1 \input texinfo @c -*- mode: texinfo; coding: utf-8 -*-
2 @comment %**start of header
3 @setfilename ../../info/eintr.info
4 @c setfilename emacs-lisp-intro.info
5 @c sethtmlfilename emacs-lisp-intro.html
6 @settitle Programming in Emacs Lisp
12 @include emacsver.texi
14 @c ================ How to Print a Book in Various Sizes ================
16 @c This book can be printed in any of three different sizes.
17 @c Set the following @-commands appropriately.
27 @c European A4 size paper:
32 @c (Note: if you edit the book so as to change the length of the
33 @c table of contents, you may have to change the value of 'pageno' below.)
35 @c <<<< For hard copy printing, this file is now
36 @c set for smallbook, which works for all sizes
37 @c of paper, and with PostScript figures >>>>
45 @c ================ Included Figures ================
47 @c If you clear this, the figures will be printed as ASCII diagrams
48 @c rather than PostScript/PDF.
49 @c (This is not relevant to Info, since Info only handles ASCII.)
50 @set print-postscript-figures
51 @c clear print-postscript-figures
53 @comment %**end of header
55 @c per rms and peterb, use 10pt fonts for the main text, mostly to
56 @c save on paper cost.
57 @c Do this inside @tex for now, so current makeinfo does not complain.
63 \global\hbadness=6666 % don't worry about not-too-underfull boxes
66 @c These refer to the printed book sold by the FSF.
67 @set edition-number 3.10
68 @set update-date 28 October 2009
70 @c For next or subsequent edition:
71 @c create function using with-output-to-temp-buffer
72 @c create a major mode, with keymaps
73 @c run an asynchronous process, like grep or diff
75 @c For 8.5 by 11 inch format: do not use such a small amount of
76 @c whitespace between paragraphs as smallbook format
79 \global\parskip 6pt plus 1pt
83 @c For all sized formats: print within-book cross
84 @c reference with ``...'' rather than [...]
86 @c This works with the texinfo.tex file, version 2003-05-04.08,
87 @c in the Texinfo version 4.6 of the 2003 Jun 13 distribution.
90 \if \xrefprintnodename
91 \global\def\xrefprintnodename#1{\unskip, ``#1''}
93 \global\def\xrefprintnodename#1{ ``#1''}
95 % \global\def\xrefprintnodename#1{, ``#1''}
98 @c ----------------------------------------------------
100 @dircategory Emacs lisp
102 * Emacs Lisp Intro: (eintr). A simple introduction to Emacs Lisp programming.
106 This is an @cite{Introduction to Programming in Emacs Lisp}, for
107 people who are not programmers.
110 Edition @value{edition-number}, @value{update-date}
113 Distributed with Emacs version @value{EMACSVER}.
116 Copyright @copyright{} 1990--1995, 1997, 2001--2015 Free Software
123 GNU Press, @hfill @uref{http://www.fsf.org/licensing/gnu-press/}@*
124 a division of the @hfill email: @email{sales@@fsf.org}@*
125 Free Software Foundation, Inc. @hfill Tel: +1 (617) 542-5942@*
126 51 Franklin Street, Fifth Floor @hfill Fax: +1 (617) 542-2652@*
127 Boston, MA 02110-1301 USA
131 Printed copies available from @uref{http://shop.fsf.org/}. Published by:
134 GNU Press, http://www.fsf.org/licensing/gnu-press/
135 a division of the email: sales@@fsf.org
136 Free Software Foundation, Inc. Tel: +1 (617) 542-5942
137 51 Franklin Street, Fifth Floor Fax: +1 (617) 542-2652
138 Boston, MA 02110-1301 USA
146 Permission is granted to copy, distribute and/or modify this document
147 under the terms of the GNU Free Documentation License, Version 1.3 or
148 any later version published by the Free Software Foundation; there
149 being no Invariant Section, with the Front-Cover Texts being ``A GNU
150 Manual'', and with the Back-Cover Texts as in (a) below. A copy of
151 the license is included in the section entitled ``GNU Free
152 Documentation License''.
154 (a) The FSF's Back-Cover Text is: ``You have the freedom to
155 copy and modify this GNU manual. Buying copies from the FSF
156 supports it in developing GNU and promoting software freedom.''
160 @c half title; two lines here, so do not use 'shorttitlepage'
163 \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}%
165 {\begingroup\hbox{}\vskip 0.25in \chaprm%
166 \centerline{Programming in Emacs Lisp}%
167 \endgroup\page\hbox{}\page}
172 @center @titlefont{An Introduction to}
174 @center @titlefont{Programming in Emacs Lisp}
176 @center Revised Third Edition
178 @center by Robert J. Chassell
181 @vskip 0pt plus 1filll
187 @evenheading @thispage @| @| @thischapter
188 @oddheading @thissection @| @| @thispage
192 @c Keep T.O.C. short by tightening up for largebook
195 \global\parskip 2pt plus 1pt
196 \global\advance\baselineskip by -1pt
206 @top An Introduction to Programming in Emacs Lisp
210 <p>The homepage for GNU Emacs is at
211 <a href="/software/emacs/">http://www.gnu.org/software/emacs/</a>.<br>
212 To view this manual in other formats, click
213 <a href="/software/emacs/manual/eintr.html">here</a>.
219 This master menu first lists each chapter and index; then it lists
220 every node in every chapter.
223 @c >>>> Set pageno appropriately <<<<
225 @c The first page of the Preface is a roman numeral; it is the first
226 @c right handed page after the Table of Contents; hence the following
227 @c setting must be for an odd negative number.
230 @c global@pageno = -11
233 @set COUNT-WORDS count-words-example
234 @c Length of variable name chosen so that things still line up when expanded.
237 * Preface:: What to look for.
238 * List Processing:: What is Lisp?
239 * Practicing Evaluation:: Running several programs.
240 * Writing Defuns:: How to write function definitions.
241 * Buffer Walk Through:: Exploring a few buffer-related functions.
242 * More Complex:: A few, even more complex functions.
243 * Narrowing & Widening:: Restricting your and Emacs attention to
245 * car cdr & cons:: Fundamental functions in Lisp.
246 * Cutting & Storing Text:: Removing text and saving it.
247 * List Implementation:: How lists are implemented in the computer.
248 * Yanking:: Pasting stored text.
249 * Loops & Recursion:: How to repeat a process.
250 * Regexp Search:: Regular expression searches.
251 * Counting Words:: A review of repetition and regexps.
252 * Words in a defun:: Counting words in a @code{defun}.
253 * Readying a Graph:: A prototype graph printing function.
254 * Emacs Initialization:: How to write a @file{.emacs} file.
255 * Debugging:: How to run the Emacs Lisp debuggers.
256 * Conclusion:: Now you have the basics.
257 * the-the:: An appendix: how to find reduplicated words.
258 * Kill Ring:: An appendix: how the kill ring works.
259 * Full Graph:: How to create a graph with labeled axes.
260 * Free Software and Free Manuals::
261 * GNU Free Documentation License::
266 --- The Detailed Node Listing ---
270 * Why:: Why learn Emacs Lisp?
271 * On Reading this Text:: Read, gain familiarity, pick up habits....
272 * Who You Are:: For whom this is written.
274 * Note for Novices:: You can read this as a novice.
279 * Lisp Lists:: What are lists?
280 * Run a Program:: Any list in Lisp is a program ready to run.
281 * Making Errors:: Generating an error message.
282 * Names & Definitions:: Names of symbols and function definitions.
283 * Lisp Interpreter:: What the Lisp interpreter does.
284 * Evaluation:: Running a program.
285 * Variables:: Returning a value from a variable.
286 * Arguments:: Passing information to a function.
287 * set & setq:: Setting the value of a variable.
288 * Summary:: The major points.
289 * Error Message Exercises::
293 * Numbers Lists:: List have numbers, other lists, in them.
294 * Lisp Atoms:: Elemental entities.
295 * Whitespace in Lists:: Formatting lists to be readable.
296 * Typing Lists:: How GNU Emacs helps you type lists.
300 * Complications:: Variables, Special forms, Lists within.
301 * Byte Compiling:: Specially processing code for speed.
305 * How the Interpreter Acts:: Returns and Side Effects...
306 * Evaluating Inner Lists:: Lists within lists...
310 * fill-column Example::
311 * Void Function:: The error message for a symbol
313 * Void Variable:: The error message for a symbol without a value.
317 * Data types:: Types of data passed to a function.
318 * Args as Variable or List:: An argument can be the value
319 of a variable or list.
320 * Variable Number of Arguments:: Some functions may take a
321 variable number of arguments.
322 * Wrong Type of Argument:: Passing an argument of the wrong type
324 * message:: A useful function for sending messages.
326 Setting the Value of a Variable
328 * Using set:: Setting values.
329 * Using setq:: Setting a quoted value.
330 * Counting:: Using @code{setq} to count.
332 Practicing Evaluation
334 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
336 * Buffer Names:: Buffers and files are different.
337 * Getting Buffers:: Getting a buffer itself, not merely its name.
338 * Switching Buffers:: How to change to another buffer.
339 * Buffer Size & Locations:: Where point is located and the size of
341 * Evaluation Exercise::
343 How To Write Function Definitions
345 * Primitive Functions::
346 * defun:: The @code{defun} macro.
347 * Install:: Install a function definition.
348 * Interactive:: Making a function interactive.
349 * Interactive Options:: Different options for @code{interactive}.
350 * Permanent Installation:: Installing code permanently.
351 * let:: Creating and initializing local variables.
353 * else:: If--then--else expressions.
354 * Truth & Falsehood:: What Lisp considers false and true.
355 * save-excursion:: Keeping track of point and buffer.
359 Install a Function Definition
361 * Effect of installation::
362 * Change a defun:: How to change a function definition.
364 Make a Function Interactive
366 * Interactive multiply-by-seven:: An overview.
367 * multiply-by-seven in detail:: The interactive version.
371 * Prevent confusion::
372 * Parts of let Expression::
373 * Sample let Expression::
374 * Uninitialized let Variables::
376 The @code{if} Special Form
378 * if in more detail::
379 * type-of-animal in detail:: An example of an @code{if} expression.
381 Truth and Falsehood in Emacs Lisp
383 * nil explained:: @code{nil} has two meanings.
385 @code{save-excursion}
387 * Point and mark:: A review of various locations.
388 * Template for save-excursion::
390 A Few Buffer-Related Functions
392 * Finding More:: How to find more information.
393 * simplified-beginning-of-buffer:: Shows @code{goto-char},
394 @code{point-min}, and @code{push-mark}.
395 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
396 * append-to-buffer:: Uses @code{save-excursion} and
397 @code{insert-buffer-substring}.
398 * Buffer Related Review:: Review.
401 The Definition of @code{mark-whole-buffer}
403 * mark-whole-buffer overview::
404 * Body of mark-whole-buffer:: Only three lines of code.
406 The Definition of @code{append-to-buffer}
408 * append-to-buffer overview::
409 * append interactive:: A two part interactive expression.
410 * append-to-buffer body:: Incorporates a @code{let} expression.
411 * append save-excursion:: How the @code{save-excursion} works.
413 A Few More Complex Functions
415 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
416 * insert-buffer:: Read-only, and with @code{or}.
417 * beginning-of-buffer:: Shows @code{goto-char},
418 @code{point-min}, and @code{push-mark}.
419 * Second Buffer Related Review::
420 * optional Exercise::
422 The Definition of @code{insert-buffer}
424 * insert-buffer code::
425 * insert-buffer interactive:: When you can read, but not write.
426 * insert-buffer body:: The body has an @code{or} and a @code{let}.
427 * if & or:: Using an @code{if} instead of an @code{or}.
428 * Insert or:: How the @code{or} expression works.
429 * Insert let:: Two @code{save-excursion} expressions.
430 * New insert-buffer::
432 The Interactive Expression in @code{insert-buffer}
434 * Read-only buffer:: When a buffer cannot be modified.
435 * b for interactive:: An existing buffer or else its name.
437 Complete Definition of @code{beginning-of-buffer}
439 * Optional Arguments::
440 * beginning-of-buffer opt arg:: Example with optional argument.
441 * beginning-of-buffer complete::
443 @code{beginning-of-buffer} with an Argument
445 * Disentangle beginning-of-buffer::
446 * Large buffer case::
447 * Small buffer case::
449 Narrowing and Widening
451 * Narrowing advantages:: The advantages of narrowing
452 * save-restriction:: The @code{save-restriction} special form.
453 * what-line:: The number of the line that point is on.
456 @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
458 * Strange Names:: An historical aside: why the strange names?
459 * car & cdr:: Functions for extracting part of a list.
460 * cons:: Constructing a list.
461 * nthcdr:: Calling @code{cdr} repeatedly.
463 * setcar:: Changing the first element of a list.
464 * setcdr:: Changing the rest of a list.
470 * length:: How to find the length of a list.
472 Cutting and Storing Text
474 * Storing Text:: Text is stored in a list.
475 * zap-to-char:: Cutting out text up to a character.
476 * kill-region:: Cutting text out of a region.
477 * copy-region-as-kill:: A definition for copying text.
478 * Digression into C:: Minor note on C programming language macros.
479 * defvar:: How to give a variable an initial value.
480 * cons & search-fwd Review::
485 * Complete zap-to-char:: The complete implementation.
486 * zap-to-char interactive:: A three part interactive expression.
487 * zap-to-char body:: A short overview.
488 * search-forward:: How to search for a string.
489 * progn:: The @code{progn} special form.
490 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
494 * Complete kill-region:: The function definition.
495 * condition-case:: Dealing with a problem.
498 @code{copy-region-as-kill}
500 * Complete copy-region-as-kill:: The complete function definition.
501 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
503 The Body of @code{copy-region-as-kill}
505 * last-command & this-command::
506 * kill-append function::
507 * kill-new function::
509 Initializing a Variable with @code{defvar}
511 * See variable current value::
512 * defvar and asterisk::
514 How Lists are Implemented
517 * Symbols as Chest:: Exploring a powerful metaphor.
522 * Kill Ring Overview::
523 * kill-ring-yank-pointer:: The kill ring is a list.
524 * yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
528 * while:: Causing a stretch of code to repeat.
530 * Recursion:: Causing a function to call itself.
535 * Looping with while:: Repeat so long as test returns true.
536 * Loop Example:: A @code{while} loop that uses a list.
537 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
538 * Incrementing Loop:: A loop with an incrementing counter.
539 * Incrementing Loop Details::
540 * Decrementing Loop:: A loop with a decrementing counter.
542 Details of an Incrementing Loop
544 * Incrementing Example:: Counting pebbles in a triangle.
545 * Inc Example parts:: The parts of the function definition.
546 * Inc Example altogether:: Putting the function definition together.
548 Loop with a Decrementing Counter
550 * Decrementing Example:: More pebbles on the beach.
551 * Dec Example parts:: The parts of the function definition.
552 * Dec Example altogether:: Putting the function definition together.
554 Save your time: @code{dolist} and @code{dotimes}
561 * Building Robots:: Same model, different serial number ...
562 * Recursive Definition Parts:: Walk until you stop ...
563 * Recursion with list:: Using a list as the test whether to recurse.
564 * Recursive triangle function::
565 * Recursion with cond::
566 * Recursive Patterns:: Often used templates.
567 * No Deferment:: Don't store up work ...
568 * No deferment solution::
570 Recursion in Place of a Counter
572 * Recursive Example arg of 1 or 2::
573 * Recursive Example arg of 3 or 4::
581 Regular Expression Searches
583 * sentence-end:: The regular expression for @code{sentence-end}.
584 * re-search-forward:: Very similar to @code{search-forward}.
585 * forward-sentence:: A straightforward example of regexp search.
586 * forward-paragraph:: A somewhat complex example.
587 * etags:: How to create your own @file{TAGS} table.
589 * re-search Exercises::
591 @code{forward-sentence}
593 * Complete forward-sentence::
594 * fwd-sentence while loops:: Two @code{while} loops.
595 * fwd-sentence re-search:: A regular expression search.
597 @code{forward-paragraph}: a Goldmine of Functions
599 * forward-paragraph in brief:: Key parts of the function definition.
600 * fwd-para let:: The @code{let*} expression.
601 * fwd-para while:: The forward motion @code{while} loop.
603 Counting: Repetition and Regexps
606 * @value{COUNT-WORDS}:: Use a regexp, but find a problem.
607 * recursive-count-words:: Start with case of no words in region.
608 * Counting Exercise::
610 The @code{@value{COUNT-WORDS}} Function
612 * Design @value{COUNT-WORDS}:: The definition using a @code{while} loop.
613 * Whitespace Bug:: The Whitespace Bug in @code{@value{COUNT-WORDS}}.
615 Counting Words in a @code{defun}
617 * Divide and Conquer::
618 * Words and Symbols:: What to count?
619 * Syntax:: What constitutes a word or symbol?
620 * count-words-in-defun:: Very like @code{@value{COUNT-WORDS}}.
621 * Several defuns:: Counting several defuns in a file.
622 * Find a File:: Do you want to look at a file?
623 * lengths-list-file:: A list of the lengths of many definitions.
624 * Several files:: Counting in definitions in different files.
625 * Several files recursively:: Recursively counting in different files.
626 * Prepare the data:: Prepare the data for display in a graph.
628 Count Words in @code{defuns} in Different Files
630 * lengths-list-many-files:: Return a list of the lengths of defuns.
631 * append:: Attach one list to another.
633 Prepare the Data for Display in a Graph
635 * Data for Display in Detail::
636 * Sorting:: Sorting lists.
637 * Files List:: Making a list of files.
638 * Counting function definitions::
642 * Columns of a graph::
643 * graph-body-print:: How to print the body of a graph.
644 * recursive-graph-body-print::
646 * Line Graph Exercise::
648 Your @file{.emacs} File
650 * Default Configuration::
651 * Site-wide Init:: You can write site-wide init files.
652 * defcustom:: Emacs will write code for you.
653 * Beginning init File:: How to write a @file{.emacs} init file.
654 * Text and Auto-fill:: Automatically wrap lines.
655 * Mail Aliases:: Use abbreviations for email addresses.
656 * Indent Tabs Mode:: Don't use tabs with @TeX{}
657 * Keybindings:: Create some personal keybindings.
658 * Keymaps:: More about key binding.
659 * Loading Files:: Load (i.e., evaluate) files automatically.
660 * Autoload:: Make functions available.
661 * Simple Extension:: Define a function; bind it to a key.
662 * X11 Colors:: Colors in X.
664 * Mode Line:: How to customize your mode line.
668 * debug:: How to use the built-in debugger.
669 * debug-on-entry:: Start debugging when you call a function.
670 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
671 * edebug:: How to use Edebug, a source level debugger.
672 * Debugging Exercises::
674 Handling the Kill Ring
676 * What the Kill Ring Does::
678 * yank:: Paste a copy of a clipped element.
679 * yank-pop:: Insert element pointed to.
682 The @code{current-kill} Function
684 * Code for current-kill::
685 * Understanding current-kill::
687 @code{current-kill} in Outline
689 * Body of current-kill::
690 * Digression concerning error:: How to mislead humans, but not computers.
691 * Determining the Element::
693 A Graph with Labeled Axes
696 * print-graph Varlist:: @code{let} expression in @code{print-graph}.
697 * print-Y-axis:: Print a label for the vertical axis.
698 * print-X-axis:: Print a horizontal label.
699 * Print Whole Graph:: The function to print a complete graph.
701 The @code{print-Y-axis} Function
703 * print-Y-axis in Detail::
704 * Height of label:: What height for the Y axis?
705 * Compute a Remainder:: How to compute the remainder of a division.
706 * Y Axis Element:: Construct a line for the Y axis.
707 * Y-axis-column:: Generate a list of Y axis labels.
708 * print-Y-axis Penultimate:: A not quite final version.
710 The @code{print-X-axis} Function
712 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
713 * X Axis Tic Marks:: Create tic marks for the horizontal axis.
715 Printing the Whole Graph
717 * The final version:: A few changes.
718 * Test print-graph:: Run a short test.
719 * Graphing words in defuns:: Executing the final code.
720 * lambda:: How to write an anonymous function.
721 * mapcar:: Apply a function to elements of a list.
722 * Another Bug:: Yet another bug @dots{} most insidious.
723 * Final printed graph:: The graph itself!
731 Most of the GNU Emacs integrated environment is written in the programming
732 language called Emacs Lisp. The code written in this programming
733 language is the software---the sets of instructions---that tell the
734 computer what to do when you give it commands. Emacs is designed so
735 that you can write new code in Emacs Lisp and easily install it as an
736 extension to the editor.
738 (GNU Emacs is sometimes called an ``extensible editor'', but it does
739 much more than provide editing capabilities. It is better to refer to
740 Emacs as an ``extensible computing environment''. However, that
741 phrase is quite a mouthful. It is easier to refer to Emacs simply as
742 an editor. Moreover, everything you do in Emacs---find the Mayan date
743 and phases of the moon, simplify polynomials, debug code, manage
744 files, read letters, write books---all these activities are kinds of
745 editing in the most general sense of the word.)
748 * Why:: Why learn Emacs Lisp?
749 * On Reading this Text:: Read, gain familiarity, pick up habits....
750 * Who You Are:: For whom this is written.
752 * Note for Novices:: You can read this as a novice.
758 @unnumberedsec Why Study Emacs Lisp?
761 Although Emacs Lisp is usually thought of in association only with Emacs,
762 it is a full computer programming language. You can use Emacs Lisp as
763 you would any other programming language.
765 Perhaps you want to understand programming; perhaps you want to extend
766 Emacs; or perhaps you want to become a programmer. This introduction to
767 Emacs Lisp is designed to get you started: to guide you in learning the
768 fundamentals of programming, and more importantly, to show you how you
769 can teach yourself to go further.
771 @node On Reading this Text
772 @unnumberedsec On Reading this Text
774 All through this document, you will see little sample programs you can
775 run inside of Emacs. If you read this document in Info inside of GNU
776 Emacs, you can run the programs as they appear. (This is easy to do and
777 is explained when the examples are presented.) Alternatively, you can
778 read this introduction as a printed book while sitting beside a computer
779 running Emacs. (This is what I like to do; I like printed books.) If
780 you don't have a running Emacs beside you, you can still read this book,
781 but in this case, it is best to treat it as a novel or as a travel guide
782 to a country not yet visited: interesting, but not the same as being
785 Much of this introduction is dedicated to walkthroughs or guided tours
786 of code used in GNU Emacs. These tours are designed for two purposes:
787 first, to give you familiarity with real, working code (code you use
788 every day); and, second, to give you familiarity with the way Emacs
789 works. It is interesting to see how a working environment is
792 hope that you will pick up the habit of browsing through source code.
793 You can learn from it and mine it for ideas. Having GNU Emacs is like
794 having a dragon's cave of treasures.
796 In addition to learning about Emacs as an editor and Emacs Lisp as a
797 programming language, the examples and guided tours will give you an
798 opportunity to get acquainted with Emacs as a Lisp programming
799 environment. GNU Emacs supports programming and provides tools that
800 you will want to become comfortable using, such as @kbd{M-.} (the key
801 which invokes the @code{find-tag} command). You will also learn about
802 buffers and other objects that are part of the environment.
803 Learning about these features of Emacs is like learning new routes
804 around your home town.
807 In addition, I have written several programs as extended examples.
808 Although these are examples, the programs are real. I use them.
809 Other people use them. You may use them. Beyond the fragments of
810 programs used for illustrations, there is very little in here that is
811 just for teaching purposes; what you see is used. This is a great
812 advantage of Emacs Lisp: it is easy to learn to use it for work.
815 Finally, I hope to convey some of the skills for using Emacs to
816 learn aspects of programming that you don't know. You can often use
817 Emacs to help you understand what puzzles you or to find out how to do
818 something new. This self-reliance is not only a pleasure, but an
822 @unnumberedsec For Whom This is Written
824 This text is written as an elementary introduction for people who are
825 not programmers. If you are a programmer, you may not be satisfied with
826 this primer. The reason is that you may have become expert at reading
827 reference manuals and be put off by the way this text is organized.
829 An expert programmer who reviewed this text said to me:
832 @i{I prefer to learn from reference manuals. I ``dive into'' each
833 paragraph, and ``come up for air'' between paragraphs.}
835 @i{When I get to the end of a paragraph, I assume that that subject is
836 done, finished, that I know everything I need (with the
837 possible exception of the case when the next paragraph starts talking
838 about it in more detail). I expect that a well written reference manual
839 will not have a lot of redundancy, and that it will have excellent
840 pointers to the (one) place where the information I want is.}
843 This introduction is not written for this person!
845 Firstly, I try to say everything at least three times: first, to
846 introduce it; second, to show it in context; and third, to show it in a
847 different context, or to review it.
849 Secondly, I hardly ever put all the information about a subject in one
850 place, much less in one paragraph. To my way of thinking, that imposes
851 too heavy a burden on the reader. Instead I try to explain only what
852 you need to know at the time. (Sometimes I include a little extra
853 information so you won't be surprised later when the additional
854 information is formally introduced.)
856 When you read this text, you are not expected to learn everything the
857 first time. Frequently, you need make only a nodding
858 acquaintance with some of the items mentioned. My hope is that I have
859 structured the text and given you enough hints that you will be alert to
860 what is important, and concentrate on it.
862 You will need to dive into some paragraphs; there is no other way
863 to read them. But I have tried to keep down the number of such
864 paragraphs. This book is intended as an approachable hill, rather than
865 as a daunting mountain.
867 This introduction to @cite{Programming in Emacs Lisp} has a companion
870 @cite{The GNU Emacs Lisp Reference Manual}.
873 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
874 Emacs Lisp Reference Manual}.
876 The reference manual has more detail than this introduction. In the
877 reference manual, all the information about one topic is concentrated
878 in one place. You should turn to it if you are like the programmer
879 quoted above. And, of course, after you have read this
880 @cite{Introduction}, you will find the @cite{Reference Manual} useful
881 when you are writing your own programs.
884 @unnumberedsec Lisp History
887 Lisp was first developed in the late 1950s at the Massachusetts
888 Institute of Technology for research in artificial intelligence. The
889 great power of the Lisp language makes it superior for other purposes as
890 well, such as writing editor commands and integrated environments.
894 GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT
895 in the 1960s. It is somewhat inspired by Common Lisp, which became a
896 standard in the 1980s. However, Emacs Lisp is much simpler than Common
897 Lisp. (The standard Emacs distribution contains an optional extensions
898 file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.)
900 @node Note for Novices
901 @unnumberedsec A Note for Novices
903 If you don't know GNU Emacs, you can still read this document
904 profitably. However, I recommend you learn Emacs, if only to learn to
905 move around your computer screen. You can teach yourself how to use
906 Emacs with the built-in tutorial. To use it, type @kbd{C-h t}. (This
907 means you press and release the @key{CTRL} key and the @kbd{h} at the
908 same time, and then press and release @kbd{t}.)
910 Also, I often refer to one of Emacs's standard commands by listing the
911 keys which you press to invoke the command and then giving the name of
912 the command in parentheses, like this: @kbd{M-C-\}
913 (@code{indent-region}). What this means is that the
914 @code{indent-region} command is customarily invoked by typing
915 @kbd{M-C-\}. (You can, if you wish, change the keys that are typed to
916 invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, ,
917 Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your
918 @key{META} key, @key{CTRL} key and @key{\} key all at the same time.
919 (On many modern keyboards the @key{META} key is labeled
921 Sometimes a combination like this is called a keychord, since it is
922 similar to the way you play a chord on a piano. If your keyboard does
923 not have a @key{META} key, the @key{ESC} key prefix is used in place
924 of it. In this case, @kbd{M-C-\} means that you press and release your
925 @key{ESC} key and then type the @key{CTRL} key and the @key{\} key at
926 the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key
927 along with the key that is labeled @key{ALT} and, at the same time,
928 press the @key{\} key.
930 In addition to typing a lone keychord, you can prefix what you type
931 with @kbd{C-u}, which is called the @dfn{universal argument}. The
932 @kbd{C-u} keychord passes an argument to the subsequent command.
933 Thus, to indent a region of plain text by 6 spaces, mark the region,
934 and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number,
935 Emacs either passes the number 4 to the command or otherwise runs the
936 command differently than it would otherwise.) @xref{Arguments, ,
937 Numeric Arguments, emacs, The GNU Emacs Manual}.
939 If you are reading this in Info using GNU Emacs, you can read through
940 this whole document just by pressing the space bar, @key{SPC}.
941 (To learn about Info, type @kbd{C-h i} and then select Info.)
943 A note on terminology: when I use the word Lisp alone, I often am
944 referring to the various dialects of Lisp in general, but when I speak
945 of Emacs Lisp, I am referring to GNU Emacs Lisp in particular.
948 @unnumberedsec Thank You
950 My thanks to all who helped me with this book. My especial thanks to
951 @r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland
952 McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.
953 Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both
954 @w{Philip Johnson} and @w{David Stampe} for their patient
955 encouragement. My mistakes are my own.
967 @c ================ Beginning of main text ================
969 @c Start main text on right-hand (verso) page
972 \par\vfill\supereject
975 \par\vfill\supereject
977 \par\vfill\supereject
979 \par\vfill\supereject
983 @c Note: this resetting of the page number back to 1 causes TeX to gripe
984 @c about already having seen page numbers 1-4 before (in the preface):
985 @c pdfTeX warning (ext4): destination with the same identifier (name{1})
986 @c has been already used, duplicate ignored
987 @c I guess that is harmless (what happens if a later part of the text
988 @c makes a link to something in the first 4 pages though?).
989 @c E.g., note that the Emacs manual has a preface, but does not bother
990 @c resetting the page numbers back to 1 after that.
993 @evenheading @thispage @| @| @thischapter
994 @oddheading @thissection @| @| @thispage
998 @node List Processing
999 @chapter List Processing
1001 To the untutored eye, Lisp is a strange programming language. In Lisp
1002 code there are parentheses everywhere. Some people even claim that
1003 the name stands for ``Lots of Isolated Silly Parentheses''. But the
1004 claim is unwarranted. Lisp stands for LISt Processing, and the
1005 programming language handles @emph{lists} (and lists of lists) by
1006 putting them between parentheses. The parentheses mark the boundaries
1007 of the list. Sometimes a list is preceded by a single apostrophe or
1008 quotation mark, @samp{'}@footnote{The single apostrophe or quotation
1009 mark is an abbreviation for the function @code{quote}; you need not
1010 think about functions now; functions are defined in @ref{Making
1011 Errors, , Generate an Error Message}.} Lists are the basis of Lisp.
1014 * Lisp Lists:: What are lists?
1015 * Run a Program:: Any list in Lisp is a program ready to run.
1016 * Making Errors:: Generating an error message.
1017 * Names & Definitions:: Names of symbols and function definitions.
1018 * Lisp Interpreter:: What the Lisp interpreter does.
1019 * Evaluation:: Running a program.
1020 * Variables:: Returning a value from a variable.
1021 * Arguments:: Passing information to a function.
1022 * set & setq:: Setting the value of a variable.
1023 * Summary:: The major points.
1024 * Error Message Exercises::
1031 In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}.
1032 This list is preceded by a single apostrophe. It could just as well be
1033 written as follows, which looks more like the kind of list you are likely
1034 to be familiar with:
1046 The elements of this list are the names of the four different flowers,
1047 separated from each other by whitespace and surrounded by parentheses,
1048 like flowers in a field with a stone wall around them.
1049 @cindex Flowers in a field
1052 * Numbers Lists:: List have numbers, other lists, in them.
1053 * Lisp Atoms:: Elemental entities.
1054 * Whitespace in Lists:: Formatting lists to be readable.
1055 * Typing Lists:: How GNU Emacs helps you type lists.
1060 @unnumberedsubsec Numbers, Lists inside of Lists
1063 Lists can also have numbers in them, as in this list: @code{(+ 2 2)}.
1064 This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each
1065 separated by whitespace.
1067 In Lisp, both data and programs are represented the same way; that is,
1068 they are both lists of words, numbers, or other lists, separated by
1069 whitespace and surrounded by parentheses. (Since a program looks like
1070 data, one program may easily serve as data for another; this is a very
1071 powerful feature of Lisp.) (Incidentally, these two parenthetical
1072 remarks are @emph{not} Lisp lists, because they contain @samp{;} and
1073 @samp{.} as punctuation marks.)
1076 Here is another list, this time with a list inside of it:
1079 '(this list has (a list inside of it))
1082 The components of this list are the words @samp{this}, @samp{list},
1083 @samp{has}, and the list @samp{(a list inside of it)}. The interior
1084 list is made up of the words @samp{a}, @samp{list}, @samp{inside},
1085 @samp{of}, @samp{it}.
1088 @subsection Lisp Atoms
1091 In Lisp, what we have been calling words are called @dfn{atoms}. This
1092 term comes from the historical meaning of the word atom, which means
1093 ``indivisible''. As far as Lisp is concerned, the words we have been
1094 using in the lists cannot be divided into any smaller parts and still
1095 mean the same thing as part of a program; likewise with numbers and
1096 single character symbols like @samp{+}. On the other hand, unlike an
1097 ancient atom, a list can be split into parts. (@xref{car cdr & cons,
1098 , @code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
1100 In a list, atoms are separated from each other by whitespace. They can be
1101 right next to a parenthesis.
1103 @cindex @samp{empty list} defined
1104 Technically speaking, a list in Lisp consists of parentheses surrounding
1105 atoms separated by whitespace or surrounding other lists or surrounding
1106 both atoms and other lists. A list can have just one atom in it or
1107 have nothing in it at all. A list with nothing in it looks like this:
1108 @code{()}, and is called the @dfn{empty list}. Unlike anything else, an
1109 empty list is considered both an atom and a list at the same time.
1111 @cindex Symbolic expressions, introduced
1112 @cindex @samp{expression} defined
1113 @cindex @samp{form} defined
1114 The printed representation of both atoms and lists are called
1115 @dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}.
1116 The word @dfn{expression} by itself can refer to either the printed
1117 representation, or to the atom or list as it is held internally in the
1118 computer. Often, people use the term @dfn{expression}
1119 indiscriminately. (Also, in many texts, the word @dfn{form} is used
1120 as a synonym for expression.)
1122 Incidentally, the atoms that make up our universe were named such when
1123 they were thought to be indivisible; but it has been found that physical
1124 atoms are not indivisible. Parts can split off an atom or it can
1125 fission into two parts of roughly equal size. Physical atoms were named
1126 prematurely, before their truer nature was found. In Lisp, certain
1127 kinds of atom, such as an array, can be separated into parts; but the
1128 mechanism for doing this is different from the mechanism for splitting a
1129 list. As far as list operations are concerned, the atoms of a list are
1132 As in English, the meanings of the component letters of a Lisp atom
1133 are different from the meaning the letters make as a word. For
1134 example, the word for the South American sloth, the @samp{ai}, is
1135 completely different from the two words, @samp{a}, and @samp{i}.
1137 There are many kinds of atom in nature but only a few in Lisp: for
1138 example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such
1139 as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have
1140 listed in the examples above are all symbols. In everyday Lisp
1141 conversation, the word ``atom'' is not often used, because programmers
1142 usually try to be more specific about what kind of atom they are dealing
1143 with. Lisp programming is mostly about symbols (and sometimes numbers)
1144 within lists. (Incidentally, the preceding three word parenthetical
1145 remark is a proper list in Lisp, since it consists of atoms, which in
1146 this case are symbols, separated by whitespace and enclosed by
1147 parentheses, without any non-Lisp punctuation.)
1150 Text between double quotation marks---even sentences or
1151 paragraphs---is also an atom. Here is an example:
1152 @cindex Text between double quotation marks
1155 '(this list includes "text between quotation marks.")
1158 @cindex @samp{string} defined
1160 In Lisp, all of the quoted text including the punctuation mark and the
1161 blank spaces is a single atom. This kind of atom is called a
1162 @dfn{string} (for ``string of characters'') and is the sort of thing that
1163 is used for messages that a computer can print for a human to read.
1164 Strings are a different kind of atom than numbers or symbols and are
1167 @node Whitespace in Lists
1168 @subsection Whitespace in Lists
1169 @cindex Whitespace in lists
1172 The amount of whitespace in a list does not matter. From the point of view
1173 of the Lisp language,
1184 is exactly the same as this:
1187 '(this list looks like this)
1190 Both examples show what to Lisp is the same list, the list made up of
1191 the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and
1192 @samp{this} in that order.
1194 Extra whitespace and newlines are designed to make a list more readable
1195 by humans. When Lisp reads the expression, it gets rid of all the extra
1196 whitespace (but it needs to have at least one space between atoms in
1197 order to tell them apart.)
1199 Odd as it seems, the examples we have seen cover almost all of what Lisp
1200 lists look like! Every other list in Lisp looks more or less like one
1201 of these examples, except that the list may be longer and more complex.
1202 In brief, a list is between parentheses, a string is between quotation
1203 marks, a symbol looks like a word, and a number looks like a number.
1204 (For certain situations, square brackets, dots and a few other special
1205 characters may be used; however, we will go quite far without them.)
1208 @subsection GNU Emacs Helps You Type Lists
1209 @cindex Help typing lists
1210 @cindex Formatting help
1212 When you type a Lisp expression in GNU Emacs using either Lisp
1213 Interaction mode or Emacs Lisp mode, you have available to you several
1214 commands to format the Lisp expression so it is easy to read. For
1215 example, pressing the @key{TAB} key automatically indents the line the
1216 cursor is on by the right amount. A command to properly indent the
1217 code in a region is customarily bound to @kbd{M-C-\}. Indentation is
1218 designed so that you can see which elements of a list belong to which
1219 list---elements of a sub-list are indented more than the elements of
1222 In addition, when you type a closing parenthesis, Emacs momentarily
1223 jumps the cursor back to the matching opening parenthesis, so you can
1224 see which one it is. This is very useful, since every list you type
1225 in Lisp must have its closing parenthesis match its opening
1226 parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs
1227 Manual}, for more information about Emacs's modes.)
1230 @section Run a Program
1231 @cindex Run a program
1232 @cindex Program, running one
1234 @cindex @samp{evaluate} defined
1235 A list in Lisp---any list---is a program ready to run. If you run it
1236 (for which the Lisp jargon is @dfn{evaluate}), the computer will do one
1237 of three things: do nothing except return to you the list itself; send
1238 you an error message; or, treat the first symbol in the list as a
1239 command to do something. (Usually, of course, it is the last of these
1240 three things that you really want!)
1242 @c use code for the single apostrophe, not samp.
1244 @cindex @code{'} for quoting
1245 @cindex quoting using apostrophe
1246 @cindex apostrophe for quoting
1247 The single apostrophe, @code{'}, that I put in front of some of the
1248 example lists in preceding sections is called a @dfn{quote}; when it
1249 precedes a list, it tells Lisp to do nothing with the list, other than
1250 take it as it is written. But if there is no quote preceding a list,
1251 the first item of the list is special: it is a command for the computer
1252 to obey. (In Lisp, these commands are called @emph{functions}.) The list
1253 @code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp
1254 understands that the @code{+} is an instruction to do something with the
1255 rest of the list: add the numbers that follow.
1258 If you are reading this inside of GNU Emacs in Info, here is how you can
1259 evaluate such a list: place your cursor immediately after the right
1260 hand parenthesis of the following list and then type @kbd{C-x C-e}:
1266 @c use code for the number four, not samp.
1268 You will see the number @code{4} appear in the echo area. (What
1269 you have just done is evaluate the list. The echo area
1270 is the line at the bottom of the screen that displays or echoes
1271 text.) Now try the same thing with a quoted list: place the cursor
1272 right after the following list and type @kbd{C-x C-e}:
1275 '(this is a quoted list)
1279 You will see @code{(this is a quoted list)} appear in the echo area.
1281 @cindex Lisp interpreter, explained
1282 @cindex Interpreter, Lisp, explained
1283 In both cases, what you are doing is giving a command to the program
1284 inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the
1285 interpreter a command to evaluate the expression. The name of the Lisp
1286 interpreter comes from the word for the task done by a human who comes
1287 up with the meaning of an expression---who interprets it.
1289 You can also evaluate an atom that is not part of a list---one that is
1290 not surrounded by parentheses; again, the Lisp interpreter translates
1291 from the humanly readable expression to the language of the computer.
1292 But before discussing this (@pxref{Variables}), we will discuss what the
1293 Lisp interpreter does when you make an error.
1296 @section Generate an Error Message
1297 @cindex Generate an error message
1298 @cindex Error message generation
1300 Partly so you won't worry if you do it accidentally, we will now give
1301 a command to the Lisp interpreter that generates an error message.
1302 This is a harmless activity; and indeed, we will often try to generate
1303 error messages intentionally. Once you understand the jargon, error
1304 messages can be informative. Instead of being called ``error''
1305 messages, they should be called ``help'' messages. They are like
1306 signposts to a traveler in a strange country; deciphering them can be
1307 hard, but once understood, they can point the way.
1309 The error message is generated by a built-in GNU Emacs debugger. We
1310 will enter the debugger. You get out of the debugger by typing @code{q}.
1312 What we will do is evaluate a list that is not quoted and does not
1313 have a meaningful command as its first element. Here is a list almost
1314 exactly the same as the one we just used, but without the single-quote
1315 in front of it. Position the cursor right after it and type @kbd{C-x
1319 (this is an unquoted list)
1324 What you see depends on which version of Emacs you are running. GNU
1325 Emacs version 22 provides more information than version 20 and before.
1326 First, the more recent result of generating an error; then the
1327 earlier, version 20 result.
1331 In GNU Emacs version 22, a @file{*Backtrace*} window will open up and
1332 you will see the following in it:
1335 A @file{*Backtrace*} window will open up and you should see the
1340 ---------- Buffer: *Backtrace* ----------
1341 Debugger entered--Lisp error: (void-function this)
1342 (this is an unquoted list)
1343 eval((this is an unquoted list))
1344 eval-last-sexp-1(nil)
1346 call-interactively(eval-last-sexp)
1347 ---------- Buffer: *Backtrace* ----------
1353 Your cursor will be in this window (you may have to wait a few seconds
1354 before it becomes visible). To quit the debugger and make the
1355 debugger window go away, type:
1362 Please type @kbd{q} right now, so you become confident that you can
1363 get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter
1366 @cindex @samp{function} defined
1367 Based on what we already know, we can almost read this error message.
1369 You read the @file{*Backtrace*} buffer from the bottom up; it tells
1370 you what Emacs did. When you typed @kbd{C-x C-e}, you made an
1371 interactive call to the command @code{eval-last-sexp}. @code{eval} is
1372 an abbreviation for ``evaluate'' and @code{sexp} is an abbreviation for
1373 ``symbolic expression''. The command means ``evaluate last symbolic
1374 expression'', which is the expression just before your cursor.
1376 Each line above tells you what the Lisp interpreter evaluated next.
1377 The most recent action is at the top. The buffer is called the
1378 @file{*Backtrace*} buffer because it enables you to track Emacs
1382 At the top of the @file{*Backtrace*} buffer, you see the line:
1385 Debugger entered--Lisp error: (void-function this)
1389 The Lisp interpreter tried to evaluate the first atom of the list, the
1390 word @samp{this}. It is this action that generated the error message
1391 @samp{void-function this}.
1393 The message contains the words @samp{void-function} and @samp{this}.
1395 @cindex @samp{function} defined
1396 The word @samp{function} was mentioned once before. It is a very
1397 important word. For our purposes, we can define it by saying that a
1398 @dfn{function} is a set of instructions to the computer that tell the
1399 computer to do something.
1401 Now we can begin to understand the error message: @samp{void-function
1402 this}. The function (that is, the word @samp{this}) does not have a
1403 definition of any set of instructions for the computer to carry out.
1405 The slightly odd word, @samp{void-function}, is designed to cover the
1406 way Emacs Lisp is implemented, which is that when a symbol does not
1407 have a function definition attached to it, the place that should
1408 contain the instructions is void.
1410 On the other hand, since we were able to add 2 plus 2 successfully, by
1411 evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must
1412 have a set of instructions for the computer to obey and those
1413 instructions must be to add the numbers that follow the @code{+}.
1415 It is possible to prevent Emacs entering the debugger in cases like
1416 this. We do not explain how to do that here, but we will mention what
1417 the result looks like, because you may encounter a similar situation
1418 if there is a bug in some Emacs code that you are using. In such
1419 cases, you will see only one line of error message; it will appear in
1420 the echo area and look like this:
1423 Symbol's function definition is void:@: this
1428 (Also, your terminal may beep at you---some do, some don't; and others
1429 blink. This is just a device to get your attention.)
1431 The message goes away as soon as you type a key, even just to
1434 We know the meaning of the word @samp{Symbol}. It refers to the first
1435 atom of the list, the word @samp{this}. The word @samp{function}
1436 refers to the instructions that tell the computer what to do.
1437 (Technically, the symbol tells the computer where to find the
1438 instructions, but this is a complication we can ignore for the
1441 The error message can be understood: @samp{Symbol's function
1442 definition is void:@: this}. The symbol (that is, the word
1443 @samp{this}) lacks instructions for the computer to carry out.
1445 @node Names & Definitions
1446 @section Symbol Names and Function Definitions
1447 @cindex Symbol names
1449 We can articulate another characteristic of Lisp based on what we have
1450 discussed so far---an important characteristic: a symbol, like
1451 @code{+}, is not itself the set of instructions for the computer to
1452 carry out. Instead, the symbol is used, perhaps temporarily, as a way
1453 of locating the definition or set of instructions. What we see is the
1454 name through which the instructions can be found. Names of people
1455 work the same way. I can be referred to as @samp{Bob}; however, I am
1456 not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the
1457 consciousness consistently associated with a particular life-form.
1458 The name is not me, but it can be used to refer to me.
1460 In Lisp, one set of instructions can be attached to several names.
1461 For example, the computer instructions for adding numbers can be
1462 linked to the symbol @code{plus} as well as to the symbol @code{+}
1463 (and are in some dialects of Lisp). Among humans, I can be referred
1464 to as @samp{Robert} as well as @samp{Bob} and by other words as well.
1466 On the other hand, a symbol can have only one function definition
1467 attached to it at a time. Otherwise, the computer would be confused as
1468 to which definition to use. If this were the case among people, only
1469 one person in the world could be named @samp{Bob}. However, the function
1470 definition to which the name refers can be changed readily.
1471 (@xref{Install, , Install a Function Definition}.)
1473 Since Emacs Lisp is large, it is customary to name symbols in a way
1474 that identifies the part of Emacs to which the function belongs.
1475 Thus, all the names for functions that deal with Texinfo start with
1476 @samp{texinfo-} and those for functions that deal with reading mail
1477 start with @samp{rmail-}.
1479 @node Lisp Interpreter
1480 @section The Lisp Interpreter
1481 @cindex Lisp interpreter, what it does
1482 @cindex Interpreter, what it does
1484 Based on what we have seen, we can now start to figure out what the
1485 Lisp interpreter does when we command it to evaluate a list.
1486 First, it looks to see whether there is a quote before the list; if
1487 there is, the interpreter just gives us the list. On the other
1488 hand, if there is no quote, the interpreter looks at the first element
1489 in the list and sees whether it has a function definition. If it does,
1490 the interpreter carries out the instructions in the function definition.
1491 Otherwise, the interpreter prints an error message.
1493 This is how Lisp works. Simple. There are added complications which we
1494 will get to in a minute, but these are the fundamentals. Of course, to
1495 write Lisp programs, you need to know how to write function definitions
1496 and attach them to names, and how to do this without confusing either
1497 yourself or the computer.
1500 * Complications:: Variables, Special forms, Lists within.
1501 * Byte Compiling:: Specially processing code for speed.
1506 @unnumberedsubsec Complications
1509 Now, for the first complication. In addition to lists, the Lisp
1510 interpreter can evaluate a symbol that is not quoted and does not have
1511 parentheses around it. The Lisp interpreter will attempt to determine
1512 the symbol's value as a @dfn{variable}. This situation is described
1513 in the section on variables. (@xref{Variables}.)
1515 @cindex Special form
1516 The second complication occurs because some functions are unusual and
1517 do not work in the usual manner. Those that don't are called
1518 @dfn{special forms}. They are used for special jobs, like defining a
1519 function, and there are not many of them. In the next few chapters,
1520 you will be introduced to several of the more important special forms.
1522 As well as special forms, there are also @dfn{macros}. A macro
1523 is a construct defined in Lisp, which differs from a function in that it
1524 translates a Lisp expression into another expression that is to be
1525 evaluated in place of the original expression. (@xref{Lisp macro}.)
1527 For the purposes of this introduction, you do not need to worry too much
1528 about whether something is a special form, macro, or ordinary function.
1529 For example, @code{if} is a special form (@pxref{if}), but @code{when}
1530 is a macro (@pxref{Lisp macro}). In earlier versions of Emacs,
1531 @code{defun} was a special form, but now it is a macro (@pxref{defun}).
1532 It still behaves in the same way.
1534 The final complication is this: if the function that the
1535 Lisp interpreter is looking at is not a special form, and if it is part
1536 of a list, the Lisp interpreter looks to see whether the list has a list
1537 inside of it. If there is an inner list, the Lisp interpreter first
1538 figures out what it should do with the inside list, and then it works on
1539 the outside list. If there is yet another list embedded inside the
1540 inner list, it works on that one first, and so on. It always works on
1541 the innermost list first. The interpreter works on the innermost list
1542 first, to evaluate the result of that list. The result may be
1543 used by the enclosing expression.
1545 Otherwise, the interpreter works left to right, from one expression to
1548 @node Byte Compiling
1549 @subsection Byte Compiling
1550 @cindex Byte compiling
1552 One other aspect of interpreting: the Lisp interpreter is able to
1553 interpret two kinds of entity: humanly readable code, on which we will
1554 focus exclusively, and specially processed code, called @dfn{byte
1555 compiled} code, which is not humanly readable. Byte compiled code
1556 runs faster than humanly readable code.
1558 You can transform humanly readable code into byte compiled code by
1559 running one of the compile commands such as @code{byte-compile-file}.
1560 Byte compiled code is usually stored in a file that ends with a
1561 @file{.elc} extension rather than a @file{.el} extension. You will
1562 see both kinds of file in the @file{emacs/lisp} directory; the files
1563 to read are those with @file{.el} extensions.
1565 As a practical matter, for most things you might do to customize or
1566 extend Emacs, you do not need to byte compile; and I will not discuss
1567 the topic here. @xref{Byte Compilation, , Byte Compilation, elisp,
1568 The GNU Emacs Lisp Reference Manual}, for a full description of byte
1575 When the Lisp interpreter works on an expression, the term for the
1576 activity is called @dfn{evaluation}. We say that the interpreter
1577 ``evaluates the expression''. I've used this term several times before.
1578 The word comes from its use in everyday language, ``to ascertain the
1579 value or amount of; to appraise'', according to @cite{Webster's New
1580 Collegiate Dictionary}.
1583 * How the Interpreter Acts:: Returns and Side Effects...
1584 * Evaluating Inner Lists:: Lists within lists...
1588 @node How the Interpreter Acts
1589 @unnumberedsubsec How the Lisp Interpreter Acts
1592 @cindex @samp{returned value} explained
1593 After evaluating an expression, the Lisp interpreter will most likely
1594 @dfn{return} the value that the computer produces by carrying out the
1595 instructions it found in the function definition, or perhaps it will
1596 give up on that function and produce an error message. (The interpreter
1597 may also find itself tossed, so to speak, to a different function or it
1598 may attempt to repeat continually what it is doing for ever and ever in
1599 an infinite loop. These actions are less common; and
1600 we can ignore them.) Most frequently, the interpreter returns a value.
1602 @cindex @samp{side effect} defined
1603 At the same time the interpreter returns a value, it may do something
1604 else as well, such as move a cursor or copy a file; this other kind of
1605 action is called a @dfn{side effect}. Actions that we humans think are
1606 important, such as printing results, are often side effects to the
1607 Lisp interpreter. It is fairly easy to learn to use side effects.
1609 In summary, evaluating a symbolic expression most commonly causes the
1610 Lisp interpreter to return a value and perhaps carry out a side effect;
1611 or else produce an error.
1613 @node Evaluating Inner Lists
1614 @subsection Evaluating Inner Lists
1615 @cindex Inner list evaluation
1616 @cindex Evaluating inner lists
1618 If evaluation applies to a list that is inside another list, the outer
1619 list may use the value returned by the first evaluation as information
1620 when the outer list is evaluated. This explains why inner expressions
1621 are evaluated first: the values they return are used by the outer
1625 We can investigate this process by evaluating another addition example.
1626 Place your cursor after the following expression and type @kbd{C-x C-e}:
1633 The number 8 will appear in the echo area.
1635 What happens is that the Lisp interpreter first evaluates the inner
1636 expression, @code{(+ 3 3)}, for which the value 6 is returned; then it
1637 evaluates the outer expression as if it were written @code{(+ 2 6)}, which
1638 returns the value 8. Since there are no more enclosing expressions to
1639 evaluate, the interpreter prints that value in the echo area.
1641 Now it is easy to understand the name of the command invoked by the
1642 keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The
1643 letters @code{sexp} are an abbreviation for ``symbolic expression'', and
1644 @code{eval} is an abbreviation for ``evaluate''. The command
1645 evaluates the last symbolic expression.
1647 As an experiment, you can try evaluating the expression by putting the
1648 cursor at the beginning of the next line immediately following the
1649 expression, or inside the expression.
1652 Here is another copy of the expression:
1659 If you place the cursor at the beginning of the blank line that
1660 immediately follows the expression and type @kbd{C-x C-e}, you will
1661 still get the value 8 printed in the echo area. Now try putting the
1662 cursor inside the expression. If you put it right after the next to
1663 last parenthesis (so it appears to sit on top of the last parenthesis),
1664 you will get a 6 printed in the echo area! This is because the command
1665 evaluates the expression @code{(+ 3 3)}.
1667 Now put the cursor immediately after a number. Type @kbd{C-x C-e} and
1668 you will get the number itself. In Lisp, if you evaluate a number, you
1669 get the number itself---this is how numbers differ from symbols. If you
1670 evaluate a list starting with a symbol like @code{+}, you will get a
1671 value returned that is the result of the computer carrying out the
1672 instructions in the function definition attached to that name. If a
1673 symbol by itself is evaluated, something different happens, as we will
1674 see in the next section.
1680 In Emacs Lisp, a symbol can have a value attached to it just as it can
1681 have a function definition attached to it. The two are different.
1682 The function definition is a set of instructions that a computer will
1683 obey. A value, on the other hand, is something, such as number or a
1684 name, that can vary (which is why such a symbol is called a variable).
1685 The value of a symbol can be any expression in Lisp, such as a symbol,
1686 number, list, or string. A symbol that has a value is often called a
1689 A symbol can have both a function definition and a value attached to
1690 it at the same time. Or it can have just one or the other.
1691 The two are separate. This is somewhat similar
1692 to the way the name Cambridge can refer to the city in Massachusetts
1693 and have some information attached to the name as well, such as
1694 ``great programming center''.
1697 (Incidentally, in Emacs Lisp, a symbol can have two
1698 other things attached to it, too: a property list and a documentation
1699 string; these are discussed later.)
1702 Another way to think about this is to imagine a symbol as being a chest
1703 of drawers. The function definition is put in one drawer, the value in
1704 another, and so on. What is put in the drawer holding the value can be
1705 changed without affecting the contents of the drawer holding the
1706 function definition, and vice versa.
1709 * fill-column Example::
1710 * Void Function:: The error message for a symbol
1712 * Void Variable:: The error message for a symbol without a value.
1716 @node fill-column Example
1717 @unnumberedsubsec @code{fill-column}, an Example Variable
1720 @findex fill-column, @r{an example variable}
1721 @cindex Example variable, @code{fill-column}
1722 @cindex Variable, example of, @code{fill-column}
1723 The variable @code{fill-column} illustrates a symbol with a value
1724 attached to it: in every GNU Emacs buffer, this symbol is set to some
1725 value, usually 72 or 70, but sometimes to some other value. To find the
1726 value of this symbol, evaluate it by itself. If you are reading this in
1727 Info inside of GNU Emacs, you can do this by putting the cursor after
1728 the symbol and typing @kbd{C-x C-e}:
1735 After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo
1736 area. This is the value for which @code{fill-column} is set for me as I
1737 write this. It may be different for you in your Info buffer. Notice
1738 that the value returned as a variable is printed in exactly the same way
1739 as the value returned by a function carrying out its instructions. From
1740 the point of view of the Lisp interpreter, a value returned is a value
1741 returned. What kind of expression it came from ceases to matter once
1744 A symbol can have any value attached to it or, to use the jargon, we can
1745 @dfn{bind} the variable to a value: to a number, such as 72; to a
1746 string, @code{"such as this"}; to a list, such as @code{(spruce pine
1747 oak)}; we can even bind a variable to a function definition.
1749 A symbol can be bound to a value in several ways. @xref{set & setq, ,
1750 Setting the Value of a Variable}, for information about one way to do
1754 @subsection Error Message for a Symbol Without a Function
1755 @cindex Symbol without function error
1756 @cindex Error for symbol without function
1758 When we evaluated @code{fill-column} to find its value as a variable,
1759 we did not place parentheses around the word. This is because we did
1760 not intend to use it as a function name.
1762 If @code{fill-column} were the first or only element of a list, the
1763 Lisp interpreter would attempt to find the function definition
1764 attached to it. But @code{fill-column} has no function definition.
1765 Try evaluating this:
1773 You will create a @file{*Backtrace*} buffer that says:
1777 ---------- Buffer: *Backtrace* ----------
1778 Debugger entered--Lisp error: (void-function fill-column)
1781 eval-last-sexp-1(nil)
1783 call-interactively(eval-last-sexp)
1784 ---------- Buffer: *Backtrace* ----------
1789 (Remember, to quit the debugger and make the debugger window go away,
1790 type @kbd{q} in the @file{*Backtrace*} buffer.)
1794 In GNU Emacs 20 and before, you will produce an error message that says:
1797 Symbol's function definition is void:@: fill-column
1801 (The message will go away as soon as you move the cursor or type
1806 @subsection Error Message for a Symbol Without a Value
1807 @cindex Symbol without value error
1808 @cindex Error for symbol without value
1810 If you attempt to evaluate a symbol that does not have a value bound to
1811 it, you will receive an error message. You can see this by
1812 experimenting with our 2 plus 2 addition. In the following expression,
1813 put your cursor right after the @code{+}, before the first number 2,
1822 In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that
1827 ---------- Buffer: *Backtrace* ----------
1828 Debugger entered--Lisp error: (void-variable +)
1830 eval-last-sexp-1(nil)
1832 call-interactively(eval-last-sexp)
1833 ---------- Buffer: *Backtrace* ----------
1838 (Again, you can quit the debugger by
1839 typing @kbd{q} in the @file{*Backtrace*} buffer.)
1841 This backtrace is different from the very first error message we saw,
1842 which said, @samp{Debugger entered--Lisp error: (void-function this)}.
1843 In this case, the function does not have a value as a variable; while
1844 in the other error message, the function (the word @samp{this}) did not
1847 In this experiment with the @code{+}, what we did was cause the Lisp
1848 interpreter to evaluate the @code{+} and look for the value of the
1849 variable instead of the function definition. We did this by placing the
1850 cursor right after the symbol rather than after the parenthesis of the
1851 enclosing list as we did before. As a consequence, the Lisp interpreter
1852 evaluated the preceding s-expression, which in this case was
1855 Since @code{+} does not have a value bound to it, just the function
1856 definition, the error message reported that the symbol's value as a
1861 In GNU Emacs version 20 and before, your error message will say:
1864 Symbol's value as variable is void:@: +
1868 The meaning is the same as in GNU Emacs 22.
1874 @cindex Passing information to functions
1876 To see how information is passed to functions, let's look again at
1877 our old standby, the addition of two plus two. In Lisp, this is written
1884 If you evaluate this expression, the number 4 will appear in your echo
1885 area. What the Lisp interpreter does is add the numbers that follow
1888 @cindex @samp{argument} defined
1889 The numbers added by @code{+} are called the @dfn{arguments} of the
1890 function @code{+}. These numbers are the information that is given to
1891 or @dfn{passed} to the function.
1893 The word ``argument'' comes from the way it is used in mathematics and
1894 does not refer to a disputation between two people; instead it refers to
1895 the information presented to the function, in this case, to the
1896 @code{+}. In Lisp, the arguments to a function are the atoms or lists
1897 that follow the function. The values returned by the evaluation of
1898 these atoms or lists are passed to the function. Different functions
1899 require different numbers of arguments; some functions require none at
1900 all.@footnote{It is curious to track the path by which the word ``argument''
1901 came to have two different meanings, one in mathematics and the other in
1902 everyday English. According to the @cite{Oxford English Dictionary},
1903 the word derives from the Latin for @samp{to make clear, prove}; thus it
1904 came to mean, by one thread of derivation, ``the evidence offered as
1905 proof'', which is to say, ``the information offered'', which led to its
1906 meaning in Lisp. But in the other thread of derivation, it came to mean
1907 ``to assert in a manner against which others may make counter
1908 assertions'', which led to the meaning of the word as a disputation.
1909 (Note here that the English word has two different definitions attached
1910 to it at the same time. By contrast, in Emacs Lisp, a symbol cannot
1911 have two different function definitions at the same time.)}
1914 * Data types:: Types of data passed to a function.
1915 * Args as Variable or List:: An argument can be the value
1916 of a variable or list.
1917 * Variable Number of Arguments:: Some functions may take a
1918 variable number of arguments.
1919 * Wrong Type of Argument:: Passing an argument of the wrong type
1921 * message:: A useful function for sending messages.
1925 @subsection Arguments' Data Types
1927 @cindex Types of data
1928 @cindex Arguments' data types
1930 The type of data that should be passed to a function depends on what
1931 kind of information it uses. The arguments to a function such as
1932 @code{+} must have values that are numbers, since @code{+} adds numbers.
1933 Other functions use different kinds of data for their arguments.
1937 For example, the @code{concat} function links together or unites two or
1938 more strings of text to produce a string. The arguments are strings.
1939 Concatenating the two character strings @code{abc}, @code{def} produces
1940 the single string @code{abcdef}. This can be seen by evaluating the
1944 (concat "abc" "def")
1948 The value produced by evaluating this expression is @code{"abcdef"}.
1951 A function such as @code{substring} uses both a string and numbers as
1952 arguments. The function returns a part of the string, a @dfn{substring} of
1953 the first argument. This function takes three arguments. Its first
1954 argument is the string of characters, the second and third arguments
1955 are numbers that indicate the beginning (inclusive) and end
1956 (exclusive) of the substring. The numbers are a count of the number
1957 of characters (including spaces and punctuation) from the beginning of
1958 the string. Note that the characters in a string are numbered from
1962 For example, if you evaluate the following:
1965 (substring "The quick brown fox jumped." 16 19)
1969 you will see @code{"fox"} appear in the echo area. The arguments are the
1970 string and the two numbers.
1972 Note that the string passed to @code{substring} is a single atom even
1973 though it is made up of several words separated by spaces. Lisp counts
1974 everything between the two quotation marks as part of the string,
1975 including the spaces. You can think of the @code{substring} function as
1976 a kind of atom smasher since it takes an otherwise indivisible atom
1977 and extracts a part. However, @code{substring} is only able to extract
1978 a substring from an argument that is a string, not from another type of
1979 atom such as a number or symbol.
1981 @node Args as Variable or List
1982 @subsection An Argument as the Value of a Variable or List
1984 An argument can be a symbol that returns a value when it is evaluated.
1985 For example, when the symbol @code{fill-column} by itself is evaluated,
1986 it returns a number. This number can be used in an addition.
1989 Position the cursor after the following expression and type @kbd{C-x
1997 The value will be a number two more than what you get by evaluating
1998 @code{fill-column} alone. For me, this is 74, because my value of
1999 @code{fill-column} is 72.
2001 As we have just seen, an argument can be a symbol that returns a value
2002 when evaluated. In addition, an argument can be a list that returns a
2003 value when it is evaluated. For example, in the following expression,
2004 the arguments to the function @code{concat} are the strings
2005 @w{@code{"The "}} and @w{@code{" red foxes."}} and the list
2006 @code{(number-to-string (+ 2 fill-column))}.
2008 @c For GNU Emacs 22, need number-to-string
2010 (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
2014 If you evaluate this expression---and if, as with my Emacs,
2015 @code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will
2016 appear in the echo area. (Note that you must put spaces after the
2017 word @samp{The} and before the word @samp{red} so they will appear in
2018 the final string. The function @code{number-to-string} converts the
2019 integer that the addition function returns to a string.
2020 @code{number-to-string} is also known as @code{int-to-string}.)
2022 @node Variable Number of Arguments
2023 @subsection Variable Number of Arguments
2024 @cindex Variable number of arguments
2025 @cindex Arguments, variable number of
2027 Some functions, such as @code{concat}, @code{+} or @code{*}, take any
2028 number of arguments. (The @code{*} is the symbol for multiplication.)
2029 This can be seen by evaluating each of the following expressions in
2030 the usual way. What you will see in the echo area is printed in this
2031 text after @samp{@result{}}, which you may read as ``evaluates to''.
2034 In the first set, the functions have no arguments:
2045 In this set, the functions have one argument each:
2056 In this set, the functions have three arguments each:
2060 (+ 3 4 5) @result{} 12
2062 (* 3 4 5) @result{} 60
2066 @node Wrong Type of Argument
2067 @subsection Using the Wrong Type Object as an Argument
2068 @cindex Wrong type of argument
2069 @cindex Argument, wrong type of
2071 When a function is passed an argument of the wrong type, the Lisp
2072 interpreter produces an error message. For example, the @code{+}
2073 function expects the values of its arguments to be numbers. As an
2074 experiment we can pass it the quoted symbol @code{hello} instead of a
2075 number. Position the cursor after the following expression and type
2083 When you do this you will generate an error message. What has happened
2084 is that @code{+} has tried to add the 2 to the value returned by
2085 @code{'hello}, but the value returned by @code{'hello} is the symbol
2086 @code{hello}, not a number. Only numbers can be added. So @code{+}
2087 could not carry out its addition.
2090 You will create and enter a @file{*Backtrace*} buffer that says:
2095 ---------- Buffer: *Backtrace* ----------
2096 Debugger entered--Lisp error:
2097 (wrong-type-argument number-or-marker-p hello)
2099 eval((+ 2 (quote hello)))
2100 eval-last-sexp-1(nil)
2102 call-interactively(eval-last-sexp)
2103 ---------- Buffer: *Backtrace* ----------
2108 As usual, the error message tries to be helpful and makes sense after you
2109 learn how to read it.@footnote{@code{(quote hello)} is an expansion of
2110 the abbreviation @code{'hello}.}
2112 The first part of the error message is straightforward; it says
2113 @samp{wrong type argument}. Next comes the mysterious jargon word
2114 @w{@samp{number-or-marker-p}}. This word is trying to tell you what
2115 kind of argument the @code{+} expected.
2117 The symbol @code{number-or-marker-p} says that the Lisp interpreter is
2118 trying to determine whether the information presented it (the value of
2119 the argument) is a number or a marker (a special object representing a
2120 buffer position). What it does is test to see whether the @code{+} is
2121 being given numbers to add. It also tests to see whether the
2122 argument is something called a marker, which is a specific feature of
2123 Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers.
2124 When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command,
2125 its position is kept as a marker. The mark can be considered a
2126 number---the number of characters the location is from the beginning
2127 of the buffer.) In Emacs Lisp, @code{+} can be used to add the
2128 numeric value of marker positions as numbers.
2130 The @samp{p} of @code{number-or-marker-p} is the embodiment of a
2131 practice started in the early days of Lisp programming. The @samp{p}
2132 stands for ``predicate''. In the jargon used by the early Lisp
2133 researchers, a predicate refers to a function to determine whether some
2134 property is true or false. So the @samp{p} tells us that
2135 @code{number-or-marker-p} is the name of a function that determines
2136 whether it is true or false that the argument supplied is a number or
2137 a marker. Other Lisp symbols that end in @samp{p} include @code{zerop},
2138 a function that tests whether its argument has the value of zero, and
2139 @code{listp}, a function that tests whether its argument is a list.
2141 Finally, the last part of the error message is the symbol @code{hello}.
2142 This is the value of the argument that was passed to @code{+}. If the
2143 addition had been passed the correct type of object, the value passed
2144 would have been a number, such as 37, rather than a symbol like
2145 @code{hello}. But then you would not have got the error message.
2149 In GNU Emacs version 20 and before, the echo area displays an error
2153 Wrong type argument:@: number-or-marker-p, hello
2156 This says, in different words, the same as the top line of the
2157 @file{*Backtrace*} buffer.
2161 @subsection The @code{message} Function
2164 Like @code{+}, the @code{message} function takes a variable number of
2165 arguments. It is used to send messages to the user and is so useful
2166 that we will describe it here.
2169 A message is printed in the echo area. For example, you can print a
2170 message in your echo area by evaluating the following list:
2173 (message "This message appears in the echo area!")
2176 The whole string between double quotation marks is a single argument
2177 and is printed @i{in toto}. (Note that in this example, the message
2178 itself will appear in the echo area within double quotes; that is
2179 because you see the value returned by the @code{message} function. In
2180 most uses of @code{message} in programs that you write, the text will
2181 be printed in the echo area as a side-effect, without the quotes.
2182 @xref{multiply-by-seven in detail, , @code{multiply-by-seven} in
2183 detail}, for an example of this.)
2185 However, if there is a @samp{%s} in the quoted string of characters, the
2186 @code{message} function does not print the @samp{%s} as such, but looks
2187 to the argument that follows the string. It evaluates the second
2188 argument and prints the value at the location in the string where the
2192 You can see this by positioning the cursor after the following
2193 expression and typing @kbd{C-x C-e}:
2196 (message "The name of this buffer is: %s." (buffer-name))
2200 In Info, @code{"The name of this buffer is: *info*."} will appear in the
2201 echo area. The function @code{buffer-name} returns the name of the
2202 buffer as a string, which the @code{message} function inserts in place
2205 To print a value as an integer, use @samp{%d} in the same way as
2206 @samp{%s}. For example, to print a message in the echo area that
2207 states the value of the @code{fill-column}, evaluate the following:
2210 (message "The value of fill-column is %d." fill-column)
2214 On my system, when I evaluate this list, @code{"The value of
2215 fill-column is 72."} appears in my echo area@footnote{Actually, you
2216 can use @code{%s} to print a number. It is non-specific. @code{%d}
2217 prints only the part of a number left of a decimal point, and not
2218 anything that is not a number.}.
2220 If there is more than one @samp{%s} in the quoted string, the value of
2221 the first argument following the quoted string is printed at the
2222 location of the first @samp{%s} and the value of the second argument is
2223 printed at the location of the second @samp{%s}, and so on.
2226 For example, if you evaluate the following,
2230 (message "There are %d %s in the office!"
2231 (- fill-column 14) "pink elephants")
2236 a rather whimsical message will appear in your echo area. On my system
2237 it says, @code{"There are 58 pink elephants in the office!"}.
2239 The expression @code{(- fill-column 14)} is evaluated and the resulting
2240 number is inserted in place of the @samp{%d}; and the string in double
2241 quotes, @code{"pink elephants"}, is treated as a single argument and
2242 inserted in place of the @samp{%s}. (That is to say, a string between
2243 double quotes evaluates to itself, like a number.)
2245 Finally, here is a somewhat complex example that not only illustrates
2246 the computation of a number, but also shows how you can use an
2247 expression within an expression to generate the text that is substituted
2252 (message "He saw %d %s"
2256 "The quick brown foxes jumped." 16 21)
2261 In this example, @code{message} has three arguments: the string,
2262 @code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and
2263 the expression beginning with the function @code{concat}. The value
2264 resulting from the evaluation of @code{(- fill-column 32)} is inserted
2265 in place of the @samp{%d}; and the value returned by the expression
2266 beginning with @code{concat} is inserted in place of the @samp{%s}.
2268 When your fill column is 70 and you evaluate the expression, the
2269 message @code{"He saw 38 red foxes leaping."} appears in your echo
2273 @section Setting the Value of a Variable
2274 @cindex Variable, setting value
2275 @cindex Setting value of variable
2277 @cindex @samp{bind} defined
2278 There are several ways by which a variable can be given a value. One of
2279 the ways is to use either the function @code{set} or the function
2280 @code{setq}. Another way is to use @code{let} (@pxref{let}). (The
2281 jargon for this process is to @dfn{bind} a variable to a value.)
2283 The following sections not only describe how @code{set} and @code{setq}
2284 work but also illustrate how arguments are passed.
2287 * Using set:: Setting values.
2288 * Using setq:: Setting a quoted value.
2289 * Counting:: Using @code{setq} to count.
2293 @subsection Using @code{set}
2296 To set the value of the symbol @code{flowers} to the list @code{'(rose
2297 violet daisy buttercup)}, evaluate the following expression by
2298 positioning the cursor after the expression and typing @kbd{C-x C-e}.
2301 (set 'flowers '(rose violet daisy buttercup))
2305 The list @code{(rose violet daisy buttercup)} will appear in the echo
2306 area. This is what is @emph{returned} by the @code{set} function. As a
2307 side effect, the symbol @code{flowers} is bound to the list; that is,
2308 the symbol @code{flowers}, which can be viewed as a variable, is given
2309 the list as its value. (This process, by the way, illustrates how a
2310 side effect to the Lisp interpreter, setting the value, can be the
2311 primary effect that we humans are interested in. This is because every
2312 Lisp function must return a value if it does not get an error, but it
2313 will only have a side effect if it is designed to have one.)
2315 After evaluating the @code{set} expression, you can evaluate the symbol
2316 @code{flowers} and it will return the value you just set. Here is the
2317 symbol. Place your cursor after it and type @kbd{C-x C-e}.
2324 When you evaluate @code{flowers}, the list
2325 @code{(rose violet daisy buttercup)} appears in the echo area.
2327 Incidentally, if you evaluate @code{'flowers}, the variable with a quote
2328 in front of it, what you will see in the echo area is the symbol itself,
2329 @code{flowers}. Here is the quoted symbol, so you can try this:
2335 Note also, that when you use @code{set}, you need to quote both
2336 arguments to @code{set}, unless you want them evaluated. Since we do
2337 not want either argument evaluated, neither the variable
2338 @code{flowers} nor the list @code{(rose violet daisy buttercup)}, both
2339 are quoted. (When you use @code{set} without quoting its first
2340 argument, the first argument is evaluated before anything else is
2341 done. If you did this and @code{flowers} did not have a value
2342 already, you would get an error message that the @samp{Symbol's value
2343 as variable is void}; on the other hand, if @code{flowers} did return
2344 a value after it was evaluated, the @code{set} would attempt to set
2345 the value that was returned. There are situations where this is the
2346 right thing for the function to do; but such situations are rare.)
2349 @subsection Using @code{setq}
2352 As a practical matter, you almost always quote the first argument to
2353 @code{set}. The combination of @code{set} and a quoted first argument
2354 is so common that it has its own name: the special form @code{setq}.
2355 This special form is just like @code{set} except that the first argument
2356 is quoted automatically, so you don't need to type the quote mark
2357 yourself. Also, as an added convenience, @code{setq} permits you to set
2358 several different variables to different values, all in one expression.
2360 To set the value of the variable @code{carnivores} to the list
2361 @code{'(lion tiger leopard)} using @code{setq}, the following expression
2365 (setq carnivores '(lion tiger leopard))
2369 This is exactly the same as using @code{set} except the first argument
2370 is automatically quoted by @code{setq}. (The @samp{q} in @code{setq}
2371 means @code{quote}.)
2374 With @code{set}, the expression would look like this:
2377 (set 'carnivores '(lion tiger leopard))
2380 Also, @code{setq} can be used to assign different values to
2381 different variables. The first argument is bound to the value
2382 of the second argument, the third argument is bound to the value of the
2383 fourth argument, and so on. For example, you could use the following to
2384 assign a list of trees to the symbol @code{trees} and a list of herbivores
2385 to the symbol @code{herbivores}:
2389 (setq trees '(pine fir oak maple)
2390 herbivores '(gazelle antelope zebra))
2395 (The expression could just as well have been on one line, but it might
2396 not have fit on a page; and humans find it easier to read nicely
2399 Although I have been using the term ``assign'', there is another way of
2400 thinking about the workings of @code{set} and @code{setq}; and that is to
2401 say that @code{set} and @code{setq} make the symbol @emph{point} to the
2402 list. This latter way of thinking is very common and in forthcoming
2403 chapters we shall come upon at least one symbol that has ``pointer'' as
2404 part of its name. The name is chosen because the symbol has a value,
2405 specifically a list, attached to it; or, expressed another way,
2406 the symbol is set to point to the list.
2409 @subsection Counting
2412 Here is an example that shows how to use @code{setq} in a counter. You
2413 might use this to count how many times a part of your program repeats
2414 itself. First set a variable to zero; then add one to the number each
2415 time the program repeats itself. To do this, you need a variable that
2416 serves as a counter, and two expressions: an initial @code{setq}
2417 expression that sets the counter variable to zero; and a second
2418 @code{setq} expression that increments the counter each time it is
2423 (setq counter 0) ; @r{Let's call this the initializer.}
2425 (setq counter (+ counter 1)) ; @r{This is the incrementer.}
2427 counter ; @r{This is the counter.}
2432 (The text following the @samp{;} are comments. @xref{Change a
2433 defun, , Change a Function Definition}.)
2435 If you evaluate the first of these expressions, the initializer,
2436 @code{(setq counter 0)}, and then evaluate the third expression,
2437 @code{counter}, the number @code{0} will appear in the echo area. If
2438 you then evaluate the second expression, the incrementer, @code{(setq
2439 counter (+ counter 1))}, the counter will get the value 1. So if you
2440 again evaluate @code{counter}, the number @code{1} will appear in the
2441 echo area. Each time you evaluate the second expression, the value of
2442 the counter will be incremented.
2444 When you evaluate the incrementer, @code{(setq counter (+ counter 1))},
2445 the Lisp interpreter first evaluates the innermost list; this is the
2446 addition. In order to evaluate this list, it must evaluate the variable
2447 @code{counter} and the number @code{1}. When it evaluates the variable
2448 @code{counter}, it receives its current value. It passes this value and
2449 the number @code{1} to the @code{+} which adds them together. The sum
2450 is then returned as the value of the inner list and passed to the
2451 @code{setq} which sets the variable @code{counter} to this new value.
2452 Thus, the value of the variable, @code{counter}, is changed.
2457 Learning Lisp is like climbing a hill in which the first part is the
2458 steepest. You have now climbed the most difficult part; what remains
2459 becomes easier as you progress onwards.
2467 Lisp programs are made up of expressions, which are lists or single atoms.
2470 Lists are made up of zero or more atoms or inner lists, separated by whitespace and
2471 surrounded by parentheses. A list can be empty.
2474 Atoms are multi-character symbols, like @code{forward-paragraph}, single
2475 character symbols like @code{+}, strings of characters between double
2476 quotation marks, or numbers.
2479 A number evaluates to itself.
2482 A string between double quotes also evaluates to itself.
2485 When you evaluate a symbol by itself, its value is returned.
2488 When you evaluate a list, the Lisp interpreter looks at the first symbol
2489 in the list and then at the function definition bound to that symbol.
2490 Then the instructions in the function definition are carried out.
2493 A single quotation mark,
2500 , tells the Lisp interpreter that it should
2501 return the following expression as written, and not evaluate it as it
2502 would if the quote were not there.
2505 Arguments are the information passed to a function. The arguments to a
2506 function are computed by evaluating the rest of the elements of the list
2507 of which the function is the first element.
2510 A function always returns a value when it is evaluated (unless it gets
2511 an error); in addition, it may also carry out some action that is a
2512 side effect. In many cases, a function's primary purpose is to
2513 create a side effect.
2516 @node Error Message Exercises
2519 A few simple exercises:
2523 Generate an error message by evaluating an appropriate symbol that is
2524 not within parentheses.
2527 Generate an error message by evaluating an appropriate symbol that is
2528 between parentheses.
2531 Create a counter that increments by two rather than one.
2534 Write an expression that prints a message in the echo area when
2538 @node Practicing Evaluation
2539 @chapter Practicing Evaluation
2540 @cindex Practicing evaluation
2541 @cindex Evaluation practice
2543 Before learning how to write a function definition in Emacs Lisp, it is
2544 useful to spend a little time evaluating various expressions that have
2545 already been written. These expressions will be lists with the
2546 functions as their first (and often only) element. Since some of the
2547 functions associated with buffers are both simple and interesting, we
2548 will start with those. In this section, we will evaluate a few of
2549 these. In another section, we will study the code of several other
2550 buffer-related functions, to see how they were written.
2553 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
2555 * Buffer Names:: Buffers and files are different.
2556 * Getting Buffers:: Getting a buffer itself, not merely its name.
2557 * Switching Buffers:: How to change to another buffer.
2558 * Buffer Size & Locations:: Where point is located and the size of
2560 * Evaluation Exercise::
2564 @node How to Evaluate
2565 @unnumberedsec How to Evaluate
2568 @i{Whenever you give an editing command} to Emacs Lisp, such as the
2569 command to move the cursor or to scroll the screen, @i{you are evaluating
2570 an expression,} the first element of which is a function. @i{This is
2573 @cindex @samp{interactive function} defined
2574 @cindex @samp{command} defined
2575 When you type keys, you cause the Lisp interpreter to evaluate an
2576 expression and that is how you get your results. Even typing plain text
2577 involves evaluating an Emacs Lisp function, in this case, one that uses
2578 @code{self-insert-command}, which simply inserts the character you
2579 typed. The functions you evaluate by typing keystrokes are called
2580 @dfn{interactive} functions, or @dfn{commands}; how you make a function
2581 interactive will be illustrated in the chapter on how to write function
2582 definitions. @xref{Interactive, , Making a Function Interactive}.
2584 In addition to typing keyboard commands, we have seen a second way to
2585 evaluate an expression: by positioning the cursor after a list and
2586 typing @kbd{C-x C-e}. This is what we will do in the rest of this
2587 section. There are other ways to evaluate an expression as well; these
2588 will be described as we come to them.
2590 Besides being used for practicing evaluation, the functions shown in the
2591 next few sections are important in their own right. A study of these
2592 functions makes clear the distinction between buffers and files, how to
2593 switch to a buffer, and how to determine a location within it.
2596 @section Buffer Names
2598 @findex buffer-file-name
2600 The two functions, @code{buffer-name} and @code{buffer-file-name}, show
2601 the difference between a file and a buffer. When you evaluate the
2602 following expression, @code{(buffer-name)}, the name of the buffer
2603 appears in the echo area. When you evaluate @code{(buffer-file-name)},
2604 the name of the file to which the buffer refers appears in the echo
2605 area. Usually, the name returned by @code{(buffer-name)} is the same as
2606 the name of the file to which it refers, and the name returned by
2607 @code{(buffer-file-name)} is the full path-name of the file.
2609 A file and a buffer are two different entities. A file is information
2610 recorded permanently in the computer (unless you delete it). A buffer,
2611 on the other hand, is information inside of Emacs that will vanish at
2612 the end of the editing session (or when you kill the buffer). Usually,
2613 a buffer contains information that you have copied from a file; we say
2614 the buffer is @dfn{visiting} that file. This copy is what you work on
2615 and modify. Changes to the buffer do not change the file, until you
2616 save the buffer. When you save the buffer, the buffer is copied to the file
2617 and is thus saved permanently.
2620 If you are reading this in Info inside of GNU Emacs, you can evaluate
2621 each of the following expressions by positioning the cursor after it and
2622 typing @kbd{C-x C-e}.
2633 When I do this in Info, the value returned by evaluating
2634 @code{(buffer-name)} is @file{"*info*"}, and the value returned by
2635 evaluating @code{(buffer-file-name)} is @file{nil}.
2637 On the other hand, while I am writing this document, the value
2638 returned by evaluating @code{(buffer-name)} is
2639 @file{"introduction.texinfo"}, and the value returned by evaluating
2640 @code{(buffer-file-name)} is
2641 @file{"/gnu/work/intro/introduction.texinfo"}.
2643 @cindex @code{nil}, history of word
2644 The former is the name of the buffer and the latter is the name of the
2645 file. In Info, the buffer name is @file{"*info*"}. Info does not
2646 point to any file, so the result of evaluating
2647 @code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is
2648 from the Latin word for ``nothing''; in this case, it means that the
2649 buffer is not associated with any file. (In Lisp, @code{nil} is also
2650 used to mean ``false'' and is a synonym for the empty list, @code{()}.)
2652 When I am writing, the name of my buffer is
2653 @file{"introduction.texinfo"}. The name of the file to which it
2654 points is @file{"/gnu/work/intro/introduction.texinfo"}.
2656 (In the expressions, the parentheses tell the Lisp interpreter to
2657 treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as
2658 functions; without the parentheses, the interpreter would attempt to
2659 evaluate the symbols as variables. @xref{Variables}.)
2661 In spite of the distinction between files and buffers, you will often
2662 find that people refer to a file when they mean a buffer and vice versa.
2663 Indeed, most people say, ``I am editing a file,'' rather than saying,
2664 ``I am editing a buffer which I will soon save to a file.'' It is
2665 almost always clear from context what people mean. When dealing with
2666 computer programs, however, it is important to keep the distinction in mind,
2667 since the computer is not as smart as a person.
2669 @cindex Buffer, history of word
2670 The word ``buffer'', by the way, comes from the meaning of the word as a
2671 cushion that deadens the force of a collision. In early computers, a
2672 buffer cushioned the interaction between files and the computer's
2673 central processing unit. The drums or tapes that held a file and the
2674 central processing unit were pieces of equipment that were very
2675 different from each other, working at their own speeds, in spurts. The
2676 buffer made it possible for them to work together effectively.
2677 Eventually, the buffer grew from being an intermediary, a temporary
2678 holding place, to being the place where work is done. This
2679 transformation is rather like that of a small seaport that grew into a
2680 great city: once it was merely the place where cargo was warehoused
2681 temporarily before being loaded onto ships; then it became a business
2682 and cultural center in its own right.
2684 Not all buffers are associated with files. For example, a
2685 @file{*scratch*} buffer does not visit any file. Similarly, a
2686 @file{*Help*} buffer is not associated with any file.
2688 In the old days, when you lacked a @file{~/.emacs} file and started an
2689 Emacs session by typing the command @code{emacs} alone, without naming
2690 any files, Emacs started with the @file{*scratch*} buffer visible.
2691 Nowadays, you will see a splash screen. You can follow one of the
2692 commands suggested on the splash screen, visit a file, or press the
2693 spacebar to reach the @file{*scratch*} buffer.
2695 If you switch to the @file{*scratch*} buffer, type
2696 @code{(buffer-name)}, position the cursor after it, and then type
2697 @kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"}
2698 will be returned and will appear in the echo area. @code{"*scratch*"}
2699 is the name of the buffer. When you type @code{(buffer-file-name)} in
2700 the @file{*scratch*} buffer and evaluate that, @code{nil} will appear
2701 in the echo area, just as it does when you evaluate
2702 @code{(buffer-file-name)} in Info.
2704 Incidentally, if you are in the @file{*scratch*} buffer and want the
2705 value returned by an expression to appear in the @file{*scratch*}
2706 buffer itself rather than in the echo area, type @kbd{C-u C-x C-e}
2707 instead of @kbd{C-x C-e}. This causes the value returned to appear
2708 after the expression. The buffer will look like this:
2711 (buffer-name)"*scratch*"
2715 You cannot do this in Info since Info is read-only and it will not allow
2716 you to change the contents of the buffer. But you can do this in any
2717 buffer you can edit; and when you write code or documentation (such as
2718 this book), this feature is very useful.
2720 @node Getting Buffers
2721 @section Getting Buffers
2722 @findex current-buffer
2723 @findex other-buffer
2724 @cindex Getting a buffer
2726 The @code{buffer-name} function returns the @emph{name} of the buffer;
2727 to get the buffer @emph{itself}, a different function is needed: the
2728 @code{current-buffer} function. If you use this function in code, what
2729 you get is the buffer itself.
2731 A name and the object or entity to which the name refers are different
2732 from each other. You are not your name. You are a person to whom
2733 others refer by name. If you ask to speak to George and someone hands you
2734 a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r},
2735 @samp{g}, and @samp{e} written on it, you might be amused, but you would
2736 not be satisfied. You do not want to speak to the name, but to the
2737 person to whom the name refers. A buffer is similar: the name of the
2738 scratch buffer is @file{*scratch*}, but the name is not the buffer. To
2739 get a buffer itself, you need to use a function such as
2740 @code{current-buffer}.
2742 However, there is a slight complication: if you evaluate
2743 @code{current-buffer} in an expression on its own, as we will do here,
2744 what you see is a printed representation of the name of the buffer
2745 without the contents of the buffer. Emacs works this way for two
2746 reasons: the buffer may be thousands of lines long---too long to be
2747 conveniently displayed; and, another buffer may have the same contents
2748 but a different name, and it is important to distinguish between them.
2751 Here is an expression containing the function:
2758 If you evaluate this expression in Info in Emacs in the usual way,
2759 @file{#<buffer *info*>} will appear in the echo area. The special
2760 format indicates that the buffer itself is being returned, rather than
2763 Incidentally, while you can type a number or symbol into a program, you
2764 cannot do that with the printed representation of a buffer: the only way
2765 to get a buffer itself is with a function such as @code{current-buffer}.
2767 A related function is @code{other-buffer}. This returns the most
2768 recently selected buffer other than the one you are in currently, not
2769 a printed representation of its name. If you have recently switched
2770 back and forth from the @file{*scratch*} buffer, @code{other-buffer}
2771 will return that buffer.
2774 You can see this by evaluating the expression:
2781 You should see @file{#<buffer *scratch*>} appear in the echo area, or
2782 the name of whatever other buffer you switched back from most
2783 recently@footnote{Actually, by default, if the buffer from which you
2784 just switched is visible to you in another window, @code{other-buffer}
2785 will choose the most recent buffer that you cannot see; this is a
2786 subtlety that I often forget.}.
2788 @node Switching Buffers
2789 @section Switching Buffers
2790 @findex switch-to-buffer
2792 @cindex Switching to a buffer
2794 The @code{other-buffer} function actually provides a buffer when it is
2795 used as an argument to a function that requires one. We can see this
2796 by using @code{other-buffer} and @code{switch-to-buffer} to switch to a
2799 But first, a brief introduction to the @code{switch-to-buffer}
2800 function. When you switched back and forth from Info to the
2801 @file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most
2802 likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or
2803 rather, to save typing, you probably only typed @kbd{RET} if the
2804 default buffer was @file{*scratch*}, or if it was different, then you
2805 typed just part of the name, such as @code{*sc}, pressed your
2806 @kbd{TAB} key to cause it to expand to the full name, and then typed
2807 @kbd{RET}.} when prompted in the minibuffer for the name of
2808 the buffer to which you wanted to switch. The keystrokes, @kbd{C-x
2809 b}, cause the Lisp interpreter to evaluate the interactive function
2810 @code{switch-to-buffer}. As we said before, this is how Emacs works:
2811 different keystrokes call or run different functions. For example,
2812 @kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls
2813 @code{forward-sentence}, and so on.
2815 By writing @code{switch-to-buffer} in an expression, and giving it a
2816 buffer to switch to, we can switch buffers just the way @kbd{C-x b}
2820 (switch-to-buffer (other-buffer))
2824 The symbol @code{switch-to-buffer} is the first element of the list,
2825 so the Lisp interpreter will treat it as a function and carry out the
2826 instructions that are attached to it. But before doing that, the
2827 interpreter will note that @code{other-buffer} is inside parentheses
2828 and work on that symbol first. @code{other-buffer} is the first (and
2829 in this case, the only) element of this list, so the Lisp interpreter
2830 calls or runs the function. It returns another buffer. Next, the
2831 interpreter runs @code{switch-to-buffer}, passing to it, as an
2832 argument, the other buffer, which is what Emacs will switch to. If
2833 you are reading this in Info, try this now. Evaluate the expression.
2834 (To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this
2835 expression will move you to your most recent other buffer that you
2836 cannot see. If you really want to go to your most recently selected
2837 buffer, even if you can still see it, you need to evaluate the
2838 following more complex expression:
2841 (switch-to-buffer (other-buffer (current-buffer) t))
2845 In this case, the first argument to @code{other-buffer} tells it which
2846 buffer to skip---the current one---and the second argument tells
2847 @code{other-buffer} it is OK to switch to a visible buffer. In
2848 regular use, @code{switch-to-buffer} takes you to a buffer not visible
2849 in windows since you would most likely use @kbd{C-x o}
2850 (@code{other-window}) to go to another visible buffer.}
2852 In the programming examples in later sections of this document, you will
2853 see the function @code{set-buffer} more often than
2854 @code{switch-to-buffer}. This is because of a difference between
2855 computer programs and humans: humans have eyes and expect to see the
2856 buffer on which they are working on their computer terminals. This is
2857 so obvious, it almost goes without saying. However, programs do not
2858 have eyes. When a computer program works on a buffer, that buffer does
2859 not need to be visible on the screen.
2861 @code{switch-to-buffer} is designed for humans and does two different
2862 things: it switches the buffer to which Emacs's attention is directed; and
2863 it switches the buffer displayed in the window to the new buffer.
2864 @code{set-buffer}, on the other hand, does only one thing: it switches
2865 the attention of the computer program to a different buffer. The buffer
2866 on the screen remains unchanged (of course, normally nothing happens
2867 there until the command finishes running).
2869 @cindex @samp{call} defined
2870 Also, we have just introduced another jargon term, the word @dfn{call}.
2871 When you evaluate a list in which the first symbol is a function, you
2872 are calling that function. The use of the term comes from the notion of
2873 the function as an entity that can do something for you if you call
2874 it---just as a plumber is an entity who can fix a leak if you call him
2877 @node Buffer Size & Locations
2878 @section Buffer Size and the Location of Point
2879 @cindex Size of buffer
2881 @cindex Point location
2882 @cindex Location of point
2884 Finally, let's look at several rather simple functions,
2885 @code{buffer-size}, @code{point}, @code{point-min}, and
2886 @code{point-max}. These give information about the size of a buffer and
2887 the location of point within it.
2889 The function @code{buffer-size} tells you the size of the current
2890 buffer; that is, the function returns a count of the number of
2891 characters in the buffer.
2898 You can evaluate this in the usual way, by positioning the
2899 cursor after the expression and typing @kbd{C-x C-e}.
2901 @cindex @samp{point} defined
2902 In Emacs, the current position of the cursor is called @dfn{point}.
2903 The expression @code{(point)} returns a number that tells you where the
2904 cursor is located as a count of the number of characters from the
2905 beginning of the buffer up to point.
2908 You can see the character count for point in this buffer by evaluating
2909 the following expression in the usual way:
2916 As I write this, the value of point is 65724. The @code{point}
2917 function is frequently used in some of the examples later in this
2921 The value of point depends, of course, on its location within the
2922 buffer. If you evaluate point in this spot, the number will be larger:
2929 For me, the value of point in this location is 66043, which means that
2930 there are 319 characters (including spaces) between the two
2931 expressions. (Doubtless, you will see different numbers, since I will
2932 have edited this since I first evaluated point.)
2934 @cindex @samp{narrowing} defined
2935 The function @code{point-min} is somewhat similar to @code{point}, but
2936 it returns the value of the minimum permissible value of point in the
2937 current buffer. This is the number 1 unless @dfn{narrowing} is in
2938 effect. (Narrowing is a mechanism whereby you can restrict yourself,
2939 or a program, to operations on just a part of a buffer.
2940 @xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the
2941 function @code{point-max} returns the value of the maximum permissible
2942 value of point in the current buffer.
2944 @node Evaluation Exercise
2947 Find a file with which you are working and move towards its middle.
2948 Find its buffer name, file name, length, and your position in the file.
2950 @node Writing Defuns
2951 @chapter How To Write Function Definitions
2952 @cindex Definition writing
2953 @cindex Function definition writing
2954 @cindex Writing a function definition
2956 When the Lisp interpreter evaluates a list, it looks to see whether the
2957 first symbol on the list has a function definition attached to it; or,
2958 put another way, whether the symbol points to a function definition. If
2959 it does, the computer carries out the instructions in the definition. A
2960 symbol that has a function definition is called, simply, a function
2961 (although, properly speaking, the definition is the function and the
2962 symbol refers to it.)
2965 * Primitive Functions::
2966 * defun:: The @code{defun} macro.
2967 * Install:: Install a function definition.
2968 * Interactive:: Making a function interactive.
2969 * Interactive Options:: Different options for @code{interactive}.
2970 * Permanent Installation:: Installing code permanently.
2971 * let:: Creating and initializing local variables.
2973 * else:: If--then--else expressions.
2974 * Truth & Falsehood:: What Lisp considers false and true.
2975 * save-excursion:: Keeping track of point and buffer.
2981 @node Primitive Functions
2982 @unnumberedsec An Aside about Primitive Functions
2984 @cindex Primitive functions
2985 @cindex Functions, primitive
2987 @cindex C language primitives
2988 @cindex Primitives written in C
2989 All functions are defined in terms of other functions, except for a few
2990 @dfn{primitive} functions that are written in the C programming
2991 language. When you write functions' definitions, you will write them in
2992 Emacs Lisp and use other functions as your building blocks. Some of the
2993 functions you will use will themselves be written in Emacs Lisp (perhaps
2994 by you) and some will be primitives written in C@. The primitive
2995 functions are used exactly like those written in Emacs Lisp and behave
2996 like them. They are written in C so we can easily run GNU Emacs on any
2997 computer that has sufficient power and can run C.
2999 Let me re-emphasize this: when you write code in Emacs Lisp, you do not
3000 distinguish between the use of functions written in C and the use of
3001 functions written in Emacs Lisp. The difference is irrelevant. I
3002 mention the distinction only because it is interesting to know. Indeed,
3003 unless you investigate, you won't know whether an already-written
3004 function is written in Emacs Lisp or C.
3007 @section The @code{defun} Macro
3010 @cindex @samp{function definition} defined
3011 In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to
3012 it that tells the computer what to do when the function is called.
3013 This code is called the @dfn{function definition} and is created by
3014 evaluating a Lisp expression that starts with the symbol @code{defun}
3015 (which is an abbreviation for @emph{define function}).
3017 In subsequent sections, we will look at function definitions from the
3018 Emacs source code, such as @code{mark-whole-buffer}. In this section,
3019 we will describe a simple function definition so you can see how it
3020 looks. This function definition uses arithmetic because it makes for a
3021 simple example. Some people dislike examples using arithmetic; however,
3022 if you are such a person, do not despair. Hardly any of the code we
3023 will study in the remainder of this introduction involves arithmetic or
3024 mathematics. The examples mostly involve text in one way or another.
3026 A function definition has up to five parts following the word
3031 The name of the symbol to which the function definition should be
3035 A list of the arguments that will be passed to the function. If no
3036 arguments will be passed to the function, this is an empty list,
3040 Documentation describing the function. (Technically optional, but
3041 strongly recommended.)
3044 Optionally, an expression to make the function interactive so you can
3045 use it by typing @kbd{M-x} and then the name of the function; or by
3046 typing an appropriate key or keychord.
3048 @cindex @samp{body} defined
3050 The code that instructs the computer what to do: the @dfn{body} of the
3051 function definition.
3054 It is helpful to think of the five parts of a function definition as
3055 being organized in a template, with slots for each part:
3059 (defun @var{function-name} (@var{arguments}@dots{})
3060 "@var{optional-documentation}@dots{}"
3061 (interactive @var{argument-passing-info}) ; @r{optional}
3066 As an example, here is the code for a function that multiplies its
3067 argument by 7. (This example is not interactive. @xref{Interactive,
3068 , Making a Function Interactive}, for that information.)
3072 (defun multiply-by-seven (number)
3073 "Multiply NUMBER by seven."
3078 This definition begins with a parenthesis and the symbol @code{defun},
3079 followed by the name of the function.
3081 @cindex @samp{argument list} defined
3082 The name of the function is followed by a list that contains the
3083 arguments that will be passed to the function. This list is called
3084 the @dfn{argument list}. In this example, the list has only one
3085 element, the symbol, @code{number}. When the function is used, the
3086 symbol will be bound to the value that is used as the argument to the
3089 Instead of choosing the word @code{number} for the name of the argument,
3090 I could have picked any other name. For example, I could have chosen
3091 the word @code{multiplicand}. I picked the word ``number'' because it
3092 tells what kind of value is intended for this slot; but I could just as
3093 well have chosen the word ``multiplicand'' to indicate the role that the
3094 value placed in this slot will play in the workings of the function. I
3095 could have called it @code{foogle}, but that would have been a bad
3096 choice because it would not tell humans what it means. The choice of
3097 name is up to the programmer and should be chosen to make the meaning of
3100 Indeed, you can choose any name you wish for a symbol in an argument
3101 list, even the name of a symbol used in some other function: the name
3102 you use in an argument list is private to that particular definition.
3103 In that definition, the name refers to a different entity than any use
3104 of the same name outside the function definition. Suppose you have a
3105 nick-name ``Shorty'' in your family; when your family members refer to
3106 ``Shorty'', they mean you. But outside your family, in a movie, for
3107 example, the name ``Shorty'' refers to someone else. Because a name in an
3108 argument list is private to the function definition, you can change the
3109 value of such a symbol inside the body of a function without changing
3110 its value outside the function. The effect is similar to that produced
3111 by a @code{let} expression. (@xref{let, , @code{let}}.)
3114 Note also that we discuss the word ``number'' in two different ways: as a
3115 symbol that appears in the code, and as the name of something that will
3116 be replaced by a something else during the evaluation of the function.
3117 In the first case, @code{number} is a symbol, not a number; it happens
3118 that within the function, it is a variable who value is the number in
3119 question, but our primary interest in it is as a symbol. On the other
3120 hand, when we are talking about the function, our interest is that we
3121 will substitute a number for the word @var{number}. To keep this
3122 distinction clear, we use different typography for the two
3123 circumstances. When we talk about this function, or about how it works,
3124 we refer to this number by writing @var{number}. In the function
3125 itself, we refer to it by writing @code{number}.
3128 The argument list is followed by the documentation string that
3129 describes the function. This is what you see when you type
3130 @w{@kbd{C-h f}} and the name of a function. Incidentally, when you
3131 write a documentation string like this, you should make the first line
3132 a complete sentence since some commands, such as @code{apropos}, print
3133 only the first line of a multi-line documentation string. Also, you
3134 should not indent the second line of a documentation string, if you
3135 have one, because that looks odd when you use @kbd{C-h f}
3136 (@code{describe-function}). The documentation string is optional, but
3137 it is so useful, it should be included in almost every function you
3140 @findex * @r{(multiplication)}
3141 The third line of the example consists of the body of the function
3142 definition. (Most functions' definitions, of course, are longer than
3143 this.) In this function, the body is the list, @code{(* 7 number)}, which
3144 says to multiply the value of @var{number} by 7. (In Emacs Lisp,
3145 @code{*} is the function for multiplication, just as @code{+} is the
3146 function for addition.)
3148 When you use the @code{multiply-by-seven} function, the argument
3149 @code{number} evaluates to the actual number you want used. Here is an
3150 example that shows how @code{multiply-by-seven} is used; but don't try
3151 to evaluate this yet!
3154 (multiply-by-seven 3)
3158 The symbol @code{number}, specified in the function definition in the
3159 next section, is bound to the value 3 in the actual use of
3160 the function. Note that although @code{number} was inside parentheses
3161 in the function definition, the argument passed to the
3162 @code{multiply-by-seven} function is not in parentheses. The
3163 parentheses are written in the function definition so the computer can
3164 figure out where the argument list ends and the rest of the function
3167 If you evaluate this example, you are likely to get an error message.
3168 (Go ahead, try it!) This is because we have written the function
3169 definition, but not yet told the computer about the definition---we have
3170 not yet loaded the function definition in Emacs.
3171 Installing a function is the process that tells the Lisp interpreter the
3172 definition of the function. Installation is described in the next
3176 @section Install a Function Definition
3177 @cindex Install a Function Definition
3178 @cindex Definition installation
3179 @cindex Function definition installation
3181 If you are reading this inside of Info in Emacs, you can try out the
3182 @code{multiply-by-seven} function by first evaluating the function
3183 definition and then evaluating @code{(multiply-by-seven 3)}. A copy of
3184 the function definition follows. Place the cursor after the last
3185 parenthesis of the function definition and type @kbd{C-x C-e}. When you
3186 do this, @code{multiply-by-seven} will appear in the echo area. (What
3187 this means is that when a function definition is evaluated, the value it
3188 returns is the name of the defined function.) At the same time, this
3189 action installs the function definition.
3193 (defun multiply-by-seven (number)
3194 "Multiply NUMBER by seven."
3200 By evaluating this @code{defun}, you have just installed
3201 @code{multiply-by-seven} in Emacs. The function is now just as much a
3202 part of Emacs as @code{forward-word} or any other editing function you
3203 use. (@code{multiply-by-seven} will stay installed until you quit
3204 Emacs. To reload code automatically whenever you start Emacs, see
3205 @ref{Permanent Installation, , Installing Code Permanently}.)
3208 * Effect of installation::
3209 * Change a defun:: How to change a function definition.
3213 @node Effect of installation
3214 @unnumberedsubsec The effect of installation
3217 You can see the effect of installing @code{multiply-by-seven} by
3218 evaluating the following sample. Place the cursor after the following
3219 expression and type @kbd{C-x C-e}. The number 21 will appear in the
3223 (multiply-by-seven 3)
3226 If you wish, you can read the documentation for the function by typing
3227 @kbd{C-h f} (@code{describe-function}) and then the name of the
3228 function, @code{multiply-by-seven}. When you do this, a
3229 @file{*Help*} window will appear on your screen that says:
3233 multiply-by-seven is a Lisp function.
3235 (multiply-by-seven NUMBER)
3237 Multiply NUMBER by seven.
3242 (To return to a single window on your screen, type @kbd{C-x 1}.)
3244 @node Change a defun
3245 @subsection Change a Function Definition
3246 @cindex Changing a function definition
3247 @cindex Function definition, how to change
3248 @cindex Definition, how to change
3250 If you want to change the code in @code{multiply-by-seven}, just rewrite
3251 it. To install the new version in place of the old one, evaluate the
3252 function definition again. This is how you modify code in Emacs. It is
3255 As an example, you can change the @code{multiply-by-seven} function to
3256 add the number to itself seven times instead of multiplying the number
3257 by seven. It produces the same answer, but by a different path. At
3258 the same time, we will add a comment to the code; a comment is text
3259 that the Lisp interpreter ignores, but that a human reader may find
3260 useful or enlightening. The comment is that this is the second
3265 (defun multiply-by-seven (number) ; @r{Second version.}
3266 "Multiply NUMBER by seven."
3267 (+ number number number number number number number))
3271 @cindex Comments in Lisp code
3272 The comment follows a semicolon, @samp{;}. In Lisp, everything on a
3273 line that follows a semicolon is a comment. The end of the line is the
3274 end of the comment. To stretch a comment over two or more lines, begin
3275 each line with a semicolon.
3277 @xref{Beginning init File, , Beginning a @file{.emacs}
3278 File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp
3279 Reference Manual}, for more about comments.
3281 You can install this version of the @code{multiply-by-seven} function by
3282 evaluating it in the same way you evaluated the first function: place
3283 the cursor after the last parenthesis and type @kbd{C-x C-e}.
3285 In summary, this is how you write code in Emacs Lisp: you write a
3286 function; install it; test it; and then make fixes or enhancements and
3290 @section Make a Function Interactive
3291 @cindex Interactive functions
3294 You make a function interactive by placing a list that begins with
3295 the special form @code{interactive} immediately after the
3296 documentation. A user can invoke an interactive function by typing
3297 @kbd{M-x} and then the name of the function; or by typing the keys to
3298 which it is bound, for example, by typing @kbd{C-n} for
3299 @code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}.
3301 Interestingly, when you call an interactive function interactively,
3302 the value returned is not automatically displayed in the echo area.
3303 This is because you often call an interactive function for its side
3304 effects, such as moving forward by a word or line, and not for the
3305 value returned. If the returned value were displayed in the echo area
3306 each time you typed a key, it would be very distracting.
3309 * Interactive multiply-by-seven:: An overview.
3310 * multiply-by-seven in detail:: The interactive version.
3314 @node Interactive multiply-by-seven
3315 @unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview
3318 Both the use of the special form @code{interactive} and one way to
3319 display a value in the echo area can be illustrated by creating an
3320 interactive version of @code{multiply-by-seven}.
3327 (defun multiply-by-seven (number) ; @r{Interactive version.}
3328 "Multiply NUMBER by seven."
3330 (message "The result is %d" (* 7 number)))
3335 You can install this code by placing your cursor after it and typing
3336 @kbd{C-x C-e}. The name of the function will appear in your echo area.
3337 Then, you can use this code by typing @kbd{C-u} and a number and then
3338 typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase
3339 @samp{The result is @dots{}} followed by the product will appear in the
3342 Speaking more generally, you invoke a function like this in either of two
3347 By typing a prefix argument that contains the number to be passed, and
3348 then typing @kbd{M-x} and the name of the function, as with
3349 @kbd{C-u 3 M-x forward-sentence}; or,
3352 By typing whatever key or keychord the function is bound to, as with
3357 Both the examples just mentioned work identically to move point forward
3358 three sentences. (Since @code{multiply-by-seven} is not bound to a key,
3359 it could not be used as an example of key binding.)
3361 (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command
3364 A @dfn{prefix argument} is passed to an interactive function by typing the
3365 @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by
3366 typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you
3367 type @kbd{C-u} without a number, it defaults to 4).
3369 @node multiply-by-seven in detail
3370 @subsection An Interactive @code{multiply-by-seven}
3372 Let's look at the use of the special form @code{interactive} and then at
3373 the function @code{message} in the interactive version of
3374 @code{multiply-by-seven}. You will recall that the function definition
3379 (defun multiply-by-seven (number) ; @r{Interactive version.}
3380 "Multiply NUMBER by seven."
3382 (message "The result is %d" (* 7 number)))
3386 In this function, the expression, @code{(interactive "p")}, is a list of
3387 two elements. The @code{"p"} tells Emacs to pass the prefix argument to
3388 the function and use its value for the argument of the function.
3391 The argument will be a number. This means that the symbol
3392 @code{number} will be bound to a number in the line:
3395 (message "The result is %d" (* 7 number))
3400 For example, if your prefix argument is 5, the Lisp interpreter will
3401 evaluate the line as if it were:
3404 (message "The result is %d" (* 7 5))
3408 (If you are reading this in GNU Emacs, you can evaluate this expression
3409 yourself.) First, the interpreter will evaluate the inner list, which
3410 is @code{(* 7 5)}. This returns a value of 35. Next, it
3411 will evaluate the outer list, passing the values of the second and
3412 subsequent elements of the list to the function @code{message}.
3414 As we have seen, @code{message} is an Emacs Lisp function especially
3415 designed for sending a one line message to a user. (@xref{message, ,
3416 The @code{message} function}.) In summary, the @code{message}
3417 function prints its first argument in the echo area as is, except for
3418 occurrences of @samp{%d} or @samp{%s} (and various other %-sequences
3419 which we have not mentioned). When it sees a control sequence, the
3420 function looks to the second or subsequent arguments and prints the
3421 value of the argument in the location in the string where the control
3422 sequence is located.
3424 In the interactive @code{multiply-by-seven} function, the control string
3425 is @samp{%d}, which requires a number, and the value returned by
3426 evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35
3427 is printed in place of the @samp{%d} and the message is @samp{The result
3430 (Note that when you call the function @code{multiply-by-seven}, the
3431 message is printed without quotes, but when you call @code{message}, the
3432 text is printed in double quotes. This is because the value returned by
3433 @code{message} is what appears in the echo area when you evaluate an
3434 expression whose first element is @code{message}; but when embedded in a
3435 function, @code{message} prints the text as a side effect without
3438 @node Interactive Options
3439 @section Different Options for @code{interactive}
3440 @cindex Options for @code{interactive}
3441 @cindex Interactive options
3443 In the example, @code{multiply-by-seven} used @code{"p"} as the
3444 argument to @code{interactive}. This argument told Emacs to interpret
3445 your typing either @kbd{C-u} followed by a number or @key{META}
3446 followed by a number as a command to pass that number to the function
3447 as its argument. Emacs has more than twenty characters predefined for
3448 use with @code{interactive}. In almost every case, one of these
3449 options will enable you to pass the right information interactively to
3450 a function. (@xref{Interactive Codes, , Code Characters for
3451 @code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.)
3454 Consider the function @code{zap-to-char}. Its interactive expression
3458 (interactive "p\ncZap to char: ")
3461 The first part of the argument to @code{interactive} is @samp{p}, with
3462 which you are already familiar. This argument tells Emacs to
3463 interpret a prefix, as a number to be passed to the function. You
3464 can specify a prefix either by typing @kbd{C-u} followed by a number
3465 or by typing @key{META} followed by a number. The prefix is the
3466 number of specified characters. Thus, if your prefix is three and the
3467 specified character is @samp{x}, then you will delete all the text up
3468 to and including the third next @samp{x}. If you do not set a prefix,
3469 then you delete all the text up to and including the specified
3470 character, but no more.
3472 The @samp{c} tells the function the name of the character to which to delete.
3474 More formally, a function with two or more arguments can have
3475 information passed to each argument by adding parts to the string that
3476 follows @code{interactive}. When you do this, the information is
3477 passed to each argument in the same order it is specified in the
3478 @code{interactive} list. In the string, each part is separated from
3479 the next part by a @samp{\n}, which is a newline. For example, you
3480 can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }.
3481 This causes Emacs to pass the value of the prefix argument (if there
3482 is one) and the character.
3484 In this case, the function definition looks like the following, where
3485 @code{arg} and @code{char} are the symbols to which @code{interactive}
3486 binds the prefix argument and the specified character:
3490 (defun @var{name-of-function} (arg char)
3491 "@var{documentation}@dots{}"
3492 (interactive "p\ncZap to char: ")
3493 @var{body-of-function}@dots{})
3498 (The space after the colon in the prompt makes it look better when you
3499 are prompted. @xref{copy-to-buffer, , The Definition of
3500 @code{copy-to-buffer}}, for an example.)
3502 When a function does not take arguments, @code{interactive} does not
3503 require any. Such a function contains the simple expression
3504 @code{(interactive)}. The @code{mark-whole-buffer} function is like
3507 Alternatively, if the special letter-codes are not right for your
3508 application, you can pass your own arguments to @code{interactive} as
3511 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}},
3512 for an example. @xref{Using Interactive, , Using @code{Interactive},
3513 elisp, The GNU Emacs Lisp Reference Manual}, for a more complete
3514 explanation about this technique.
3516 @node Permanent Installation
3517 @section Install Code Permanently
3518 @cindex Install code permanently
3519 @cindex Permanent code installation
3520 @cindex Code installation
3522 When you install a function definition by evaluating it, it will stay
3523 installed until you quit Emacs. The next time you start a new session
3524 of Emacs, the function will not be installed unless you evaluate the
3525 function definition again.
3527 At some point, you may want to have code installed automatically
3528 whenever you start a new session of Emacs. There are several ways of
3533 If you have code that is just for yourself, you can put the code for the
3534 function definition in your @file{.emacs} initialization file. When you
3535 start Emacs, your @file{.emacs} file is automatically evaluated and all
3536 the function definitions within it are installed.
3537 @xref{Emacs Initialization, , Your @file{.emacs} File}.
3540 Alternatively, you can put the function definitions that you want
3541 installed in one or more files of their own and use the @code{load}
3542 function to cause Emacs to evaluate and thereby install each of the
3543 functions in the files.
3544 @xref{Loading Files, , Loading Files}.
3547 Thirdly, if you have code that your whole site will use, it is usual
3548 to put it in a file called @file{site-init.el} that is loaded when
3549 Emacs is built. This makes the code available to everyone who uses
3550 your machine. (See the @file{INSTALL} file that is part of the Emacs
3554 Finally, if you have code that everyone who uses Emacs may want, you
3555 can post it on a computer network or send a copy to the Free Software
3556 Foundation. (When you do this, please license the code and its
3557 documentation under a license that permits other people to run, copy,
3558 study, modify, and redistribute the code and which protects you from
3559 having your work taken from you.) If you send a copy of your code to
3560 the Free Software Foundation, and properly protect yourself and
3561 others, it may be included in the next release of Emacs. In large
3562 part, this is how Emacs has grown over the past years, by donations.
3568 The @code{let} expression is a special form in Lisp that you will need
3569 to use in most function definitions.
3571 @code{let} is used to attach or bind a symbol to a value in such a way
3572 that the Lisp interpreter will not confuse the variable with a
3573 variable of the same name that is not part of the function.
3575 To understand why the @code{let} special form is necessary, consider
3576 the situation in which you own a home that you generally refer to as
3577 ``the house'', as in the sentence, ``The house needs painting.'' If you
3578 are visiting a friend and your host refers to ``the house'', he is
3579 likely to be referring to @emph{his} house, not yours, that is, to a
3582 If your friend is referring to his house and you think he is referring
3583 to your house, you may be in for some confusion. The same thing could
3584 happen in Lisp if a variable that is used inside of one function has
3585 the same name as a variable that is used inside of another function,
3586 and the two are not intended to refer to the same value. The
3587 @code{let} special form prevents this kind of confusion.
3590 * Prevent confusion::
3591 * Parts of let Expression::
3592 * Sample let Expression::
3593 * Uninitialized let Variables::
3597 @node Prevent confusion
3598 @unnumberedsubsec @code{let} Prevents Confusion
3601 @cindex @samp{local variable} defined
3602 @cindex @samp{variable, local}, defined
3603 The @code{let} special form prevents confusion. @code{let} creates a
3604 name for a @dfn{local variable} that overshadows any use of the same
3605 name outside the @code{let} expression. This is like understanding
3606 that whenever your host refers to ``the house'', he means his house, not
3607 yours. (Symbols used in argument lists work the same way.
3608 @xref{defun, , The @code{defun} Macro}.)
3610 Local variables created by a @code{let} expression retain their value
3611 @emph{only} within the @code{let} expression itself (and within
3612 expressions called within the @code{let} expression); the local
3613 variables have no effect outside the @code{let} expression.
3615 Another way to think about @code{let} is that it is like a @code{setq}
3616 that is temporary and local. The values set by @code{let} are
3617 automatically undone when the @code{let} is finished. The setting
3618 only affects expressions that are inside the bounds of the @code{let}
3619 expression. In computer science jargon, we would say the binding of
3620 a symbol is visible only in functions called in the @code{let} form;
3621 in Emacs Lisp, scoping is dynamic, not lexical.
3623 @code{let} can create more than one variable at once. Also,
3624 @code{let} gives each variable it creates an initial value, either a
3625 value specified by you, or @code{nil}. (In the jargon, this is
3626 binding the variable to the value.) After @code{let} has created
3627 and bound the variables, it executes the code in the body of the
3628 @code{let}, and returns the value of the last expression in the body,
3629 as the value of the whole @code{let} expression. (``Execute'' is a jargon
3630 term that means to evaluate a list; it comes from the use of the word
3631 meaning ``to give practical effect to'' (@cite{Oxford English
3632 Dictionary}). Since you evaluate an expression to perform an action,
3633 ``execute'' has evolved as a synonym to ``evaluate''.)
3635 @node Parts of let Expression
3636 @subsection The Parts of a @code{let} Expression
3637 @cindex @code{let} expression, parts of
3638 @cindex Parts of @code{let} expression
3640 @cindex @samp{varlist} defined
3641 A @code{let} expression is a list of three parts. The first part is
3642 the symbol @code{let}. The second part is a list, called a
3643 @dfn{varlist}, each element of which is either a symbol by itself or a
3644 two-element list, the first element of which is a symbol. The third
3645 part of the @code{let} expression is the body of the @code{let}. The
3646 body usually consists of one or more lists.
3649 A template for a @code{let} expression looks like this:
3652 (let @var{varlist} @var{body}@dots{})
3656 The symbols in the varlist are the variables that are given initial
3657 values by the @code{let} special form. Symbols by themselves are given
3658 the initial value of @code{nil}; and each symbol that is the first
3659 element of a two-element list is bound to the value that is returned
3660 when the Lisp interpreter evaluates the second element.
3662 Thus, a varlist might look like this: @code{(thread (needles 3))}. In
3663 this case, in a @code{let} expression, Emacs binds the symbol
3664 @code{thread} to an initial value of @code{nil}, and binds the symbol
3665 @code{needles} to an initial value of 3.
3667 When you write a @code{let} expression, what you do is put the
3668 appropriate expressions in the slots of the @code{let} expression
3671 If the varlist is composed of two-element lists, as is often the case,
3672 the template for the @code{let} expression looks like this:
3676 (let ((@var{variable} @var{value})
3677 (@var{variable} @var{value})
3683 @node Sample let Expression
3684 @subsection Sample @code{let} Expression
3685 @cindex Sample @code{let} expression
3686 @cindex @code{let} expression sample
3688 The following expression creates and gives initial values
3689 to the two variables @code{zebra} and @code{tiger}. The body of the
3690 @code{let} expression is a list which calls the @code{message} function.
3694 (let ((zebra "stripes")
3696 (message "One kind of animal has %s and another is %s."
3701 Here, the varlist is @code{((zebra "stripes") (tiger "fierce"))}.
3703 The two variables are @code{zebra} and @code{tiger}. Each variable is
3704 the first element of a two-element list and each value is the second
3705 element of its two-element list. In the varlist, Emacs binds the
3706 variable @code{zebra} to the value @code{"stripes"}@footnote{According
3707 to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras
3708 become impossibly dangerous as they grow older'' but the claim here is
3709 that they do not become fierce like a tiger. (1997, W. W. Norton and
3710 Co., ISBN 0-393-03894-2, page 171)}, and binds the
3711 variable @code{tiger} to the value @code{"fierce"}. In this example,
3712 both values are strings. The values could just as well have been
3713 another list or a symbol. The body of the @code{let}
3714 follows after the list holding the variables. In this example, the
3715 body is a list that uses the @code{message} function to print a string
3719 You may evaluate the example in the usual fashion, by placing the
3720 cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do
3721 this, the following will appear in the echo area:
3724 "One kind of animal has stripes and another is fierce."
3727 As we have seen before, the @code{message} function prints its first
3728 argument, except for @samp{%s}. In this example, the value of the variable
3729 @code{zebra} is printed at the location of the first @samp{%s} and the
3730 value of the variable @code{tiger} is printed at the location of the
3733 @node Uninitialized let Variables
3734 @subsection Uninitialized Variables in a @code{let} Statement
3735 @cindex Uninitialized @code{let} variables
3736 @cindex @code{let} variables uninitialized
3738 If you do not bind the variables in a @code{let} statement to specific
3739 initial values, they will automatically be bound to an initial value of
3740 @code{nil}, as in the following expression:
3749 "Here are %d variables with %s, %s, and %s value."
3750 birch pine fir oak))
3755 Here, the varlist is @code{((birch 3) pine fir (oak 'some))}.
3758 If you evaluate this expression in the usual way, the following will
3759 appear in your echo area:
3762 "Here are 3 variables with nil, nil, and some value."
3766 In this example, Emacs binds the symbol @code{birch} to the number 3,
3767 binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds
3768 the symbol @code{oak} to the value @code{some}.
3770 Note that in the first part of the @code{let}, the variables @code{pine}
3771 and @code{fir} stand alone as atoms that are not surrounded by
3772 parentheses; this is because they are being bound to @code{nil}, the
3773 empty list. But @code{oak} is bound to @code{some} and so is a part of
3774 the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the
3775 number 3 and so is in a list with that number. (Since a number
3776 evaluates to itself, the number does not need to be quoted. Also, the
3777 number is printed in the message using a @samp{%d} rather than a
3778 @samp{%s}.) The four variables as a group are put into a list to
3779 delimit them from the body of the @code{let}.
3782 @section The @code{if} Special Form
3784 @cindex Conditional with @code{if}
3786 A third special form, in addition to @code{defun} and @code{let}, is the
3787 conditional @code{if}. This form is used to instruct the computer to
3788 make decisions. You can write function definitions without using
3789 @code{if}, but it is used often enough, and is important enough, to be
3790 included here. It is used, for example, in the code for the
3791 function @code{beginning-of-buffer}.
3793 The basic idea behind an @code{if}, is that @emph{if} a test is true,
3794 @emph{then} an expression is evaluated. If the test is not true, the
3795 expression is not evaluated. For example, you might make a decision
3796 such as, ``if it is warm and sunny, then go to the beach!''
3799 * if in more detail::
3800 * type-of-animal in detail:: An example of an @code{if} expression.
3804 @node if in more detail
3805 @unnumberedsubsec @code{if} in more detail
3808 @cindex @samp{if-part} defined
3809 @cindex @samp{then-part} defined
3810 An @code{if} expression written in Lisp does not use the word ``then'';
3811 the test and the action are the second and third elements of the list
3812 whose first element is @code{if}. Nonetheless, the test part of an
3813 @code{if} expression is often called the @dfn{if-part} and the second
3814 argument is often called the @dfn{then-part}.
3816 Also, when an @code{if} expression is written, the true-or-false-test
3817 is usually written on the same line as the symbol @code{if}, but the
3818 action to carry out if the test is true, the then-part, is written
3819 on the second and subsequent lines. This makes the @code{if}
3820 expression easier to read.
3824 (if @var{true-or-false-test}
3825 @var{action-to-carry-out-if-test-is-true})
3830 The true-or-false-test will be an expression that
3831 is evaluated by the Lisp interpreter.
3833 Here is an example that you can evaluate in the usual manner. The test
3834 is whether the number 5 is greater than the number 4. Since it is, the
3835 message @samp{5 is greater than 4!} will be printed.
3839 (if (> 5 4) ; @r{if-part}
3840 (message "5 is greater than 4!")) ; @r{then-part}
3845 (The function @code{>} tests whether its first argument is greater than
3846 its second argument and returns true if it is.)
3847 @findex > (greater than)
3849 Of course, in actual use, the test in an @code{if} expression will not
3850 be fixed for all time as it is by the expression @code{(> 5 4)}.
3851 Instead, at least one of the variables used in the test will be bound to
3852 a value that is not known ahead of time. (If the value were known ahead
3853 of time, we would not need to run the test!)
3855 For example, the value may be bound to an argument of a function
3856 definition. In the following function definition, the character of the
3857 animal is a value that is passed to the function. If the value bound to
3858 @code{characteristic} is @code{"fierce"}, then the message, @samp{It is a
3859 tiger!} will be printed; otherwise, @code{nil} will be returned.
3863 (defun type-of-animal (characteristic)
3864 "Print message in echo area depending on CHARACTERISTIC.
3865 If the CHARACTERISTIC is the string \"fierce\",
3866 then warn of a tiger."
3867 (if (equal characteristic "fierce")
3868 (message "It is a tiger!")))
3874 If you are reading this inside of GNU Emacs, you can evaluate the
3875 function definition in the usual way to install it in Emacs, and then you
3876 can evaluate the following two expressions to see the results:
3880 (type-of-animal "fierce")
3882 (type-of-animal "striped")
3887 @c Following sentences rewritten to prevent overfull hbox.
3889 When you evaluate @code{(type-of-animal "fierce")}, you will see the
3890 following message printed in the echo area: @code{"It is a tiger!"}; and
3891 when you evaluate @code{(type-of-animal "striped")} you will see @code{nil}
3892 printed in the echo area.
3894 @node type-of-animal in detail
3895 @subsection The @code{type-of-animal} Function in Detail
3897 Let's look at the @code{type-of-animal} function in detail.
3899 The function definition for @code{type-of-animal} was written by filling
3900 the slots of two templates, one for a function definition as a whole, and
3901 a second for an @code{if} expression.
3904 The template for every function that is not interactive is:
3908 (defun @var{name-of-function} (@var{argument-list})
3909 "@var{documentation}@dots{}"
3915 The parts of the function that match this template look like this:
3919 (defun type-of-animal (characteristic)
3920 "Print message in echo area depending on CHARACTERISTIC.
3921 If the CHARACTERISTIC is the string \"fierce\",
3922 then warn of a tiger."
3923 @var{body: the} @code{if} @var{expression})
3927 The name of function is @code{type-of-animal}; it is passed the value
3928 of one argument. The argument list is followed by a multi-line
3929 documentation string. The documentation string is included in the
3930 example because it is a good habit to write documentation string for
3931 every function definition. The body of the function definition
3932 consists of the @code{if} expression.
3935 The template for an @code{if} expression looks like this:
3939 (if @var{true-or-false-test}
3940 @var{action-to-carry-out-if-the-test-returns-true})
3945 In the @code{type-of-animal} function, the code for the @code{if}
3950 (if (equal characteristic "fierce")
3951 (message "It is a tiger!")))
3956 Here, the true-or-false-test is the expression:
3959 (equal characteristic "fierce")
3963 In Lisp, @code{equal} is a function that determines whether its first
3964 argument is equal to its second argument. The second argument is the
3965 string @code{"fierce"} and the first argument is the value of the
3966 symbol @code{characteristic}---in other words, the argument passed to
3969 In the first exercise of @code{type-of-animal}, the argument
3970 @code{"fierce"} is passed to @code{type-of-animal}. Since @code{"fierce"}
3971 is equal to @code{"fierce"}, the expression, @code{(equal characteristic
3972 "fierce")}, returns a value of true. When this happens, the @code{if}
3973 evaluates the second argument or then-part of the @code{if}:
3974 @code{(message "It is a tiger!")}.
3976 On the other hand, in the second exercise of @code{type-of-animal}, the
3977 argument @code{"striped"} is passed to @code{type-of-animal}. @code{"striped"}
3978 is not equal to @code{"fierce"}, so the then-part is not evaluated and
3979 @code{nil} is returned by the @code{if} expression.
3982 @section If--then--else Expressions
3985 An @code{if} expression may have an optional third argument, called
3986 the @dfn{else-part}, for the case when the true-or-false-test returns
3987 false. When this happens, the second argument or then-part of the
3988 overall @code{if} expression is @emph{not} evaluated, but the third or
3989 else-part @emph{is} evaluated. You might think of this as the cloudy
3990 day alternative for the decision ``if it is warm and sunny, then go to
3991 the beach, else read a book!''.
3993 The word ``else'' is not written in the Lisp code; the else-part of an
3994 @code{if} expression comes after the then-part. In the written Lisp, the
3995 else-part is usually written to start on a line of its own and is
3996 indented less than the then-part:
4000 (if @var{true-or-false-test}
4001 @var{action-to-carry-out-if-the-test-returns-true}
4002 @var{action-to-carry-out-if-the-test-returns-false})
4006 For example, the following @code{if} expression prints the message @samp{4
4007 is not greater than 5!} when you evaluate it in the usual way:
4011 (if (> 4 5) ; @r{if-part}
4012 (message "4 falsely greater than 5!") ; @r{then-part}
4013 (message "4 is not greater than 5!")) ; @r{else-part}
4018 Note that the different levels of indentation make it easy to
4019 distinguish the then-part from the else-part. (GNU Emacs has several
4020 commands that automatically indent @code{if} expressions correctly.
4021 @xref{Typing Lists, , GNU Emacs Helps You Type Lists}.)
4023 We can extend the @code{type-of-animal} function to include an
4024 else-part by simply incorporating an additional part to the @code{if}
4028 You can see the consequences of doing this if you evaluate the following
4029 version of the @code{type-of-animal} function definition to install it
4030 and then evaluate the two subsequent expressions to pass different
4031 arguments to the function.
4035 (defun type-of-animal (characteristic) ; @r{Second version.}
4036 "Print message in echo area depending on CHARACTERISTIC.
4037 If the CHARACTERISTIC is the string \"fierce\",
4038 then warn of a tiger; else say it is not fierce."
4039 (if (equal characteristic "fierce")
4040 (message "It is a tiger!")
4041 (message "It is not fierce!")))
4048 (type-of-animal "fierce")
4050 (type-of-animal "striped")
4055 @c Following sentence rewritten to prevent overfull hbox.
4057 When you evaluate @code{(type-of-animal "fierce")}, you will see the
4058 following message printed in the echo area: @code{"It is a tiger!"}; but
4059 when you evaluate @code{(type-of-animal "striped")}, you will see
4060 @code{"It is not fierce!"}.
4062 (Of course, if the @var{characteristic} were @code{"ferocious"}, the
4063 message @code{"It is not fierce!"} would be printed; and it would be
4064 misleading! When you write code, you need to take into account the
4065 possibility that some such argument will be tested by the @code{if}
4066 and write your program accordingly.)
4068 @node Truth & Falsehood
4069 @section Truth and Falsehood in Emacs Lisp
4070 @cindex Truth and falsehood in Emacs Lisp
4071 @cindex Falsehood and truth in Emacs Lisp
4074 There is an important aspect to the truth test in an @code{if}
4075 expression. So far, we have spoken of ``true'' and ``false'' as values of
4076 predicates as if they were new kinds of Emacs Lisp objects. In fact,
4077 ``false'' is just our old friend @code{nil}. Anything else---anything
4078 at all---is ``true''.
4080 The expression that tests for truth is interpreted as @dfn{true}
4081 if the result of evaluating it is a value that is not @code{nil}. In
4082 other words, the result of the test is considered true if the value
4083 returned is a number such as 47, a string such as @code{"hello"}, or a
4084 symbol (other than @code{nil}) such as @code{flowers}, or a list (so
4085 long as it is not empty), or even a buffer!
4088 * nil explained:: @code{nil} has two meanings.
4093 @unnumberedsubsec An explanation of @code{nil}
4096 Before illustrating a test for truth, we need an explanation of @code{nil}.
4098 In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the
4099 empty list. Second, it means false and is the value returned when a
4100 true-or-false-test tests false. @code{nil} can be written as an empty
4101 list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is
4102 concerned, @code{()} and @code{nil} are the same. Humans, however, tend
4103 to use @code{nil} for false and @code{()} for the empty list.
4105 In Emacs Lisp, any value that is not @code{nil}---is not the empty
4106 list---is considered true. This means that if an evaluation returns
4107 something that is not an empty list, an @code{if} expression will test
4108 true. For example, if a number is put in the slot for the test, it
4109 will be evaluated and will return itself, since that is what numbers
4110 do when evaluated. In this conditional, the @code{if} expression will
4111 test true. The expression tests false only when @code{nil}, an empty
4112 list, is returned by evaluating the expression.
4114 You can see this by evaluating the two expressions in the following examples.
4116 In the first example, the number 4 is evaluated as the test in the
4117 @code{if} expression and returns itself; consequently, the then-part
4118 of the expression is evaluated and returned: @samp{true} appears in
4119 the echo area. In the second example, the @code{nil} indicates false;
4120 consequently, the else-part of the expression is evaluated and
4121 returned: @samp{false} appears in the echo area.
4138 Incidentally, if some other useful value is not available for a test that
4139 returns true, then the Lisp interpreter will return the symbol @code{t}
4140 for true. For example, the expression @code{(> 5 4)} returns @code{t}
4141 when evaluated, as you can see by evaluating it in the usual way:
4149 On the other hand, this function returns @code{nil} if the test is false.
4155 @node save-excursion
4156 @section @code{save-excursion}
4157 @findex save-excursion
4158 @cindex Region, what it is
4159 @cindex Preserving point and buffer
4160 @cindex Point and buffer preservation
4164 The @code{save-excursion} function is the third and final special form
4165 that we will discuss in this chapter.
4167 In Emacs Lisp programs used for editing, the @code{save-excursion}
4168 function is very common. It saves the location of point,
4169 executes the body of the function, and then restores point to
4170 its previous position if its location was changed. Its primary
4171 purpose is to keep the user from being surprised and disturbed by
4172 unexpected movement of point.
4175 * Point and mark:: A review of various locations.
4176 * Template for save-excursion::
4180 @node Point and mark
4181 @unnumberedsubsec Point and Mark
4184 Before discussing @code{save-excursion}, however, it may be useful
4185 first to review what point and mark are in GNU Emacs. @dfn{Point} is
4186 the current location of the cursor. Wherever the cursor
4187 is, that is point. More precisely, on terminals where the cursor
4188 appears to be on top of a character, point is immediately before the
4189 character. In Emacs Lisp, point is an integer. The first character in
4190 a buffer is number one, the second is number two, and so on. The
4191 function @code{point} returns the current position of the cursor as a
4192 number. Each buffer has its own value for point.
4194 The @dfn{mark} is another position in the buffer; its value can be set
4195 with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If
4196 a mark has been set, you can use the command @kbd{C-x C-x}
4197 (@code{exchange-point-and-mark}) to cause the cursor to jump to the mark
4198 and set the mark to be the previous position of point. In addition, if
4199 you set another mark, the position of the previous mark is saved in the
4200 mark ring. Many mark positions can be saved this way. You can jump the
4201 cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more
4204 The part of the buffer between point and mark is called @dfn{the
4205 region}. Numerous commands work on the region, including
4206 @code{center-region}, @code{count-lines-region}, @code{kill-region}, and
4207 @code{print-region}.
4209 The @code{save-excursion} special form saves the location of point and
4210 restores this position after the code within the body of the
4211 special form is evaluated by the Lisp interpreter. Thus, if point were
4212 in the beginning of a piece of text and some code moved point to the end
4213 of the buffer, the @code{save-excursion} would put point back to where
4214 it was before, after the expressions in the body of the function were
4217 In Emacs, a function frequently moves point as part of its internal
4218 workings even though a user would not expect this. For example,
4219 @code{count-lines-region} moves point. To prevent the user from being
4220 bothered by jumps that are both unexpected and (from the user's point of
4221 view) unnecessary, @code{save-excursion} is often used to keep point in
4222 the location expected by the user. The use of
4223 @code{save-excursion} is good housekeeping.
4225 To make sure the house stays clean, @code{save-excursion} restores the
4226 value of point even if something goes wrong in the code inside
4227 of it (or, to be more precise and to use the proper jargon, ``in case of
4228 abnormal exit''). This feature is very helpful.
4230 In addition to recording the value of point,
4231 @code{save-excursion} keeps track of the current buffer, and restores
4232 it, too. This means you can write code that will change the buffer and
4233 have @code{save-excursion} switch you back to the original buffer.
4234 This is how @code{save-excursion} is used in @code{append-to-buffer}.
4235 (@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
4237 @node Template for save-excursion
4238 @subsection Template for a @code{save-excursion} Expression
4241 The template for code using @code{save-excursion} is simple:
4251 The body of the function is one or more expressions that will be
4252 evaluated in sequence by the Lisp interpreter. If there is more than
4253 one expression in the body, the value of the last one will be returned
4254 as the value of the @code{save-excursion} function. The other
4255 expressions in the body are evaluated only for their side effects; and
4256 @code{save-excursion} itself is used only for its side effect (which
4257 is restoring the position of point).
4260 In more detail, the template for a @code{save-excursion} expression
4266 @var{first-expression-in-body}
4267 @var{second-expression-in-body}
4268 @var{third-expression-in-body}
4270 @var{last-expression-in-body})
4275 An expression, of course, may be a symbol on its own or a list.
4277 In Emacs Lisp code, a @code{save-excursion} expression often occurs
4278 within the body of a @code{let} expression. It looks like this:
4291 In the last few chapters we have introduced a macro and a fair number
4292 of functions and special forms. Here they are described in brief,
4293 along with a few similar functions that have not been mentioned yet.
4296 @item eval-last-sexp
4297 Evaluate the last symbolic expression before the current location of
4298 point. The value is printed in the echo area unless the function is
4299 invoked with an argument; in that case, the output is printed in the
4300 current buffer. This command is normally bound to @kbd{C-x C-e}.
4303 Define function. This macro has up to five parts: the name, a
4304 template for the arguments that will be passed to the function,
4305 documentation, an optional interactive declaration, and the body of
4309 For example, in an early version of Emacs, the function definition was
4310 as follows. (It is slightly more complex now that it seeks the first
4311 non-whitespace character rather than the first visible character.)
4315 (defun back-to-indentation ()
4316 "Move point to first visible character on line."
4318 (beginning-of-line 1)
4319 (skip-chars-forward " \t"))
4326 (defun backward-to-indentation (&optional arg)
4327 "Move backward ARG lines and position at first nonblank character."
4329 (forward-line (- (or arg 1)))
4330 (skip-chars-forward " \t"))
4332 (defun back-to-indentation ()
4333 "Move point to the first non-whitespace character on this line."
4335 (beginning-of-line 1)
4336 (skip-syntax-forward " " (line-end-position))
4337 ;; Move back over chars that have whitespace syntax but have the p flag.
4338 (backward-prefix-chars))
4342 Declare to the interpreter that the function can be used
4343 interactively. This special form may be followed by a string with one
4344 or more parts that pass the information to the arguments of the
4345 function, in sequence. These parts may also tell the interpreter to
4346 prompt for information. Parts of the string are separated by
4347 newlines, @samp{\n}.
4350 Common code characters are:
4354 The name of an existing buffer.
4357 The name of an existing file.
4360 The numeric prefix argument. (Note that this @code{p} is lower case.)
4363 Point and the mark, as two numeric arguments, smallest first. This
4364 is the only code letter that specifies two successive arguments
4368 @xref{Interactive Codes, , Code Characters for @samp{interactive},
4369 elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of
4373 Declare that a list of variables is for use within the body of the
4374 @code{let} and give them an initial value, either @code{nil} or a
4375 specified value; then evaluate the rest of the expressions in the body
4376 of the @code{let} and return the value of the last one. Inside the
4377 body of the @code{let}, the Lisp interpreter does not see the values of
4378 the variables of the same names that are bound outside of the
4386 (let ((foo (buffer-name))
4387 (bar (buffer-size)))
4389 "This buffer is %s and has %d characters."
4394 @item save-excursion
4395 Record the values of point and the current buffer before
4396 evaluating the body of this special form. Restore the value of point and
4404 (message "We are %d characters into this buffer."
4407 (goto-char (point-min)) (point))))
4412 Evaluate the first argument to the function; if it is true, evaluate
4413 the second argument; else evaluate the third argument, if there is one.
4415 The @code{if} special form is called a @dfn{conditional}. There are
4416 other conditionals in Emacs Lisp, but @code{if} is perhaps the most
4424 (if (= 22 emacs-major-version)
4425 (message "This is version 22 Emacs")
4426 (message "This is not version 22 Emacs"))
4435 The @code{<} function tests whether its first argument is smaller than
4436 its second argument. A corresponding function, @code{>}, tests whether
4437 the first argument is greater than the second. Likewise, @code{<=}
4438 tests whether the first argument is less than or equal to the second and
4439 @code{>=} tests whether the first argument is greater than or equal to
4440 the second. In all cases, both arguments must be numbers or markers
4441 (markers indicate positions in buffers).
4445 The @code{=} function tests whether two arguments, both numbers or
4451 Test whether two objects are the same. @code{equal} uses one meaning
4452 of the word ``same'' and @code{eq} uses another: @code{equal} returns
4453 true if the two objects have a similar structure and contents, such as
4454 two copies of the same book. On the other hand, @code{eq}, returns
4455 true if both arguments are actually the same object.
4464 The @code{string-lessp} function tests whether its first argument is
4465 smaller than the second argument. A shorter, alternative name for the
4466 same function (a @code{defalias}) is @code{string<}.
4468 The arguments to @code{string-lessp} must be strings or symbols; the
4469 ordering is lexicographic, so case is significant. The print names of
4470 symbols are used instead of the symbols themselves.
4472 @cindex @samp{empty string} defined
4473 An empty string, @samp{""}, a string with no characters in it, is
4474 smaller than any string of characters.
4476 @code{string-equal} provides the corresponding test for equality. Its
4477 shorter, alternative name is @code{string=}. There are no string test
4478 functions that correspond to @var{>}, @code{>=}, or @code{<=}.
4481 Print a message in the echo area. The first argument is a string that
4482 can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of
4483 arguments that follow the string. The argument used by @samp{%s} must
4484 be a string or a symbol; the argument used by @samp{%d} must be a
4485 number. The argument used by @samp{%c} must be an @sc{ascii} code
4486 number; it will be printed as the character with that @sc{ascii} code.
4487 (Various other %-sequences have not been mentioned.)
4491 The @code{setq} function sets the value of its first argument to the
4492 value of the second argument. The first argument is automatically
4493 quoted by @code{setq}. It does the same for succeeding pairs of
4494 arguments. Another function, @code{set}, takes only two arguments and
4495 evaluates both of them before setting the value returned by its first
4496 argument to the value returned by its second argument.
4499 Without an argument, return the name of the buffer, as a string.
4501 @item buffer-file-name
4502 Without an argument, return the name of the file the buffer is
4505 @item current-buffer
4506 Return the buffer in which Emacs is active; it may not be
4507 the buffer that is visible on the screen.
4510 Return the most recently selected buffer (other than the buffer passed
4511 to @code{other-buffer} as an argument and other than the current
4514 @item switch-to-buffer
4515 Select a buffer for Emacs to be active in and display it in the current
4516 window so users can look at it. Usually bound to @kbd{C-x b}.
4519 Switch Emacs's attention to a buffer on which programs will run. Don't
4520 alter what the window is showing.
4523 Return the number of characters in the current buffer.
4526 Return the value of the current position of the cursor, as an
4527 integer counting the number of characters from the beginning of the
4531 Return the minimum permissible value of point in
4532 the current buffer. This is 1, unless narrowing is in effect.
4535 Return the value of the maximum permissible value of point in the
4536 current buffer. This is the end of the buffer, unless narrowing is in
4541 @node defun Exercises
4546 Write a non-interactive function that doubles the value of its
4547 argument, a number. Make that function interactive.
4550 Write a function that tests whether the current value of
4551 @code{fill-column} is greater than the argument passed to the function,
4552 and if so, prints an appropriate message.
4555 @node Buffer Walk Through
4556 @chapter A Few Buffer-Related Functions
4558 In this chapter we study in detail several of the functions used in GNU
4559 Emacs. This is called a ``walk-through''. These functions are used as
4560 examples of Lisp code, but are not imaginary examples; with the
4561 exception of the first, simplified function definition, these functions
4562 show the actual code used in GNU Emacs. You can learn a great deal from
4563 these definitions. The functions described here are all related to
4564 buffers. Later, we will study other functions.
4567 * Finding More:: How to find more information.
4568 * simplified-beginning-of-buffer:: Shows @code{goto-char},
4569 @code{point-min}, and @code{push-mark}.
4570 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
4571 * append-to-buffer:: Uses @code{save-excursion} and
4572 @code{insert-buffer-substring}.
4573 * Buffer Related Review:: Review.
4574 * Buffer Exercises::
4578 @section Finding More Information
4580 @findex describe-function, @r{introduced}
4581 @cindex Find function documentation
4582 In this walk-through, I will describe each new function as we come to
4583 it, sometimes in detail and sometimes briefly. If you are interested,
4584 you can get the full documentation of any Emacs Lisp function at any
4585 time by typing @kbd{C-h f} and then the name of the function (and then
4586 @key{RET}). Similarly, you can get the full documentation for a
4587 variable by typing @kbd{C-h v} and then the name of the variable (and
4590 @cindex Find source of function
4591 @c In version 22, tells location both of C and of Emacs Lisp
4592 Also, @code{describe-function} will tell you the location of the
4593 function definition.
4595 Put point into the name of the file that contains the function and
4596 press the @key{RET} key. In this case, @key{RET} means
4597 @code{push-button} rather than ``return'' or ``enter''. Emacs will take
4598 you directly to the function definition.
4603 If you move point over the file name and press
4604 the @key{RET} key, which in this case means @code{help-follow} rather
4605 than ``return'' or ``enter'', Emacs will take you directly to the function
4609 More generally, if you want to see a function in its original source
4610 file, you can use the @code{find-tag} function to jump to it.
4611 @code{find-tag} works with a wide variety of languages, not just
4612 Lisp, and C, and it works with non-programming text as well. For
4613 example, @code{find-tag} will jump to the various nodes in the
4614 Texinfo source file of this document.
4615 The @code{find-tag} function depends on @dfn{tags tables} that record
4616 the locations of the functions, variables, and other items to which
4617 @code{find-tag} jumps.
4619 To use the @code{find-tag} command, type @kbd{M-.} (i.e., press the
4620 period key while holding down the @key{META} key, or else type the
4621 @key{ESC} key and then type the period key), and then, at the prompt,
4622 type in the name of the function whose source code you want to see,
4623 such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will
4624 switch buffers and display the source code for the function on your
4625 screen. To switch back to your current buffer, type @kbd{C-x b
4626 @key{RET}}. (On some keyboards, the @key{META} key is labeled
4629 @c !!! 22.1.1 tags table location in this paragraph
4630 @cindex TAGS table, specifying
4632 Depending on how the initial default values of your copy of Emacs are
4633 set, you may also need to specify the location of your tags table,
4634 which is a file called @file{TAGS}. For example, if you are
4635 interested in Emacs sources, the tags table you will most likely want,
4636 if it has already been created for you, will be in a subdirectory of
4637 the @file{/usr/local/share/emacs/} directory; thus you would use the
4638 @code{M-x visit-tags-table} command and specify a pathname such as
4639 @file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table
4640 has not already been created, you will have to create it yourself. It
4641 will be in a file such as @file{/usr/local/src/emacs/src/TAGS}.
4644 To create a @file{TAGS} file in a specific directory, switch to that
4645 directory in Emacs using @kbd{M-x cd} command, or list the directory
4646 with @kbd{C-x d} (@code{dired}). Then run the compile command, with
4647 @w{@code{etags *.el}} as the command to execute:
4650 M-x compile RET etags *.el RET
4653 For more information, see @ref{etags, , Create Your Own @file{TAGS} File}.
4655 After you become more familiar with Emacs Lisp, you will find that you will
4656 frequently use @code{find-tag} to navigate your way around source code;
4657 and you will create your own @file{TAGS} tables.
4659 @cindex Library, as term for ``file''
4660 Incidentally, the files that contain Lisp code are conventionally
4661 called @dfn{libraries}. The metaphor is derived from that of a
4662 specialized library, such as a law library or an engineering library,
4663 rather than a general library. Each library, or file, contains
4664 functions that relate to a particular topic or activity, such as
4665 @file{abbrev.el} for handling abbreviations and other typing
4666 shortcuts, and @file{help.el} for help. (Sometimes several
4667 libraries provide code for a single activity, as the various
4668 @file{rmail@dots{}} files provide code for reading electronic mail.)
4669 In @cite{The GNU Emacs Manual}, you will see sentences such as ``The
4670 @kbd{C-h p} command lets you search the standard Emacs Lisp libraries
4671 by topic keywords.''
4673 @node simplified-beginning-of-buffer
4674 @section A Simplified @code{beginning-of-buffer} Definition
4675 @findex simplified-beginning-of-buffer
4677 The @code{beginning-of-buffer} command is a good function to start with
4678 since you are likely to be familiar with it and it is easy to
4679 understand. Used as an interactive command, @code{beginning-of-buffer}
4680 moves the cursor to the beginning of the buffer, leaving the mark at the
4681 previous position. It is generally bound to @kbd{M-<}.
4683 In this section, we will discuss a shortened version of the function
4684 that shows how it is most frequently used. This shortened function
4685 works as written, but it does not contain the code for a complex option.
4686 In another section, we will describe the entire function.
4687 (@xref{beginning-of-buffer, , Complete Definition of
4688 @code{beginning-of-buffer}}.)
4690 Before looking at the code, let's consider what the function
4691 definition has to contain: it must include an expression that makes
4692 the function interactive so it can be called by typing @kbd{M-x
4693 beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it
4694 must include code to leave a mark at the original position in the
4695 buffer; and it must include code to move the cursor to the beginning
4699 Here is the complete text of the shortened version of the function:
4703 (defun simplified-beginning-of-buffer ()
4704 "Move point to the beginning of the buffer;
4705 leave mark at previous position."
4708 (goto-char (point-min)))
4712 Like all function definitions, this definition has five parts following
4713 the macro @code{defun}:
4717 The name: in this example, @code{simplified-beginning-of-buffer}.
4720 A list of the arguments: in this example, an empty list, @code{()},
4723 The documentation string.
4726 The interactive expression.
4733 In this function definition, the argument list is empty; this means that
4734 this function does not require any arguments. (When we look at the
4735 definition for the complete function, we will see that it may be passed
4736 an optional argument.)
4738 The interactive expression tells Emacs that the function is intended to
4739 be used interactively. In this example, @code{interactive} does not have
4740 an argument because @code{simplified-beginning-of-buffer} does not
4744 The body of the function consists of the two lines:
4749 (goto-char (point-min))
4753 The first of these lines is the expression, @code{(push-mark)}. When
4754 this expression is evaluated by the Lisp interpreter, it sets a mark at
4755 the current position of the cursor, wherever that may be. The position
4756 of this mark is saved in the mark ring.
4758 The next line is @code{(goto-char (point-min))}. This expression
4759 jumps the cursor to the minimum point in the buffer, that is, to the
4760 beginning of the buffer (or to the beginning of the accessible portion
4761 of the buffer if it is narrowed. @xref{Narrowing & Widening, ,
4762 Narrowing and Widening}.)
4764 The @code{push-mark} command sets a mark at the place where the cursor
4765 was located before it was moved to the beginning of the buffer by the
4766 @code{(goto-char (point-min))} expression. Consequently, you can, if
4767 you wish, go back to where you were originally by typing @kbd{C-x C-x}.
4769 That is all there is to the function definition!
4771 @findex describe-function
4772 When you are reading code such as this and come upon an unfamiliar
4773 function, such as @code{goto-char}, you can find out what it does by
4774 using the @code{describe-function} command. To use this command, type
4775 @kbd{C-h f} and then type in the name of the function and press
4776 @key{RET}. The @code{describe-function} command will print the
4777 function's documentation string in a @file{*Help*} window. For
4778 example, the documentation for @code{goto-char} is:
4782 Set point to POSITION, a number or marker.
4783 Beginning of buffer is position (point-min), end is (point-max).
4788 The function's one argument is the desired position.
4791 (The prompt for @code{describe-function} will offer you the symbol
4792 under or preceding the cursor, so you can save typing by positioning
4793 the cursor right over or after the function and then typing @kbd{C-h f
4796 The @code{end-of-buffer} function definition is written in the same way as
4797 the @code{beginning-of-buffer} definition except that the body of the
4798 function contains the expression @code{(goto-char (point-max))} in place
4799 of @code{(goto-char (point-min))}.
4801 @node mark-whole-buffer
4802 @section The Definition of @code{mark-whole-buffer}
4803 @findex mark-whole-buffer
4805 The @code{mark-whole-buffer} function is no harder to understand than the
4806 @code{simplified-beginning-of-buffer} function. In this case, however,
4807 we will look at the complete function, not a shortened version.
4809 The @code{mark-whole-buffer} function is not as commonly used as the
4810 @code{beginning-of-buffer} function, but is useful nonetheless: it
4811 marks a whole buffer as a region by putting point at the beginning and
4812 a mark at the end of the buffer. It is generally bound to @kbd{C-x
4816 * mark-whole-buffer overview::
4817 * Body of mark-whole-buffer:: Only three lines of code.
4821 @node mark-whole-buffer overview
4822 @unnumberedsubsec An overview of @code{mark-whole-buffer}
4826 In GNU Emacs 22, the code for the complete function looks like this:
4830 (defun mark-whole-buffer ()
4831 "Put point at beginning and mark at end of buffer.
4832 You probably should not use this function in Lisp programs;
4833 it is usually a mistake for a Lisp function to use any subroutine
4834 that uses or sets the mark."
4837 (push-mark (point-max) nil t)
4838 (goto-char (point-min)))
4843 Like all other functions, the @code{mark-whole-buffer} function fits
4844 into the template for a function definition. The template looks like
4849 (defun @var{name-of-function} (@var{argument-list})
4850 "@var{documentation}@dots{}"
4851 (@var{interactive-expression}@dots{})
4856 Here is how the function works: the name of the function is
4857 @code{mark-whole-buffer}; it is followed by an empty argument list,
4858 @samp{()}, which means that the function does not require arguments.
4859 The documentation comes next.
4861 The next line is an @code{(interactive)} expression that tells Emacs
4862 that the function will be used interactively. These details are similar
4863 to the @code{simplified-beginning-of-buffer} function described in the
4867 @node Body of mark-whole-buffer
4868 @subsection Body of @code{mark-whole-buffer}
4870 The body of the @code{mark-whole-buffer} function consists of three
4877 (push-mark (point-max) nil t)
4878 (goto-char (point-min))
4882 The first of these lines is the expression, @code{(push-mark (point))}.
4884 This line does exactly the same job as the first line of the body of
4885 the @code{simplified-beginning-of-buffer} function, which is written
4886 @code{(push-mark)}. In both cases, the Lisp interpreter sets a mark
4887 at the current position of the cursor.
4889 I don't know why the expression in @code{mark-whole-buffer} is written
4890 @code{(push-mark (point))} and the expression in
4891 @code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps
4892 whoever wrote the code did not know that the arguments for
4893 @code{push-mark} are optional and that if @code{push-mark} is not
4894 passed an argument, the function automatically sets mark at the
4895 location of point by default. Or perhaps the expression was written
4896 so as to parallel the structure of the next line. In any case, the
4897 line causes Emacs to determine the position of point and set a mark
4900 In earlier versions of GNU Emacs, the next line of
4901 @code{mark-whole-buffer} was @code{(push-mark (point-max))}. This
4902 expression sets a mark at the point in the buffer that has the highest
4903 number. This will be the end of the buffer (or, if the buffer is
4904 narrowed, the end of the accessible portion of the buffer.
4905 @xref{Narrowing & Widening, , Narrowing and Widening}, for more about
4906 narrowing.) After this mark has been set, the previous mark, the one
4907 set at point, is no longer set, but Emacs remembers its position, just
4908 as all other recent marks are always remembered. This means that you
4909 can, if you wish, go back to that position by typing @kbd{C-u
4913 In GNU Emacs 22, the @code{(point-max)} is slightly more complicated.
4917 (push-mark (point-max) nil t)
4921 The expression works nearly the same as before. It sets a mark at the
4922 highest numbered place in the buffer that it can. However, in this
4923 version, @code{push-mark} has two additional arguments. The second
4924 argument to @code{push-mark} is @code{nil}. This tells the function
4925 it @emph{should} display a message that says ``Mark set'' when it pushes
4926 the mark. The third argument is @code{t}. This tells
4927 @code{push-mark} to activate the mark when Transient Mark mode is
4928 turned on. Transient Mark mode highlights the currently active
4929 region. It is often turned off.
4931 Finally, the last line of the function is @code{(goto-char
4932 (point-min)))}. This is written exactly the same way as it is written
4933 in @code{beginning-of-buffer}. The expression moves the cursor to
4934 the minimum point in the buffer, that is, to the beginning of the buffer
4935 (or to the beginning of the accessible portion of the buffer). As a
4936 result of this, point is placed at the beginning of the buffer and mark
4937 is set at the end of the buffer. The whole buffer is, therefore, the
4940 @c FIXME: the definition of append-to-buffer has been changed (in
4942 @node append-to-buffer
4943 @section The Definition of @code{append-to-buffer}
4944 @findex append-to-buffer
4946 The @code{append-to-buffer} command is more complex than the
4947 @code{mark-whole-buffer} command. What it does is copy the region
4948 (that is, the part of the buffer between point and mark) from the
4949 current buffer to a specified buffer.
4952 * append-to-buffer overview::
4953 * append interactive:: A two part interactive expression.
4954 * append-to-buffer body:: Incorporates a @code{let} expression.
4955 * append save-excursion:: How the @code{save-excursion} works.
4959 @node append-to-buffer overview
4960 @unnumberedsubsec An Overview of @code{append-to-buffer}
4963 @findex insert-buffer-substring
4964 The @code{append-to-buffer} command uses the
4965 @code{insert-buffer-substring} function to copy the region.
4966 @code{insert-buffer-substring} is described by its name: it takes a
4967 substring from a buffer, and inserts it into another buffer.
4969 Most of @code{append-to-buffer} is
4970 concerned with setting up the conditions for
4971 @code{insert-buffer-substring} to work: the code must specify both the
4972 buffer to which the text will go, the window it comes from and goes
4973 to, and the region that will be copied.
4976 Here is the complete text of the function:
4980 (defun append-to-buffer (buffer start end)
4981 "Append to specified buffer the text of the region.
4982 It is inserted into that buffer before its point.
4986 When calling from a program, give three arguments:
4987 BUFFER (or buffer name), START and END.
4988 START and END specify the portion of the current buffer to be copied."
4990 (list (read-buffer "Append to buffer: " (other-buffer
4991 (current-buffer) t))
4992 (region-beginning) (region-end)))
4995 (let ((oldbuf (current-buffer)))
4997 (let* ((append-to (get-buffer-create buffer))
4998 (windows (get-buffer-window-list append-to t t))
5000 (set-buffer append-to)
5001 (setq point (point))
5002 (barf-if-buffer-read-only)
5003 (insert-buffer-substring oldbuf start end)
5004 (dolist (window windows)
5005 (when (= (window-point window) point)
5006 (set-window-point window (point))))))))
5010 The function can be understood by looking at it as a series of
5011 filled-in templates.
5013 The outermost template is for the function definition. In this
5014 function, it looks like this (with several slots filled in):
5018 (defun append-to-buffer (buffer start end)
5019 "@var{documentation}@dots{}"
5020 (interactive @dots{})
5025 The first line of the function includes its name and three arguments.
5026 The arguments are the @code{buffer} to which the text will be copied, and
5027 the @code{start} and @code{end} of the region in the current buffer that
5030 The next part of the function is the documentation, which is clear and
5031 complete. As is conventional, the three arguments are written in
5032 upper case so you will notice them easily. Even better, they are
5033 described in the same order as in the argument list.
5035 Note that the documentation distinguishes between a buffer and its
5036 name. (The function can handle either.)
5038 @node append interactive
5039 @subsection The @code{append-to-buffer} Interactive Expression
5041 Since the @code{append-to-buffer} function will be used interactively,
5042 the function must have an @code{interactive} expression. (For a
5043 review of @code{interactive}, see @ref{Interactive, , Making a
5044 Function Interactive}.) The expression reads as follows:
5050 "Append to buffer: "
5051 (other-buffer (current-buffer) t))
5058 This expression is not one with letters standing for parts, as
5059 described earlier. Instead, it starts a list with these parts:
5061 The first part of the list is an expression to read the name of a
5062 buffer and return it as a string. That is @code{read-buffer}. The
5063 function requires a prompt as its first argument, @samp{"Append to
5064 buffer: "}. Its second argument tells the command what value to
5065 provide if you don't specify anything.
5067 In this case that second argument is an expression containing the
5068 function @code{other-buffer}, an exception, and a @samp{t}, standing
5071 The first argument to @code{other-buffer}, the exception, is yet
5072 another function, @code{current-buffer}. That is not going to be
5073 returned. The second argument is the symbol for true, @code{t}. that
5074 tells @code{other-buffer} that it may show visible buffers (except in
5075 this case, it will not show the current buffer, which makes sense).
5078 The expression looks like this:
5081 (other-buffer (current-buffer) t)
5084 The second and third arguments to the @code{list} expression are
5085 @code{(region-beginning)} and @code{(region-end)}. These two
5086 functions specify the beginning and end of the text to be appended.
5089 Originally, the command used the letters @samp{B} and @samp{r}.
5090 The whole @code{interactive} expression looked like this:
5093 (interactive "BAppend to buffer:@: \nr")
5097 But when that was done, the default value of the buffer switched to
5098 was invisible. That was not wanted.
5100 (The prompt was separated from the second argument with a newline,
5101 @samp{\n}. It was followed by an @samp{r} that told Emacs to bind the
5102 two arguments that follow the symbol @code{buffer} in the function's
5103 argument list (that is, @code{start} and @code{end}) to the values of
5104 point and mark. That argument worked fine.)
5106 @node append-to-buffer body
5107 @subsection The Body of @code{append-to-buffer}
5110 in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el
5112 (defun append-to-buffer (buffer start end)
5113 "Append to specified buffer the text of the region.
5114 It is inserted into that buffer before its point.
5116 When calling from a program, give three arguments:
5117 BUFFER (or buffer name), START and END.
5118 START and END specify the portion of the current buffer to be copied."
5120 (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t))
5121 (region-beginning) (region-end)))
5122 (let ((oldbuf (current-buffer)))
5124 (let* ((append-to (get-buffer-create buffer))
5125 (windows (get-buffer-window-list append-to t t))
5127 (set-buffer append-to)
5128 (setq point (point))
5129 (barf-if-buffer-read-only)
5130 (insert-buffer-substring oldbuf start end)
5131 (dolist (window windows)
5132 (when (= (window-point window) point)
5133 (set-window-point window (point))))))))
5136 The body of the @code{append-to-buffer} function begins with @code{let}.
5138 As we have seen before (@pxref{let, , @code{let}}), the purpose of a
5139 @code{let} expression is to create and give initial values to one or
5140 more variables that will only be used within the body of the
5141 @code{let}. This means that such a variable will not be confused with
5142 any variable of the same name outside the @code{let} expression.
5144 We can see how the @code{let} expression fits into the function as a
5145 whole by showing a template for @code{append-to-buffer} with the
5146 @code{let} expression in outline:
5150 (defun append-to-buffer (buffer start end)
5151 "@var{documentation}@dots{}"
5152 (interactive @dots{})
5153 (let ((@var{variable} @var{value}))
5158 The @code{let} expression has three elements:
5162 The symbol @code{let};
5165 A varlist containing, in this case, a single two-element list,
5166 @code{(@var{variable} @var{value})};
5169 The body of the @code{let} expression.
5173 In the @code{append-to-buffer} function, the varlist looks like this:
5176 (oldbuf (current-buffer))
5180 In this part of the @code{let} expression, the one variable,
5181 @code{oldbuf}, is bound to the value returned by the
5182 @code{(current-buffer)} expression. The variable, @code{oldbuf}, is
5183 used to keep track of the buffer in which you are working and from
5184 which you will copy.
5186 The element or elements of a varlist are surrounded by a set of
5187 parentheses so the Lisp interpreter can distinguish the varlist from
5188 the body of the @code{let}. As a consequence, the two-element list
5189 within the varlist is surrounded by a circumscribing set of parentheses.
5190 The line looks like this:
5194 (let ((oldbuf (current-buffer)))
5200 The two parentheses before @code{oldbuf} might surprise you if you did
5201 not realize that the first parenthesis before @code{oldbuf} marks the
5202 boundary of the varlist and the second parenthesis marks the beginning
5203 of the two-element list, @code{(oldbuf (current-buffer))}.
5205 @node append save-excursion
5206 @subsection @code{save-excursion} in @code{append-to-buffer}
5208 The body of the @code{let} expression in @code{append-to-buffer}
5209 consists of a @code{save-excursion} expression.
5211 The @code{save-excursion} function saves the location of point, and restores it
5212 to that position after the expressions in the
5213 body of the @code{save-excursion} complete execution. In addition,
5214 @code{save-excursion} keeps track of the original buffer, and
5215 restores it. This is how @code{save-excursion} is used in
5216 @code{append-to-buffer}.
5219 @cindex Indentation for formatting
5220 @cindex Formatting convention
5221 Incidentally, it is worth noting here that a Lisp function is normally
5222 formatted so that everything that is enclosed in a multi-line spread is
5223 indented more to the right than the first symbol. In this function
5224 definition, the @code{let} is indented more than the @code{defun}, and
5225 the @code{save-excursion} is indented more than the @code{let}, like
5241 This formatting convention makes it easy to see that the lines in
5242 the body of the @code{save-excursion} are enclosed by the parentheses
5243 associated with @code{save-excursion}, just as the
5244 @code{save-excursion} itself is enclosed by the parentheses associated
5245 with the @code{let}:
5249 (let ((oldbuf (current-buffer)))
5252 (set-buffer @dots{})
5253 (insert-buffer-substring oldbuf start end)
5259 The use of the @code{save-excursion} function can be viewed as a process
5260 of filling in the slots of a template:
5265 @var{first-expression-in-body}
5266 @var{second-expression-in-body}
5268 @var{last-expression-in-body})
5274 In this function, the body of the @code{save-excursion} contains only
5275 one expression, the @code{let*} expression. You know about a
5276 @code{let} function. The @code{let*} function is different. It has a
5277 @samp{*} in its name. It enables Emacs to set each variable in its
5278 varlist in sequence, one after another.
5280 Its critical feature is that variables later in the varlist can make
5281 use of the values to which Emacs set variables earlier in the varlist.
5282 @xref{fwd-para let, , The @code{let*} expression}.
5284 We will skip functions like @code{let*} and focus on two: the
5285 @code{set-buffer} function and the @code{insert-buffer-substring}
5289 In the old days, the @code{set-buffer} expression was simply
5292 (set-buffer (get-buffer-create buffer))
5300 (set-buffer append-to)
5304 @code{append-to} is bound to @code{(get-buffer-create buffer)} earlier
5305 on in the @code{let*} expression. That extra binding would not be
5306 necessary except for that @code{append-to} is used later in the
5307 varlist as an argument to @code{get-buffer-window-list}.
5312 (let ((oldbuf (current-buffer)))
5314 (let* ((append-to (get-buffer-create buffer))
5315 (windows (get-buffer-window-list append-to t t))
5317 (set-buffer append-to)
5318 (setq point (point))
5319 (barf-if-buffer-read-only)
5320 (insert-buffer-substring oldbuf start end)
5321 (dolist (window windows)
5322 (when (= (window-point window) point)
5323 (set-window-point window (point))))))))
5326 The @code{append-to-buffer} function definition inserts text from the
5327 buffer in which you are currently to a named buffer. It happens that
5328 @code{insert-buffer-substring} copies text from another buffer to the
5329 current buffer, just the reverse---that is why the
5330 @code{append-to-buffer} definition starts out with a @code{let} that
5331 binds the local symbol @code{oldbuf} to the value returned by
5332 @code{current-buffer}.
5335 The @code{insert-buffer-substring} expression looks like this:
5338 (insert-buffer-substring oldbuf start end)
5342 The @code{insert-buffer-substring} function copies a string
5343 @emph{from} the buffer specified as its first argument and inserts the
5344 string into the present buffer. In this case, the argument to
5345 @code{insert-buffer-substring} is the value of the variable created
5346 and bound by the @code{let}, namely the value of @code{oldbuf}, which
5347 was the current buffer when you gave the @code{append-to-buffer}
5350 After @code{insert-buffer-substring} has done its work,
5351 @code{save-excursion} will restore the action to the original buffer
5352 and @code{append-to-buffer} will have done its job.
5355 Written in skeletal form, the workings of the body look like this:
5359 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5360 (save-excursion ; @r{Keep track of buffer.}
5362 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})
5364 @var{change-back-to-original-buffer-when-finished}
5365 @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished}
5369 In summary, @code{append-to-buffer} works as follows: it saves the
5370 value of the current buffer in the variable called @code{oldbuf}. It
5371 gets the new buffer (creating one if need be) and switches Emacs's
5372 attention to it. Using the value of @code{oldbuf}, it inserts the
5373 region of text from the old buffer into the new buffer; and then using
5374 @code{save-excursion}, it brings you back to your original buffer.
5376 In looking at @code{append-to-buffer}, you have explored a fairly
5377 complex function. It shows how to use @code{let} and
5378 @code{save-excursion}, and how to change to and come back from another
5379 buffer. Many function definitions use @code{let},
5380 @code{save-excursion}, and @code{set-buffer} this way.
5382 @node Buffer Related Review
5385 Here is a brief summary of the various functions discussed in this chapter.
5388 @item describe-function
5389 @itemx describe-variable
5390 Print the documentation for a function or variable.
5391 Conventionally bound to @kbd{C-h f} and @kbd{C-h v}.
5394 Find the file containing the source for a function or variable and
5395 switch buffers to it, positioning point at the beginning of the item.
5396 Conventionally bound to @kbd{M-.} (that's a period following the
5399 @item save-excursion
5400 Save the location of point and restore its value after the
5401 arguments to @code{save-excursion} have been evaluated. Also, remember
5402 the current buffer and return to it.
5405 Set mark at a location and record the value of the previous mark on the
5406 mark ring. The mark is a location in the buffer that will keep its
5407 relative position even if text is added to or removed from the buffer.
5410 Set point to the location specified by the value of the argument, which
5411 can be a number, a marker, or an expression that returns the number of
5412 a position, such as @code{(point-min)}.
5414 @item insert-buffer-substring
5415 Copy a region of text from a buffer that is passed to the function as
5416 an argument and insert the region into the current buffer.
5418 @item mark-whole-buffer
5419 Mark the whole buffer as a region. Normally bound to @kbd{C-x h}.
5422 Switch the attention of Emacs to another buffer, but do not change the
5423 window being displayed. Used when the program rather than a human is
5424 to work on a different buffer.
5426 @item get-buffer-create
5428 Find a named buffer or create one if a buffer of that name does not
5429 exist. The @code{get-buffer} function returns @code{nil} if the named
5430 buffer does not exist.
5434 @node Buffer Exercises
5439 Write your own @code{simplified-end-of-buffer} function definition;
5440 then test it to see whether it works.
5443 Use @code{if} and @code{get-buffer} to write a function that prints a
5444 message telling you whether a buffer exists.
5447 Using @code{find-tag}, find the source for the @code{copy-to-buffer}
5452 @chapter A Few More Complex Functions
5454 In this chapter, we build on what we have learned in previous chapters
5455 by looking at more complex functions. The @code{copy-to-buffer}
5456 function illustrates use of two @code{save-excursion} expressions in
5457 one definition, while the @code{insert-buffer} function illustrates
5458 use of an asterisk in an @code{interactive} expression, use of
5459 @code{or}, and the important distinction between a name and the object
5460 to which the name refers.
5463 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
5464 * insert-buffer:: Read-only, and with @code{or}.
5465 * beginning-of-buffer:: Shows @code{goto-char},
5466 @code{point-min}, and @code{push-mark}.
5467 * Second Buffer Related Review::
5468 * optional Exercise::
5471 @node copy-to-buffer
5472 @section The Definition of @code{copy-to-buffer}
5473 @findex copy-to-buffer
5475 After understanding how @code{append-to-buffer} works, it is easy to
5476 understand @code{copy-to-buffer}. This function copies text into a
5477 buffer, but instead of adding to the second buffer, it replaces all the
5478 previous text in the second buffer.
5481 The body of @code{copy-to-buffer} looks like this,
5486 (interactive "BCopy to buffer: \nr")
5487 (let ((oldbuf (current-buffer)))
5488 (with-current-buffer (get-buffer-create buffer)
5489 (barf-if-buffer-read-only)
5492 (insert-buffer-substring oldbuf start end)))))
5496 The @code{copy-to-buffer} function has a simpler @code{interactive}
5497 expression than @code{append-to-buffer}.
5500 The definition then says
5503 (with-current-buffer (get-buffer-create buffer) @dots{}
5506 First, look at the earliest inner expression; that is evaluated first.
5507 That expression starts with @code{get-buffer-create buffer}. The
5508 function tells the computer to use the buffer with the name specified
5509 as the one to which you are copying, or if such a buffer does not
5510 exist, to create it. Then, the @code{with-current-buffer} function
5511 evaluates its body with that buffer temporarily current.
5513 (This demonstrates another way to shift the computer's attention but
5514 not the user's. The @code{append-to-buffer} function showed how to do
5515 the same with @code{save-excursion} and @code{set-buffer}.
5516 @code{with-current-buffer} is a newer, and arguably easier,
5519 The @code{barf-if-buffer-read-only} function sends you an error
5520 message saying the buffer is read-only if you cannot modify it.
5522 The next line has the @code{erase-buffer} function as its sole
5523 contents. That function erases the buffer.
5525 Finally, the last two lines contain the @code{save-excursion}
5526 expression with @code{insert-buffer-substring} as its body.
5527 The @code{insert-buffer-substring} expression copies the text from
5528 the buffer you are in (and you have not seen the computer shift its
5529 attention, so you don't know that that buffer is now called
5532 Incidentally, this is what is meant by ``replacement''. To replace text,
5533 Emacs erases the previous text and then inserts new text.
5536 In outline, the body of @code{copy-to-buffer} looks like this:
5540 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5541 (@var{with-the-buffer-you-are-copying-to}
5542 (@var{but-do-not-erase-or-copy-to-a-read-only-buffer})
5545 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})))
5550 @section The Definition of @code{insert-buffer}
5551 @findex insert-buffer
5553 @code{insert-buffer} is yet another buffer-related function. This
5554 command copies another buffer @emph{into} the current buffer. It is the
5555 reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they
5556 copy a region of text @emph{from} the current buffer to another buffer.
5558 Here is a discussion based on the original code. The code was
5559 simplified in 2003 and is harder to understand.
5561 (@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see
5562 a discussion of the new body.)
5564 In addition, this code illustrates the use of @code{interactive} with a
5565 buffer that might be @dfn{read-only} and the important distinction
5566 between the name of an object and the object actually referred to.
5569 * insert-buffer code::
5570 * insert-buffer interactive:: When you can read, but not write.
5571 * insert-buffer body:: The body has an @code{or} and a @code{let}.
5572 * if & or:: Using an @code{if} instead of an @code{or}.
5573 * Insert or:: How the @code{or} expression works.
5574 * Insert let:: Two @code{save-excursion} expressions.
5575 * New insert-buffer::
5579 @node insert-buffer code
5580 @unnumberedsubsec The Code for @code{insert-buffer}
5584 Here is the earlier code:
5588 (defun insert-buffer (buffer)
5589 "Insert after point the contents of BUFFER.
5590 Puts mark after the inserted text.
5591 BUFFER may be a buffer or a buffer name."
5592 (interactive "*bInsert buffer:@: ")
5595 (or (bufferp buffer)
5596 (setq buffer (get-buffer buffer)))
5597 (let (start end newmark)
5601 (setq start (point-min) end (point-max)))
5604 (insert-buffer-substring buffer start end)
5605 (setq newmark (point)))
5606 (push-mark newmark)))
5611 As with other function definitions, you can use a template to see an
5612 outline of the function:
5616 (defun insert-buffer (buffer)
5617 "@var{documentation}@dots{}"
5618 (interactive "*bInsert buffer:@: ")
5623 @node insert-buffer interactive
5624 @subsection The Interactive Expression in @code{insert-buffer}
5625 @findex interactive, @r{example use of}
5627 In @code{insert-buffer}, the argument to the @code{interactive}
5628 declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert
5632 * Read-only buffer:: When a buffer cannot be modified.
5633 * b for interactive:: An existing buffer or else its name.
5636 @node Read-only buffer
5637 @unnumberedsubsubsec A Read-only Buffer
5638 @cindex Read-only buffer
5639 @cindex Asterisk for read-only buffer
5640 @findex * @r{for read-only buffer}
5642 The asterisk is for the situation when the current buffer is a
5643 read-only buffer---a buffer that cannot be modified. If
5644 @code{insert-buffer} is called when the current buffer is read-only, a
5645 message to this effect is printed in the echo area and the terminal
5646 may beep or blink at you; you will not be permitted to insert anything
5647 into current buffer. The asterisk does not need to be followed by a
5648 newline to separate it from the next argument.
5650 @node b for interactive
5651 @unnumberedsubsubsec @samp{b} in an Interactive Expression
5653 The next argument in the interactive expression starts with a lower
5654 case @samp{b}. (This is different from the code for
5655 @code{append-to-buffer}, which uses an upper-case @samp{B}.
5656 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
5657 The lower-case @samp{b} tells the Lisp interpreter that the argument
5658 for @code{insert-buffer} should be an existing buffer or else its
5659 name. (The upper-case @samp{B} option provides for the possibility
5660 that the buffer does not exist.) Emacs will prompt you for the name
5661 of the buffer, offering you a default buffer, with name completion
5662 enabled. If the buffer does not exist, you receive a message that
5663 says ``No match''; your terminal may beep at you as well.
5665 The new and simplified code generates a list for @code{interactive}.
5666 It uses the @code{barf-if-buffer-read-only} and @code{read-buffer}
5667 functions with which we are already familiar and the @code{progn}
5668 special form with which we are not. (It will be described later.)
5670 @node insert-buffer body
5671 @subsection The Body of the @code{insert-buffer} Function
5673 The body of the @code{insert-buffer} function has two major parts: an
5674 @code{or} expression and a @code{let} expression. The purpose of the
5675 @code{or} expression is to ensure that the argument @code{buffer} is
5676 bound to a buffer and not just the name of a buffer. The body of the
5677 @code{let} expression contains the code which copies the other buffer
5678 into the current buffer.
5681 In outline, the two expressions fit into the @code{insert-buffer}
5686 (defun insert-buffer (buffer)
5687 "@var{documentation}@dots{}"
5688 (interactive "*bInsert buffer:@: ")
5693 (let (@var{varlist})
5694 @var{body-of-}@code{let}@dots{} )
5698 To understand how the @code{or} expression ensures that the argument
5699 @code{buffer} is bound to a buffer and not to the name of a buffer, it
5700 is first necessary to understand the @code{or} function.
5702 Before doing this, let me rewrite this part of the function using
5703 @code{if} so that you can see what is done in a manner that will be familiar.
5706 @subsection @code{insert-buffer} With an @code{if} Instead of an @code{or}
5708 The job to be done is to make sure the value of @code{buffer} is a
5709 buffer itself and not the name of a buffer. If the value is the name,
5710 then the buffer itself must be got.
5712 You can imagine yourself at a conference where an usher is wandering
5713 around holding a list with your name on it and looking for you: the
5714 usher is bound to your name, not to you; but when the usher finds
5715 you and takes your arm, the usher becomes bound to you.
5718 In Lisp, you might describe this situation like this:
5722 (if (not (holding-on-to-guest))
5723 (find-and-take-arm-of-guest))
5727 We want to do the same thing with a buffer---if we do not have the
5728 buffer itself, we want to get it.
5731 Using a predicate called @code{bufferp} that tells us whether we have a
5732 buffer (rather than its name), we can write the code like this:
5736 (if (not (bufferp buffer)) ; @r{if-part}
5737 (setq buffer (get-buffer buffer))) ; @r{then-part}
5742 Here, the true-or-false-test of the @code{if} expression is
5743 @w{@code{(not (bufferp buffer))}}; and the then-part is the expression
5744 @w{@code{(setq buffer (get-buffer buffer))}}.
5746 In the test, the function @code{bufferp} returns true if its argument is
5747 a buffer---but false if its argument is the name of the buffer. (The
5748 last character of the function name @code{bufferp} is the character
5749 @samp{p}; as we saw earlier, such use of @samp{p} is a convention that
5750 indicates that the function is a predicate, which is a term that means
5751 that the function will determine whether some property is true or false.
5752 @xref{Wrong Type of Argument, , Using the Wrong Type Object as an
5756 The function @code{not} precedes the expression @code{(bufferp buffer)},
5757 so the true-or-false-test looks like this:
5760 (not (bufferp buffer))
5764 @code{not} is a function that returns true if its argument is false
5765 and false if its argument is true. So if @code{(bufferp buffer)}
5766 returns true, the @code{not} expression returns false and vice versa.
5768 Using this test, the @code{if} expression works as follows: when the
5769 value of the variable @code{buffer} is actually a buffer rather than
5770 its name, the true-or-false-test returns false and the @code{if}
5771 expression does not evaluate the then-part. This is fine, since we do
5772 not need to do anything to the variable @code{buffer} if it really is
5775 On the other hand, when the value of @code{buffer} is not a buffer
5776 itself, but the name of a buffer, the true-or-false-test returns true
5777 and the then-part of the expression is evaluated. In this case, the
5778 then-part is @code{(setq buffer (get-buffer buffer))}. This
5779 expression uses the @code{get-buffer} function to return an actual
5780 buffer itself, given its name. The @code{setq} then sets the variable
5781 @code{buffer} to the value of the buffer itself, replacing its previous
5782 value (which was the name of the buffer).
5785 @subsection The @code{or} in the Body
5787 The purpose of the @code{or} expression in the @code{insert-buffer}
5788 function is to ensure that the argument @code{buffer} is bound to a
5789 buffer and not just to the name of a buffer. The previous section shows
5790 how the job could have been done using an @code{if} expression.
5791 However, the @code{insert-buffer} function actually uses @code{or}.
5792 To understand this, it is necessary to understand how @code{or} works.
5795 An @code{or} function can have any number of arguments. It evaluates
5796 each argument in turn and returns the value of the first of its
5797 arguments that is not @code{nil}. Also, and this is a crucial feature
5798 of @code{or}, it does not evaluate any subsequent arguments after
5799 returning the first non-@code{nil} value.
5802 The @code{or} expression looks like this:
5806 (or (bufferp buffer)
5807 (setq buffer (get-buffer buffer)))
5812 The first argument to @code{or} is the expression @code{(bufferp buffer)}.
5813 This expression returns true (a non-@code{nil} value) if the buffer is
5814 actually a buffer, and not just the name of a buffer. In the @code{or}
5815 expression, if this is the case, the @code{or} expression returns this
5816 true value and does not evaluate the next expression---and this is fine
5817 with us, since we do not want to do anything to the value of
5818 @code{buffer} if it really is a buffer.
5820 On the other hand, if the value of @code{(bufferp buffer)} is @code{nil},
5821 which it will be if the value of @code{buffer} is the name of a buffer,
5822 the Lisp interpreter evaluates the next element of the @code{or}
5823 expression. This is the expression @code{(setq buffer (get-buffer
5824 buffer))}. This expression returns a non-@code{nil} value, which
5825 is the value to which it sets the variable @code{buffer}---and this
5826 value is a buffer itself, not the name of a buffer.
5828 The result of all this is that the symbol @code{buffer} is always
5829 bound to a buffer itself rather than to the name of a buffer. All
5830 this is necessary because the @code{set-buffer} function in a
5831 following line only works with a buffer itself, not with the name to a
5835 Incidentally, using @code{or}, the situation with the usher would be
5839 (or (holding-on-to-guest) (find-and-take-arm-of-guest))
5843 @subsection The @code{let} Expression in @code{insert-buffer}
5845 After ensuring that the variable @code{buffer} refers to a buffer itself
5846 and not just to the name of a buffer, the @code{insert-buffer function}
5847 continues with a @code{let} expression. This specifies three local
5848 variables, @code{start}, @code{end}, and @code{newmark} and binds them
5849 to the initial value @code{nil}. These variables are used inside the
5850 remainder of the @code{let} and temporarily hide any other occurrence of
5851 variables of the same name in Emacs until the end of the @code{let}.
5854 The body of the @code{let} contains two @code{save-excursion}
5855 expressions. First, we will look at the inner @code{save-excursion}
5856 expression in detail. The expression looks like this:
5862 (setq start (point-min) end (point-max)))
5867 The expression @code{(set-buffer buffer)} changes Emacs's attention
5868 from the current buffer to the one from which the text will copied.
5869 In that buffer, the variables @code{start} and @code{end} are set to
5870 the beginning and end of the buffer, using the commands
5871 @code{point-min} and @code{point-max}. Note that we have here an
5872 illustration of how @code{setq} is able to set two variables in the
5873 same expression. The first argument of @code{setq} is set to the
5874 value of its second, and its third argument is set to the value of its
5877 After the body of the inner @code{save-excursion} is evaluated, the
5878 @code{save-excursion} restores the original buffer, but @code{start} and
5879 @code{end} remain set to the values of the beginning and end of the
5880 buffer from which the text will be copied.
5883 The outer @code{save-excursion} expression looks like this:
5888 (@var{inner-}@code{save-excursion}@var{-expression}
5889 (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end})
5890 (insert-buffer-substring buffer start end)
5891 (setq newmark (point)))
5896 The @code{insert-buffer-substring} function copies the text
5897 @emph{into} the current buffer @emph{from} the region indicated by
5898 @code{start} and @code{end} in @code{buffer}. Since the whole of the
5899 second buffer lies between @code{start} and @code{end}, the whole of
5900 the second buffer is copied into the buffer you are editing. Next,
5901 the value of point, which will be at the end of the inserted text, is
5902 recorded in the variable @code{newmark}.
5904 After the body of the outer @code{save-excursion} is evaluated, point
5905 is relocated to its original place.
5907 However, it is convenient to locate a mark at the end of the newly
5908 inserted text and locate point at its beginning. The @code{newmark}
5909 variable records the end of the inserted text. In the last line of
5910 the @code{let} expression, the @code{(push-mark newmark)} expression
5911 function sets a mark to this location. (The previous location of the
5912 mark is still accessible; it is recorded on the mark ring and you can
5913 go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is
5914 located at the beginning of the inserted text, which is where it was
5915 before you called the insert function, the position of which was saved
5916 by the first @code{save-excursion}.
5919 The whole @code{let} expression looks like this:
5923 (let (start end newmark)
5927 (setq start (point-min) end (point-max)))
5928 (insert-buffer-substring buffer start end)
5929 (setq newmark (point)))
5930 (push-mark newmark))
5934 Like the @code{append-to-buffer} function, the @code{insert-buffer}
5935 function uses @code{let}, @code{save-excursion}, and
5936 @code{set-buffer}. In addition, the function illustrates one way to
5937 use @code{or}. All these functions are building blocks that we will
5938 find and use again and again.
5940 @node New insert-buffer
5941 @subsection New Body for @code{insert-buffer}
5942 @findex insert-buffer, new version body
5943 @findex new version body for insert-buffer
5945 The body in the GNU Emacs 22 version is more confusing than the original.
5948 It consists of two expressions,
5954 (insert-buffer-substring (get-buffer buffer))
5962 except, and this is what confuses novices, very important work is done
5963 inside the @code{push-mark} expression.
5965 The @code{get-buffer} function returns a buffer with the name
5966 provided. You will note that the function is @emph{not} called
5967 @code{get-buffer-create}; it does not create a buffer if one does not
5968 already exist. The buffer returned by @code{get-buffer}, an existing
5969 buffer, is passed to @code{insert-buffer-substring}, which inserts the
5970 whole of the buffer (since you did not specify anything else).
5972 The location into which the buffer is inserted is recorded by
5973 @code{push-mark}. Then the function returns @code{nil}, the value of
5974 its last command. Put another way, the @code{insert-buffer} function
5975 exists only to produce a side effect, inserting another buffer, not to
5978 @node beginning-of-buffer
5979 @section Complete Definition of @code{beginning-of-buffer}
5980 @findex beginning-of-buffer
5982 The basic structure of the @code{beginning-of-buffer} function has
5983 already been discussed. (@xref{simplified-beginning-of-buffer, , A
5984 Simplified @code{beginning-of-buffer} Definition}.)
5985 This section describes the complex part of the definition.
5987 As previously described, when invoked without an argument,
5988 @code{beginning-of-buffer} moves the cursor to the beginning of the
5989 buffer (in truth, the beginning of the accessible portion of the
5990 buffer), leaving the mark at the previous position. However, when the
5991 command is invoked with a number between one and ten, the function
5992 considers that number to be a fraction of the length of the buffer,
5993 measured in tenths, and Emacs moves the cursor that fraction of the
5994 way from the beginning of the buffer. Thus, you can either call this
5995 function with the key command @kbd{M-<}, which will move the cursor to
5996 the beginning of the buffer, or with a key command such as @kbd{C-u 7
5997 M-<} which will move the cursor to a point 70% of the way through the
5998 buffer. If a number bigger than ten is used for the argument, it
5999 moves to the end of the buffer.
6001 The @code{beginning-of-buffer} function can be called with or without an
6002 argument. The use of the argument is optional.
6005 * Optional Arguments::
6006 * beginning-of-buffer opt arg:: Example with optional argument.
6007 * beginning-of-buffer complete::
6010 @node Optional Arguments
6011 @subsection Optional Arguments
6013 Unless told otherwise, Lisp expects that a function with an argument in
6014 its function definition will be called with a value for that argument.
6015 If that does not happen, you get an error and a message that says
6016 @samp{Wrong number of arguments}.
6018 @cindex Optional arguments
6021 However, optional arguments are a feature of Lisp: a particular
6022 @dfn{keyword} is used to tell the Lisp interpreter that an argument is
6023 optional. The keyword is @code{&optional}. (The @samp{&} in front of
6024 @samp{optional} is part of the keyword.) In a function definition, if
6025 an argument follows the keyword @code{&optional}, no value need be
6026 passed to that argument when the function is called.
6029 The first line of the function definition of @code{beginning-of-buffer}
6030 therefore looks like this:
6033 (defun beginning-of-buffer (&optional arg)
6037 In outline, the whole function looks like this:
6041 (defun beginning-of-buffer (&optional arg)
6042 "@var{documentation}@dots{}"
6044 (or (@var{is-the-argument-a-cons-cell} arg)
6045 (and @var{are-both-transient-mark-mode-and-mark-active-true})
6047 (let (@var{determine-size-and-set-it})
6049 (@var{if-there-is-an-argument}
6050 @var{figure-out-where-to-go}
6057 The function is similar to the @code{simplified-beginning-of-buffer}
6058 function except that the @code{interactive} expression has @code{"P"}
6059 as an argument and the @code{goto-char} function is followed by an
6060 if-then-else expression that figures out where to put the cursor if
6061 there is an argument that is not a cons cell.
6063 (Since I do not explain a cons cell for many more chapters, please
6064 consider ignoring the function @code{consp}. @xref{List
6065 Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type,
6066 , Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference
6069 The @code{"P"} in the @code{interactive} expression tells Emacs to
6070 pass a prefix argument, if there is one, to the function in raw form.
6071 A prefix argument is made by typing the @key{META} key followed by a
6072 number, or by typing @kbd{C-u} and then a number. (If you don't type
6073 a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase
6074 @code{"p"} in the @code{interactive} expression causes the function to
6075 convert a prefix arg to a number.)
6077 The true-or-false-test of the @code{if} expression looks complex, but
6078 it is not: it checks whether @code{arg} has a value that is not
6079 @code{nil} and whether it is a cons cell. (That is what @code{consp}
6080 does; it checks whether its argument is a cons cell.) If @code{arg}
6081 has a value that is not @code{nil} (and is not a cons cell), which
6082 will be the case if @code{beginning-of-buffer} is called with a
6083 numeric argument, then this true-or-false-test will return true and
6084 the then-part of the @code{if} expression will be evaluated. On the
6085 other hand, if @code{beginning-of-buffer} is not called with an
6086 argument, the value of @code{arg} will be @code{nil} and the else-part
6087 of the @code{if} expression will be evaluated. The else-part is
6088 simply @code{point-min}, and when this is the outcome, the whole
6089 @code{goto-char} expression is @code{(goto-char (point-min))}, which
6090 is how we saw the @code{beginning-of-buffer} function in its
6093 @node beginning-of-buffer opt arg
6094 @subsection @code{beginning-of-buffer} with an Argument
6096 When @code{beginning-of-buffer} is called with an argument, an
6097 expression is evaluated which calculates what value to pass to
6098 @code{goto-char}. This expression is rather complicated at first sight.
6099 It includes an inner @code{if} expression and much arithmetic. It looks
6104 (if (> (buffer-size) 10000)
6105 ;; @r{Avoid overflow for large buffer sizes!}
6106 (* (prefix-numeric-value arg)
6111 size (prefix-numeric-value arg))) 10)))
6116 * Disentangle beginning-of-buffer::
6117 * Large buffer case::
6118 * Small buffer case::
6122 @node Disentangle beginning-of-buffer
6123 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer}
6126 Like other complex-looking expressions, the conditional expression
6127 within @code{beginning-of-buffer} can be disentangled by looking at it
6128 as parts of a template, in this case, the template for an if-then-else
6129 expression. In skeletal form, the expression looks like this:
6133 (if (@var{buffer-is-large}
6134 @var{divide-buffer-size-by-10-and-multiply-by-arg}
6135 @var{else-use-alternate-calculation}
6139 The true-or-false-test of this inner @code{if} expression checks the
6140 size of the buffer. The reason for this is that the old version 18
6141 Emacs used numbers that are no bigger than eight million or so and in
6142 the computation that followed, the programmer feared that Emacs might
6143 try to use over-large numbers if the buffer were large. The term
6144 ``overflow'', mentioned in the comment, means numbers that are over
6145 large. More recent versions of Emacs use larger numbers, but this
6146 code has not been touched, if only because people now look at buffers
6147 that are far, far larger than ever before.
6149 There are two cases: if the buffer is large and if it is not.
6151 @node Large buffer case
6152 @unnumberedsubsubsec What happens in a large buffer
6154 In @code{beginning-of-buffer}, the inner @code{if} expression tests
6155 whether the size of the buffer is greater than 10,000 characters. To do
6156 this, it uses the @code{>} function and the computation of @code{size}
6157 that comes from the let expression.
6159 In the old days, the function @code{buffer-size} was used. Not only
6160 was that function called several times, it gave the size of the whole
6161 buffer, not the accessible part. The computation makes much more
6162 sense when it handles just the accessible part. (@xref{Narrowing &
6163 Widening, , Narrowing and Widening}, for more information on focusing
6164 attention to an accessible part.)
6167 The line looks like this:
6175 When the buffer is large, the then-part of the @code{if} expression is
6176 evaluated. It reads like this (after formatting for easy reading):
6181 (prefix-numeric-value arg)
6187 This expression is a multiplication, with two arguments to the function
6190 The first argument is @code{(prefix-numeric-value arg)}. When
6191 @code{"P"} is used as the argument for @code{interactive}, the value
6192 passed to the function as its argument is passed a @dfn{raw prefix
6193 argument}, and not a number. (It is a number in a list.) To perform
6194 the arithmetic, a conversion is necessary, and
6195 @code{prefix-numeric-value} does the job.
6197 @findex / @r{(division)}
6199 The second argument is @code{(/ size 10)}. This expression divides
6200 the numeric value by ten---the numeric value of the size of the
6201 accessible portion of the buffer. This produces a number that tells
6202 how many characters make up one tenth of the buffer size. (In Lisp,
6203 @code{/} is used for division, just as @code{*} is used for
6207 In the multiplication expression as a whole, this amount is multiplied
6208 by the value of the prefix argument---the multiplication looks like this:
6212 (* @var{numeric-value-of-prefix-arg}
6213 @var{number-of-characters-in-one-tenth-of-the-accessible-buffer})
6218 If, for example, the prefix argument is @samp{7}, the one-tenth value
6219 will be multiplied by 7 to give a position 70% of the way through.
6222 The result of all this is that if the accessible portion of the buffer
6223 is large, the @code{goto-char} expression reads like this:
6227 (goto-char (* (prefix-numeric-value arg)
6232 This puts the cursor where we want it.
6234 @node Small buffer case
6235 @unnumberedsubsubsec What happens in a small buffer
6237 If the buffer contains fewer than 10,000 characters, a slightly
6238 different computation is performed. You might think this is not
6239 necessary, since the first computation could do the job. However, in
6240 a small buffer, the first method may not put the cursor on exactly the
6241 desired line; the second method does a better job.
6244 The code looks like this:
6246 @c Keep this on one line.
6248 (/ (+ 10 (* size (prefix-numeric-value arg))) 10))
6253 This is code in which you figure out what happens by discovering how the
6254 functions are embedded in parentheses. It is easier to read if you
6255 reformat it with each expression indented more deeply than its
6256 enclosing expression:
6264 (prefix-numeric-value arg)))
6271 Looking at parentheses, we see that the innermost operation is
6272 @code{(prefix-numeric-value arg)}, which converts the raw argument to
6273 a number. In the following expression, this number is multiplied by
6274 the size of the accessible portion of the buffer:
6277 (* size (prefix-numeric-value arg))
6281 This multiplication creates a number that may be larger than the size of
6282 the buffer---seven times larger if the argument is 7, for example. Ten
6283 is then added to this number and finally the large number is divided by
6284 ten to provide a value that is one character larger than the percentage
6285 position in the buffer.
6287 The number that results from all this is passed to @code{goto-char} and
6288 the cursor is moved to that point.
6291 @node beginning-of-buffer complete
6292 @subsection The Complete @code{beginning-of-buffer}
6295 Here is the complete text of the @code{beginning-of-buffer} function:
6301 (defun beginning-of-buffer (&optional arg)
6302 "Move point to the beginning of the buffer;
6303 leave mark at previous position.
6304 With \\[universal-argument] prefix,
6305 do not set mark at previous position.
6307 put point N/10 of the way from the beginning.
6309 If the buffer is narrowed,
6310 this command uses the beginning and size
6311 of the accessible part of the buffer.
6315 Don't use this command in Lisp programs!
6316 \(goto-char (point-min)) is faster
6317 and avoids clobbering the mark."
6320 (and transient-mark-mode mark-active)
6324 (let ((size (- (point-max) (point-min))))
6325 (goto-char (if (and arg (not (consp arg)))
6328 ;; Avoid overflow for large buffer sizes!
6329 (* (prefix-numeric-value arg)
6331 (/ (+ 10 (* size (prefix-numeric-value arg)))
6334 (if (and arg (not (consp arg))) (forward-line 1)))
6339 From before GNU Emacs 22
6342 (defun beginning-of-buffer (&optional arg)
6343 "Move point to the beginning of the buffer;
6344 leave mark at previous position.
6345 With arg N, put point N/10 of the way
6346 from the true beginning.
6349 Don't use this in Lisp programs!
6350 \(goto-char (point-min)) is faster
6351 and does not set the mark."
6358 (if (> (buffer-size) 10000)
6359 ;; @r{Avoid overflow for large buffer sizes!}
6360 (* (prefix-numeric-value arg)
6361 (/ (buffer-size) 10))
6364 (/ (+ 10 (* (buffer-size)
6365 (prefix-numeric-value arg)))
6368 (if arg (forward-line 1)))
6374 Except for two small points, the previous discussion shows how this
6375 function works. The first point deals with a detail in the
6376 documentation string, and the second point concerns the last line of
6380 In the documentation string, there is reference to an expression:
6383 \\[universal-argument]
6387 A @samp{\\} is used before the first square bracket of this
6388 expression. This @samp{\\} tells the Lisp interpreter to substitute
6389 whatever key is currently bound to the @samp{[@dots{}]}. In the case
6390 of @code{universal-argument}, that is usually @kbd{C-u}, but it might
6391 be different. (@xref{Documentation Tips, , Tips for Documentation
6392 Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more
6396 Finally, the last line of the @code{beginning-of-buffer} command says
6397 to move point to the beginning of the next line if the command is
6398 invoked with an argument:
6401 (if (and arg (not (consp arg))) (forward-line 1))
6405 This puts the cursor at the beginning of the first line after the
6406 appropriate tenths position in the buffer. This is a flourish that
6407 means that the cursor is always located @emph{at least} the requested
6408 tenths of the way through the buffer, which is a nicety that is,
6409 perhaps, not necessary, but which, if it did not occur, would be sure
6410 to draw complaints. (The @code{(not (consp arg))} portion is so that
6411 if you specify the command with a @kbd{C-u}, but without a number,
6412 that is to say, if the raw prefix argument is simply a cons cell,
6413 the command does not put you at the beginning of the second line.)
6415 @node Second Buffer Related Review
6418 Here is a brief summary of some of the topics covered in this chapter.
6422 Evaluate each argument in sequence, and return the value of the first
6423 argument that is not @code{nil}; if none return a value that is not
6424 @code{nil}, return @code{nil}. In brief, return the first true value
6425 of the arguments; return a true value if one @emph{or} any of the
6429 Evaluate each argument in sequence, and if any are @code{nil}, return
6430 @code{nil}; if none are @code{nil}, return the value of the last
6431 argument. In brief, return a true value only if all the arguments are
6432 true; return a true value if one @emph{and} each of the others is
6436 A keyword used to indicate that an argument to a function definition
6437 is optional; this means that the function can be evaluated without the
6438 argument, if desired.
6440 @item prefix-numeric-value
6441 Convert the raw prefix argument produced by @code{(interactive
6442 "P")} to a numeric value.
6445 Move point forward to the beginning of the next line, or if the argument
6446 is greater than one, forward that many lines. If it can't move as far
6447 forward as it is supposed to, @code{forward-line} goes forward as far as
6448 it can and then returns a count of the number of additional lines it was
6449 supposed to move but couldn't.
6452 Delete the entire contents of the current buffer.
6455 Return @code{t} if its argument is a buffer; otherwise return @code{nil}.
6458 @node optional Exercise
6459 @section @code{optional} Argument Exercise
6461 Write an interactive function with an optional argument that tests
6462 whether its argument, a number, is greater than or equal to, or else,
6463 less than the value of @code{fill-column}, and tells you which, in a
6464 message. However, if you do not pass an argument to the function, use
6465 56 as a default value.
6467 @node Narrowing & Widening
6468 @chapter Narrowing and Widening
6469 @cindex Focusing attention (narrowing)
6473 Narrowing is a feature of Emacs that makes it possible for you to focus
6474 on a specific part of a buffer, and work without accidentally changing
6475 other parts. Narrowing is normally disabled since it can confuse
6479 * Narrowing advantages:: The advantages of narrowing
6480 * save-restriction:: The @code{save-restriction} special form.
6481 * what-line:: The number of the line that point is on.
6486 @node Narrowing advantages
6487 @unnumberedsec The Advantages of Narrowing
6490 With narrowing, the rest of a buffer is made invisible, as if it weren't
6491 there. This is an advantage if, for example, you want to replace a word
6492 in one part of a buffer but not in another: you narrow to the part you want
6493 and the replacement is carried out only in that section, not in the rest
6494 of the buffer. Searches will only work within a narrowed region, not
6495 outside of one, so if you are fixing a part of a document, you can keep
6496 yourself from accidentally finding parts you do not need to fix by
6497 narrowing just to the region you want.
6498 (The key binding for @code{narrow-to-region} is @kbd{C-x n n}.)
6500 However, narrowing does make the rest of the buffer invisible, which
6501 can scare people who inadvertently invoke narrowing and think they
6502 have deleted a part of their file. Moreover, the @code{undo} command
6503 (which is usually bound to @kbd{C-x u}) does not turn off narrowing
6504 (nor should it), so people can become quite desperate if they do not
6505 know that they can return the rest of a buffer to visibility with the
6506 @code{widen} command.
6507 (The key binding for @code{widen} is @kbd{C-x n w}.)
6509 Narrowing is just as useful to the Lisp interpreter as to a human.
6510 Often, an Emacs Lisp function is designed to work on just part of a
6511 buffer; or conversely, an Emacs Lisp function needs to work on all of a
6512 buffer that has been narrowed. The @code{what-line} function, for
6513 example, removes the narrowing from a buffer, if it has any narrowing
6514 and when it has finished its job, restores the narrowing to what it was.
6515 On the other hand, the @code{count-lines} function
6516 uses narrowing to restrict itself to just that portion
6517 of the buffer in which it is interested and then restores the previous
6520 @node save-restriction
6521 @section The @code{save-restriction} Special Form
6522 @findex save-restriction
6524 In Emacs Lisp, you can use the @code{save-restriction} special form to
6525 keep track of whatever narrowing is in effect, if any. When the Lisp
6526 interpreter meets with @code{save-restriction}, it executes the code
6527 in the body of the @code{save-restriction} expression, and then undoes
6528 any changes to narrowing that the code caused. If, for example, the
6529 buffer is narrowed and the code that follows @code{save-restriction}
6530 gets rid of the narrowing, @code{save-restriction} returns the buffer
6531 to its narrowed region afterwards. In the @code{what-line} command,
6532 any narrowing the buffer may have is undone by the @code{widen}
6533 command that immediately follows the @code{save-restriction} command.
6534 Any original narrowing is restored just before the completion of the
6538 The template for a @code{save-restriction} expression is simple:
6548 The body of the @code{save-restriction} is one or more expressions that
6549 will be evaluated in sequence by the Lisp interpreter.
6551 Finally, a point to note: when you use both @code{save-excursion} and
6552 @code{save-restriction}, one right after the other, you should use
6553 @code{save-excursion} outermost. If you write them in reverse order,
6554 you may fail to record narrowing in the buffer to which Emacs switches
6555 after calling @code{save-excursion}. Thus, when written together,
6556 @code{save-excursion} and @code{save-restriction} should be written
6567 In other circumstances, when not written together, the
6568 @code{save-excursion} and @code{save-restriction} special forms must
6569 be written in the order appropriate to the function.
6585 /usr/local/src/emacs/lisp/simple.el
6588 "Print the current buffer line number and narrowed line number of point."
6590 (let ((start (point-min))
6591 (n (line-number-at-pos)))
6593 (message "Line %d" n)
6597 (message "line %d (narrowed line %d)"
6598 (+ n (line-number-at-pos start) -1) n))))))
6600 (defun line-number-at-pos (&optional pos)
6601 "Return (narrowed) buffer line number at position POS.
6602 If POS is nil, use current buffer location.
6603 Counting starts at (point-min), so the value refers
6604 to the contents of the accessible portion of the buffer."
6605 (let ((opoint (or pos (point))) start)
6607 (goto-char (point-min))
6608 (setq start (point))
6611 (1+ (count-lines start (point))))))
6613 (defun count-lines (start end)
6614 "Return number of lines between START and END.
6615 This is usually the number of newlines between them,
6616 but can be one more if START is not equal to END
6617 and the greater of them is not at the start of a line."
6620 (narrow-to-region start end)
6621 (goto-char (point-min))
6622 (if (eq selective-display t)
6625 (while (re-search-forward "[\n\C-m]" nil t 40)
6626 (setq done (+ 40 done)))
6627 (while (re-search-forward "[\n\C-m]" nil t 1)
6628 (setq done (+ 1 done)))
6629 (goto-char (point-max))
6630 (if (and (/= start end)
6634 (- (buffer-size) (forward-line (buffer-size)))))))
6638 @section @code{what-line}
6640 @cindex Widening, example of
6642 The @code{what-line} command tells you the number of the line in which
6643 the cursor is located. The function illustrates the use of the
6644 @code{save-restriction} and @code{save-excursion} commands. Here is the
6645 original text of the function:
6650 "Print the current line number (in the buffer) of point."
6657 (1+ (count-lines 1 (point)))))))
6661 (In recent versions of GNU Emacs, the @code{what-line} function has
6662 been expanded to tell you your line number in a narrowed buffer as
6663 well as your line number in a widened buffer. The recent version is
6664 more complex than the version shown here. If you feel adventurous,
6665 you might want to look at it after figuring out how this version
6666 works. You will probably need to use @kbd{C-h f}
6667 (@code{describe-function}). The newer version uses a conditional to
6668 determine whether the buffer has been narrowed.
6670 (Also, it uses @code{line-number-at-pos}, which among other simple
6671 expressions, such as @code{(goto-char (point-min))}, moves point to
6672 the beginning of the current line with @code{(forward-line 0)} rather
6673 than @code{beginning-of-line}.)
6675 The @code{what-line} function as shown here has a documentation line
6676 and is interactive, as you would expect. The next two lines use the
6677 functions @code{save-restriction} and @code{widen}.
6679 The @code{save-restriction} special form notes whatever narrowing is in
6680 effect, if any, in the current buffer and restores that narrowing after
6681 the code in the body of the @code{save-restriction} has been evaluated.
6683 The @code{save-restriction} special form is followed by @code{widen}.
6684 This function undoes any narrowing the current buffer may have had
6685 when @code{what-line} was called. (The narrowing that was there is
6686 the narrowing that @code{save-restriction} remembers.) This widening
6687 makes it possible for the line counting commands to count from the
6688 beginning of the buffer. Otherwise, they would have been limited to
6689 counting within the accessible region. Any original narrowing is
6690 restored just before the completion of the function by the
6691 @code{save-restriction} special form.
6693 The call to @code{widen} is followed by @code{save-excursion}, which
6694 saves the location of the cursor (i.e., of point), and
6695 restores it after the code in the body of the @code{save-excursion}
6696 uses the @code{beginning-of-line} function to move point.
6698 (Note that the @code{(widen)} expression comes between the
6699 @code{save-restriction} and @code{save-excursion} special forms. When
6700 you write the two @code{save- @dots{}} expressions in sequence, write
6701 @code{save-excursion} outermost.)
6704 The last two lines of the @code{what-line} function are functions to
6705 count the number of lines in the buffer and then print the number in the
6711 (1+ (count-lines 1 (point)))))))
6715 The @code{message} function prints a one-line message at the bottom of
6716 the Emacs screen. The first argument is inside of quotation marks and
6717 is printed as a string of characters. However, it may contain a
6718 @samp{%d} expression to print a following argument. @samp{%d} prints
6719 the argument as a decimal, so the message will say something such as
6723 The number that is printed in place of the @samp{%d} is computed by the
6724 last line of the function:
6727 (1+ (count-lines 1 (point)))
6733 (defun count-lines (start end)
6734 "Return number of lines between START and END.
6735 This is usually the number of newlines between them,
6736 but can be one more if START is not equal to END
6737 and the greater of them is not at the start of a line."
6740 (narrow-to-region start end)
6741 (goto-char (point-min))
6742 (if (eq selective-display t)
6745 (while (re-search-forward "[\n\C-m]" nil t 40)
6746 (setq done (+ 40 done)))
6747 (while (re-search-forward "[\n\C-m]" nil t 1)
6748 (setq done (+ 1 done)))
6749 (goto-char (point-max))
6750 (if (and (/= start end)
6754 (- (buffer-size) (forward-line (buffer-size)))))))
6758 What this does is count the lines from the first position of the
6759 buffer, indicated by the @code{1}, up to @code{(point)}, and then add
6760 one to that number. (The @code{1+} function adds one to its
6761 argument.) We add one to it because line 2 has only one line before
6762 it, and @code{count-lines} counts only the lines @emph{before} the
6765 After @code{count-lines} has done its job, and the message has been
6766 printed in the echo area, the @code{save-excursion} restores point to
6767 its original position; and @code{save-restriction} restores
6768 the original narrowing, if any.
6770 @node narrow Exercise
6771 @section Exercise with Narrowing
6773 Write a function that will display the first 60 characters of the
6774 current buffer, even if you have narrowed the buffer to its latter
6775 half so that the first line is inaccessible. Restore point, mark, and
6776 narrowing. For this exercise, you need to use a whole potpourri of
6777 functions, including @code{save-restriction}, @code{widen},
6778 @code{goto-char}, @code{point-min}, @code{message}, and
6779 @code{buffer-substring}.
6781 @cindex Properties, mention of @code{buffer-substring-no-properties}
6782 (@code{buffer-substring} is a previously unmentioned function you will
6783 have to investigate yourself; or perhaps you will have to use
6784 @code{buffer-substring-no-properties} or
6785 @code{filter-buffer-substring} @dots{}, yet other functions. Text
6786 properties are a feature otherwise not discussed here. @xref{Text
6787 Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference
6790 Additionally, do you really need @code{goto-char} or @code{point-min}?
6791 Or can you write the function without them?
6793 @node car cdr & cons
6794 @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
6795 @findex car, @r{introduced}
6796 @findex cdr, @r{introduced}
6798 In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental
6799 functions. The @code{cons} function is used to construct lists, and
6800 the @code{car} and @code{cdr} functions are used to take them apart.
6802 In the walk through of the @code{copy-region-as-kill} function, we
6803 will see @code{cons} as well as two variants on @code{cdr},
6804 namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.)
6807 * Strange Names:: An historical aside: why the strange names?
6808 * car & cdr:: Functions for extracting part of a list.
6809 * cons:: Constructing a list.
6810 * nthcdr:: Calling @code{cdr} repeatedly.
6812 * setcar:: Changing the first element of a list.
6813 * setcdr:: Changing the rest of a list.
6819 @unnumberedsec Strange Names
6822 The name of the @code{cons} function is not unreasonable: it is an
6823 abbreviation of the word ``construct''. The origins of the names for
6824 @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car}
6825 is an acronym from the phrase ``Contents of the Address part of the
6826 Register''; and @code{cdr} (pronounced ``could-er'') is an acronym from
6827 the phrase ``Contents of the Decrement part of the Register''. These
6828 phrases refer to specific pieces of hardware on the very early
6829 computer on which the original Lisp was developed. Besides being
6830 obsolete, the phrases have been completely irrelevant for more than 25
6831 years to anyone thinking about Lisp. Nonetheless, although a few
6832 brave scholars have begun to use more reasonable names for these
6833 functions, the old terms are still in use. In particular, since the
6834 terms are used in the Emacs Lisp source code, we will use them in this
6838 @section @code{car} and @code{cdr}
6840 The @sc{car} of a list is, quite simply, the first item in the list.
6841 Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is
6845 If you are reading this in Info in GNU Emacs, you can see this by
6846 evaluating the following:
6849 (car '(rose violet daisy buttercup))
6853 After evaluating the expression, @code{rose} will appear in the echo
6856 Clearly, a more reasonable name for the @code{car} function would be
6857 @code{first} and this is often suggested.
6859 @code{car} does not remove the first item from the list; it only reports
6860 what it is. After @code{car} has been applied to a list, the list is
6861 still the same as it was. In the jargon, @code{car} is
6862 ``non-destructive''. This feature turns out to be important.
6864 The @sc{cdr} of a list is the rest of the list, that is, the
6865 @code{cdr} function returns the part of the list that follows the
6866 first item. Thus, while the @sc{car} of the list @code{'(rose violet
6867 daisy buttercup)} is @code{rose}, the rest of the list, the value
6868 returned by the @code{cdr} function, is @code{(violet daisy
6872 You can see this by evaluating the following in the usual way:
6875 (cdr '(rose violet daisy buttercup))
6879 When you evaluate this, @code{(violet daisy buttercup)} will appear in
6882 Like @code{car}, @code{cdr} does not remove any elements from the
6883 list---it just returns a report of what the second and subsequent
6886 Incidentally, in the example, the list of flowers is quoted. If it were
6887 not, the Lisp interpreter would try to evaluate the list by calling
6888 @code{rose} as a function. In this example, we do not want to do that.
6890 Clearly, a more reasonable name for @code{cdr} would be @code{rest}.
6892 (There is a lesson here: when you name new functions, consider very
6893 carefully what you are doing, since you may be stuck with the names
6894 for far longer than you expect. The reason this document perpetuates
6895 these names is that the Emacs Lisp source code uses them, and if I did
6896 not use them, you would have a hard time reading the code; but do,
6897 please, try to avoid using these terms yourself. The people who come
6898 after you will be grateful to you.)
6900 When @code{car} and @code{cdr} are applied to a list made up of symbols,
6901 such as the list @code{(pine fir oak maple)}, the element of the list
6902 returned by the function @code{car} is the symbol @code{pine} without
6903 any parentheses around it. @code{pine} is the first element in the
6904 list. However, the @sc{cdr} of the list is a list itself, @code{(fir
6905 oak maple)}, as you can see by evaluating the following expressions in
6910 (car '(pine fir oak maple))
6912 (cdr '(pine fir oak maple))
6916 On the other hand, in a list of lists, the first element is itself a
6917 list. @code{car} returns this first element as a list. For example,
6918 the following list contains three sub-lists, a list of carnivores, a
6919 list of herbivores and a list of sea mammals:
6923 (car '((lion tiger cheetah)
6924 (gazelle antelope zebra)
6925 (whale dolphin seal)))
6930 In this example, the first element or @sc{car} of the list is the list of
6931 carnivores, @code{(lion tiger cheetah)}, and the rest of the list is
6932 @code{((gazelle antelope zebra) (whale dolphin seal))}.
6936 (cdr '((lion tiger cheetah)
6937 (gazelle antelope zebra)
6938 (whale dolphin seal)))
6942 It is worth saying again that @code{car} and @code{cdr} are
6943 non-destructive---that is, they do not modify or change lists to which
6944 they are applied. This is very important for how they are used.
6946 Also, in the first chapter, in the discussion about atoms, I said that
6947 in Lisp, certain kinds of atom, such as an array, can be separated
6948 into parts; but the mechanism for doing this is different from the
6949 mechanism for splitting a list. As far as Lisp is concerned, the
6950 atoms of a list are unsplittable. (@xref{Lisp Atoms}.) The
6951 @code{car} and @code{cdr} functions are used for splitting lists and
6952 are considered fundamental to Lisp. Since they cannot split or gain
6953 access to the parts of an array, an array is considered an atom.
6954 Conversely, the other fundamental function, @code{cons}, can put
6955 together or construct a list, but not an array. (Arrays are handled
6956 by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU
6957 Emacs Lisp Reference Manual}.)
6960 @section @code{cons}
6961 @findex cons, @r{introduced}
6963 The @code{cons} function constructs lists; it is the inverse of
6964 @code{car} and @code{cdr}. For example, @code{cons} can be used to make
6965 a four element list from the three element list, @code{(fir oak maple)}:
6968 (cons 'pine '(fir oak maple))
6973 After evaluating this list, you will see
6976 (pine fir oak maple)
6980 appear in the echo area. @code{cons} causes the creation of a new
6981 list in which the element is followed by the elements of the original
6984 We often say that @code{cons} puts a new element at the beginning of
6985 a list, or that it attaches or pushes elements onto the list, but this
6986 phrasing can be misleading, since @code{cons} does not change an
6987 existing list, but creates a new one.
6989 Like @code{car} and @code{cdr}, @code{cons} is non-destructive.
6993 * length:: How to find the length of a list.
6998 @unnumberedsubsec Build a list
7001 @code{cons} must have a list to attach to.@footnote{Actually, you can
7002 @code{cons} an element to an atom to produce a dotted pair. Dotted
7003 pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted
7004 Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You
7005 cannot start from absolutely nothing. If you are building a list, you
7006 need to provide at least an empty list at the beginning. Here is a
7007 series of @code{cons} expressions that build up a list of flowers. If
7008 you are reading this in Info in GNU Emacs, you can evaluate each of
7009 the expressions in the usual way; the value is printed in this text
7010 after @samp{@result{}}, which you may read as ``evaluates to''.
7014 (cons 'buttercup ())
7015 @result{} (buttercup)
7019 (cons 'daisy '(buttercup))
7020 @result{} (daisy buttercup)
7024 (cons 'violet '(daisy buttercup))
7025 @result{} (violet daisy buttercup)
7029 (cons 'rose '(violet daisy buttercup))
7030 @result{} (rose violet daisy buttercup)
7035 In the first example, the empty list is shown as @code{()} and a list
7036 made up of @code{buttercup} followed by the empty list is constructed.
7037 As you can see, the empty list is not shown in the list that was
7038 constructed. All that you see is @code{(buttercup)}. The empty list is
7039 not counted as an element of a list because there is nothing in an empty
7040 list. Generally speaking, an empty list is invisible.
7042 The second example, @code{(cons 'daisy '(buttercup))} constructs a new,
7043 two element list by putting @code{daisy} in front of @code{buttercup};
7044 and the third example constructs a three element list by putting
7045 @code{violet} in front of @code{daisy} and @code{buttercup}.
7048 @subsection Find the Length of a List: @code{length}
7051 You can find out how many elements there are in a list by using the Lisp
7052 function @code{length}, as in the following examples:
7056 (length '(buttercup))
7061 (length '(daisy buttercup))
7066 (length (cons 'violet '(daisy buttercup)))
7072 In the third example, the @code{cons} function is used to construct a
7073 three element list which is then passed to the @code{length} function as
7077 We can also use @code{length} to count the number of elements in an
7088 As you would expect, the number of elements in an empty list is zero.
7090 An interesting experiment is to find out what happens if you try to find
7091 the length of no list at all; that is, if you try to call @code{length}
7092 without giving it an argument, not even an empty list:
7100 What you see, if you evaluate this, is the error message
7103 Lisp error: (wrong-number-of-arguments length 0)
7107 This means that the function receives the wrong number of
7108 arguments, zero, when it expects some other number of arguments. In
7109 this case, one argument is expected, the argument being a list whose
7110 length the function is measuring. (Note that @emph{one} list is
7111 @emph{one} argument, even if the list has many elements inside it.)
7113 The part of the error message that says @samp{length} is the name of
7117 @code{length} is still a subroutine, but you need C-h f to discover that.
7119 In an earlier version:
7120 This is written with a special notation, @samp{#<subr},
7121 that indicates that the function @code{length} is one of the primitive
7122 functions written in C rather than in Emacs Lisp. (@samp{subr} is an
7123 abbreviation for ``subroutine''.) @xref{What Is a Function, , What Is a
7124 Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more
7129 @section @code{nthcdr}
7132 The @code{nthcdr} function is associated with the @code{cdr} function.
7133 What it does is take the @sc{cdr} of a list repeatedly.
7135 If you take the @sc{cdr} of the list @code{(pine fir
7136 oak maple)}, you will be returned the list @code{(fir oak maple)}. If you
7137 repeat this on what was returned, you will be returned the list
7138 @code{(oak maple)}. (Of course, repeated @sc{cdr}ing on the original
7139 list will just give you the original @sc{cdr} since the function does
7140 not change the list. You need to evaluate the @sc{cdr} of the
7141 @sc{cdr} and so on.) If you continue this, eventually you will be
7142 returned an empty list, which in this case, instead of being shown as
7143 @code{()} is shown as @code{nil}.
7146 For review, here is a series of repeated @sc{cdr}s, the text following
7147 the @samp{@result{}} shows what is returned.
7151 (cdr '(pine fir oak maple))
7152 @result{}(fir oak maple)
7156 (cdr '(fir oak maple))
7157 @result{} (oak maple)
7182 You can also do several @sc{cdr}s without printing the values in
7187 (cdr (cdr '(pine fir oak maple)))
7188 @result{} (oak maple)
7193 In this example, the Lisp interpreter evaluates the innermost list first.
7194 The innermost list is quoted, so it just passes the list as it is to the
7195 innermost @code{cdr}. This @code{cdr} passes a list made up of the
7196 second and subsequent elements of the list to the outermost @code{cdr},
7197 which produces a list composed of the third and subsequent elements of
7198 the original list. In this example, the @code{cdr} function is repeated
7199 and returns a list that consists of the original list without its
7202 The @code{nthcdr} function does the same as repeating the call to
7203 @code{cdr}. In the following example, the argument 2 is passed to the
7204 function @code{nthcdr}, along with the list, and the value returned is
7205 the list without its first two items, which is exactly the same
7206 as repeating @code{cdr} twice on the list:
7210 (nthcdr 2 '(pine fir oak maple))
7211 @result{} (oak maple)
7216 Using the original four element list, we can see what happens when
7217 various numeric arguments are passed to @code{nthcdr}, including 0, 1,
7222 ;; @r{Leave the list as it was.}
7223 (nthcdr 0 '(pine fir oak maple))
7224 @result{} (pine fir oak maple)
7228 ;; @r{Return a copy without the first element.}
7229 (nthcdr 1 '(pine fir oak maple))
7230 @result{} (fir oak maple)
7234 ;; @r{Return a copy of the list without three elements.}
7235 (nthcdr 3 '(pine fir oak maple))
7240 ;; @r{Return a copy lacking all four elements.}
7241 (nthcdr 4 '(pine fir oak maple))
7246 ;; @r{Return a copy lacking all elements.}
7247 (nthcdr 5 '(pine fir oak maple))
7256 The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly.
7257 The @code{nth} function takes the @sc{car} of the result returned by
7258 @code{nthcdr}. It returns the Nth element of the list.
7261 Thus, if it were not defined in C for speed, the definition of
7262 @code{nth} would be:
7267 "Returns the Nth element of LIST.
7268 N counts from zero. If LIST is not that long, nil is returned."
7269 (car (nthcdr n list)))
7274 (Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el},
7275 but its definition was redone in C in the 1980s.)
7277 The @code{nth} function returns a single element of a list.
7278 This can be very convenient.
7280 Note that the elements are numbered from zero, not one. That is to
7281 say, the first element of a list, its @sc{car} is the zeroth element.
7282 This zero-based counting often bothers people who
7283 are accustomed to the first element in a list being number one, which
7291 (nth 0 '("one" "two" "three"))
7294 (nth 1 '("one" "two" "three"))
7299 It is worth mentioning that @code{nth}, like @code{nthcdr} and
7300 @code{cdr}, does not change the original list---the function is
7301 non-destructive. This is in sharp contrast to the @code{setcar} and
7302 @code{setcdr} functions.
7305 @section @code{setcar}
7308 As you might guess from their names, the @code{setcar} and @code{setcdr}
7309 functions set the @sc{car} or the @sc{cdr} of a list to a new value.
7310 They actually change the original list, unlike @code{car} and @code{cdr}
7311 which leave the original list as it was. One way to find out how this
7312 works is to experiment. We will start with the @code{setcar} function.
7315 First, we can make a list and then set the value of a variable to the
7316 list, using the @code{setq} function. Here is a list of animals:
7319 (setq animals '(antelope giraffe lion tiger))
7323 If you are reading this in Info inside of GNU Emacs, you can evaluate
7324 this expression in the usual fashion, by positioning the cursor after
7325 the expression and typing @kbd{C-x C-e}. (I'm doing this right here
7326 as I write this. This is one of the advantages of having the
7327 interpreter built into the computing environment. Incidentally, when
7328 there is nothing on the line after the final parentheses, such as a
7329 comment, point can be on the next line. Thus, if your cursor is in
7330 the first column of the next line, you do not need to move it.
7331 Indeed, Emacs permits any amount of white space after the final
7335 When we evaluate the variable @code{animals}, we see that it is bound to
7336 the list @code{(antelope giraffe lion tiger)}:
7341 @result{} (antelope giraffe lion tiger)
7346 Put another way, the variable @code{animals} points to the list
7347 @code{(antelope giraffe lion tiger)}.
7349 Next, evaluate the function @code{setcar} while passing it two
7350 arguments, the variable @code{animals} and the quoted symbol
7351 @code{hippopotamus}; this is done by writing the three element list
7352 @code{(setcar animals 'hippopotamus)} and then evaluating it in the
7356 (setcar animals 'hippopotamus)
7361 After evaluating this expression, evaluate the variable @code{animals}
7362 again. You will see that the list of animals has changed:
7367 @result{} (hippopotamus giraffe lion tiger)
7372 The first element on the list, @code{antelope} is replaced by
7373 @code{hippopotamus}.
7375 So we can see that @code{setcar} did not add a new element to the list
7376 as @code{cons} would have; it replaced @code{antelope} with
7377 @code{hippopotamus}; it @emph{changed} the list.
7380 @section @code{setcdr}
7383 The @code{setcdr} function is similar to the @code{setcar} function,
7384 except that the function replaces the second and subsequent elements of
7385 a list rather than the first element.
7387 (To see how to change the last element of a list, look ahead to
7388 @ref{kill-new function, , The @code{kill-new} function}, which uses
7389 the @code{nthcdr} and @code{setcdr} functions.)
7392 To see how this works, set the value of the variable to a list of
7393 domesticated animals by evaluating the following expression:
7396 (setq domesticated-animals '(horse cow sheep goat))
7401 If you now evaluate the list, you will be returned the list
7402 @code{(horse cow sheep goat)}:
7406 domesticated-animals
7407 @result{} (horse cow sheep goat)
7412 Next, evaluate @code{setcdr} with two arguments, the name of the
7413 variable which has a list as its value, and the list to which the
7414 @sc{cdr} of the first list will be set;
7417 (setcdr domesticated-animals '(cat dog))
7421 If you evaluate this expression, the list @code{(cat dog)} will appear
7422 in the echo area. This is the value returned by the function. The
7423 result we are interested in is the side effect, which we can see by
7424 evaluating the variable @code{domesticated-animals}:
7428 domesticated-animals
7429 @result{} (horse cat dog)
7434 Indeed, the list is changed from @code{(horse cow sheep goat)} to
7435 @code{(horse cat dog)}. The @sc{cdr} of the list is changed from
7436 @code{(cow sheep goat)} to @code{(cat dog)}.
7441 Construct a list of four birds by evaluating several expressions with
7442 @code{cons}. Find out what happens when you @code{cons} a list onto
7443 itself. Replace the first element of the list of four birds with a
7444 fish. Replace the rest of that list with a list of other fish.
7446 @node Cutting & Storing Text
7447 @chapter Cutting and Storing Text
7448 @cindex Cutting and storing text
7449 @cindex Storing and cutting text
7450 @cindex Killing text
7451 @cindex Clipping text
7452 @cindex Erasing text
7453 @cindex Deleting text
7455 Whenever you cut or clip text out of a buffer with a @dfn{kill} command in
7456 GNU Emacs, it is stored in a list and you can bring it back with a
7459 (The use of the word ``kill'' in Emacs for processes which specifically
7460 @emph{do not} destroy the values of the entities is an unfortunate
7461 historical accident. A much more appropriate word would be ``clip'' since
7462 that is what the kill commands do; they clip text out of a buffer and
7463 put it into storage from which it can be brought back. I have often
7464 been tempted to replace globally all occurrences of ``kill'' in the Emacs
7465 sources with ``clip'' and all occurrences of ``killed'' with ``clipped''.)
7468 * Storing Text:: Text is stored in a list.
7469 * zap-to-char:: Cutting out text up to a character.
7470 * kill-region:: Cutting text out of a region.
7471 * copy-region-as-kill:: A definition for copying text.
7472 * Digression into C:: Minor note on C programming language macros.
7473 * defvar:: How to give a variable an initial value.
7474 * cons & search-fwd Review::
7475 * search Exercises::
7480 @unnumberedsec Storing Text in a List
7483 When text is cut out of a buffer, it is stored on a list. Successive
7484 pieces of text are stored on the list successively, so the list might
7488 ("a piece of text" "previous piece")
7493 The function @code{cons} can be used to create a new list from a piece
7494 of text (an ``atom'', to use the jargon) and an existing list, like
7499 (cons "another piece"
7500 '("a piece of text" "previous piece"))
7506 If you evaluate this expression, a list of three elements will appear in
7510 ("another piece" "a piece of text" "previous piece")
7513 With the @code{car} and @code{nthcdr} functions, you can retrieve
7514 whichever piece of text you want. For example, in the following code,
7515 @code{nthcdr 1 @dots{}} returns the list with the first item removed;
7516 and the @code{car} returns the first element of that remainder---the
7517 second element of the original list:
7521 (car (nthcdr 1 '("another piece"
7524 @result{} "a piece of text"
7528 The actual functions in Emacs are more complex than this, of course.
7529 The code for cutting and retrieving text has to be written so that
7530 Emacs can figure out which element in the list you want---the first,
7531 second, third, or whatever. In addition, when you get to the end of
7532 the list, Emacs should give you the first element of the list, rather
7533 than nothing at all.
7535 The list that holds the pieces of text is called the @dfn{kill ring}.
7536 This chapter leads up to a description of the kill ring and how it is
7537 used by first tracing how the @code{zap-to-char} function works. This
7538 function calls a function that invokes a function that
7539 manipulates the kill ring. Thus, before reaching the mountains, we
7540 climb the foothills.
7542 A subsequent chapter describes how text that is cut from the buffer is
7543 retrieved. @xref{Yanking, , Yanking Text Back}.
7546 @section @code{zap-to-char}
7549 Let us look at the interactive @code{zap-to-char} function.
7552 * Complete zap-to-char:: The complete implementation.
7553 * zap-to-char interactive:: A three part interactive expression.
7554 * zap-to-char body:: A short overview.
7555 * search-forward:: How to search for a string.
7556 * progn:: The @code{progn} special form.
7557 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
7561 @node Complete zap-to-char
7562 @unnumberedsubsec The Complete @code{zap-to-char} Implementation
7565 The @code{zap-to-char} function removes the text in the region between
7566 the location of the cursor (i.e., of point) up to and including the
7567 next occurrence of a specified character. The text that
7568 @code{zap-to-char} removes is put in the kill ring; and it can be
7569 retrieved from the kill ring by typing @kbd{C-y} (@code{yank}). If
7570 the command is given an argument, it removes text through that number
7571 of occurrences. Thus, if the cursor were at the beginning of this
7572 sentence and the character were @samp{s}, @samp{Thus} would be
7573 removed. If the argument were two, @samp{Thus, if the curs} would be
7574 removed, up to and including the @samp{s} in @samp{cursor}.
7576 If the specified character is not found, @code{zap-to-char} will say
7577 ``Search failed'', tell you the character you typed, and not remove
7580 In order to determine how much text to remove, @code{zap-to-char} uses
7581 a search function. Searches are used extensively in code that
7582 manipulates text, and we will focus attention on them as well as on the
7586 @c GNU Emacs version 19
7587 (defun zap-to-char (arg char) ; version 19 implementation
7588 "Kill up to and including ARG'th occurrence of CHAR.
7589 Goes backward if ARG is negative; error if CHAR not found."
7590 (interactive "*p\ncZap to char: ")
7591 (kill-region (point)
7594 (char-to-string char) nil nil arg)
7599 Here is the complete text of the version 22 implementation of the function:
7604 (defun zap-to-char (arg char)
7605 "Kill up to and including ARG'th occurrence of CHAR.
7606 Case is ignored if `case-fold-search' is non-nil in the current buffer.
7607 Goes backward if ARG is negative; error if CHAR not found."
7608 (interactive "p\ncZap to char: ")
7609 (if (char-table-p translation-table-for-input)
7610 (setq char (or (aref translation-table-for-input char) char)))
7611 (kill-region (point) (progn
7612 (search-forward (char-to-string char)
7618 The documentation is thorough. You do need to know the jargon meaning
7619 of the word ``kill''.
7621 @cindex curved quotes
7622 @cindex curly quotes
7623 The version 22 documentation string for @code{zap-to-char} uses ASCII
7624 grave accent and apostrophe to quote a symbol, so it appears as
7625 @t{`case-fold-search'}. This quoting style was inspired by 1970s-era
7626 displays in which grave accent and apostrophe were often mirror images
7627 suitable for use as quotes. On most modern displays this is no longer
7628 true, and when these two ASCII characters appear in documentation
7629 strings or diagnostic message formats, Emacs typically transliterates
7630 them to curved single quotes, so that the abovequoted symbol appears
7631 as @t{‘case-fold-search’}. Source-code strings can also simply use
7632 curved quotes directly.
7634 @node zap-to-char interactive
7635 @subsection The @code{interactive} Expression
7638 The interactive expression in the @code{zap-to-char} command looks like
7642 (interactive "p\ncZap to char: ")
7645 The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies
7646 two different things. First, and most simply, is the @samp{p}.
7647 This part is separated from the next part by a newline, @samp{\n}.
7648 The @samp{p} means that the first argument to the function will be
7649 passed the value of a @dfn{processed prefix}. The prefix argument is
7650 passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If
7651 the function is called interactively without a prefix, 1 is passed to
7654 The second part of @code{"p\ncZap to char:@: "} is
7655 @samp{cZap to char:@: }. In this part, the lower case @samp{c}
7656 indicates that @code{interactive} expects a prompt and that the
7657 argument will be a character. The prompt follows the @samp{c} and is
7658 the string @samp{Zap to char:@: } (with a space after the colon to
7661 What all this does is prepare the arguments to @code{zap-to-char} so they
7662 are of the right type, and give the user a prompt.
7664 In a read-only buffer, the @code{zap-to-char} function copies the text
7665 to the kill ring, but does not remove it. The echo area displays a
7666 message saying that the buffer is read-only. Also, the terminal may
7667 beep or blink at you.
7669 @node zap-to-char body
7670 @subsection The Body of @code{zap-to-char}
7672 The body of the @code{zap-to-char} function contains the code that
7673 kills (that is, removes) the text in the region from the current
7674 position of the cursor up to and including the specified character.
7676 The first part of the code looks like this:
7679 (if (char-table-p translation-table-for-input)
7680 (setq char (or (aref translation-table-for-input char) char)))
7681 (kill-region (point) (progn
7682 (search-forward (char-to-string char) nil nil arg)
7687 @code{char-table-p} is an hitherto unseen function. It determines
7688 whether its argument is a character table. When it is, it sets the
7689 character passed to @code{zap-to-char} to one of them, if that
7690 character exists, or to the character itself. (This becomes important
7691 for certain characters in non-European languages. The @code{aref}
7692 function extracts an element from an array. It is an array-specific
7693 function that is not described in this document. @xref{Arrays, ,
7694 Arrays, elisp, The GNU Emacs Lisp Reference Manual}.)
7697 @code{(point)} is the current position of the cursor.
7699 The next part of the code is an expression using @code{progn}. The body
7700 of the @code{progn} consists of calls to @code{search-forward} and
7703 It is easier to understand how @code{progn} works after learning about
7704 @code{search-forward}, so we will look at @code{search-forward} and
7705 then at @code{progn}.
7707 @node search-forward
7708 @subsection The @code{search-forward} Function
7709 @findex search-forward
7711 The @code{search-forward} function is used to locate the
7712 zapped-for-character in @code{zap-to-char}. If the search is
7713 successful, @code{search-forward} leaves point immediately after the
7714 last character in the target string. (In @code{zap-to-char}, the
7715 target string is just one character long. @code{zap-to-char} uses the
7716 function @code{char-to-string} to ensure that the computer treats that
7717 character as a string.) If the search is backwards,
7718 @code{search-forward} leaves point just before the first character in
7719 the target. Also, @code{search-forward} returns @code{t} for true.
7720 (Moving point is therefore a side effect.)
7723 In @code{zap-to-char}, the @code{search-forward} function looks like this:
7726 (search-forward (char-to-string char) nil nil arg)
7729 The @code{search-forward} function takes four arguments:
7733 The first argument is the target, what is searched for. This must be a
7734 string, such as @samp{"z"}.
7736 As it happens, the argument passed to @code{zap-to-char} is a single
7737 character. Because of the way computers are built, the Lisp
7738 interpreter may treat a single character as being different from a
7739 string of characters. Inside the computer, a single character has a
7740 different electronic format than a string of one character. (A single
7741 character can often be recorded in the computer using exactly one
7742 byte; but a string may be longer, and the computer needs to be ready
7743 for this.) Since the @code{search-forward} function searches for a
7744 string, the character that the @code{zap-to-char} function receives as
7745 its argument must be converted inside the computer from one format to
7746 the other; otherwise the @code{search-forward} function will fail.
7747 The @code{char-to-string} function is used to make this conversion.
7750 The second argument bounds the search; it is specified as a position in
7751 the buffer. In this case, the search can go to the end of the buffer,
7752 so no bound is set and the second argument is @code{nil}.
7755 The third argument tells the function what it should do if the search
7756 fails---it can signal an error (and print a message) or it can return
7757 @code{nil}. A @code{nil} as the third argument causes the function to
7758 signal an error when the search fails.
7761 The fourth argument to @code{search-forward} is the repeat count---how
7762 many occurrences of the string to look for. This argument is optional
7763 and if the function is called without a repeat count, this argument is
7764 passed the value 1. If this argument is negative, the search goes
7769 In template form, a @code{search-forward} expression looks like this:
7773 (search-forward "@var{target-string}"
7774 @var{limit-of-search}
7775 @var{what-to-do-if-search-fails}
7780 We will look at @code{progn} next.
7783 @subsection The @code{progn} Special Form
7786 @code{progn} is a special form that causes each of its arguments to be
7787 evaluated in sequence and then returns the value of the last one. The
7788 preceding expressions are evaluated only for the side effects they
7789 perform. The values produced by them are discarded.
7792 The template for a @code{progn} expression is very simple:
7801 In @code{zap-to-char}, the @code{progn} expression has to do two things:
7802 put point in exactly the right position; and return the location of
7803 point so that @code{kill-region} will know how far to kill to.
7805 The first argument to the @code{progn} is @code{search-forward}. When
7806 @code{search-forward} finds the string, the function leaves point
7807 immediately after the last character in the target string. (In this
7808 case the target string is just one character long.) If the search is
7809 backwards, @code{search-forward} leaves point just before the first
7810 character in the target. The movement of point is a side effect.
7812 The second and last argument to @code{progn} is the expression
7813 @code{(point)}. This expression returns the value of point, which in
7814 this case will be the location to which it has been moved by
7815 @code{search-forward}. (In the source, a line that tells the function
7816 to go to the previous character, if it is going forward, was commented
7817 out in 1999; I don't remember whether that feature or mis-feature was
7818 ever a part of the distributed source.) The value of @code{point} is
7819 returned by the @code{progn} expression and is passed to
7820 @code{kill-region} as @code{kill-region}'s second argument.
7822 @node Summing up zap-to-char
7823 @subsection Summing up @code{zap-to-char}
7825 Now that we have seen how @code{search-forward} and @code{progn} work,
7826 we can see how the @code{zap-to-char} function works as a whole.
7828 The first argument to @code{kill-region} is the position of the cursor
7829 when the @code{zap-to-char} command is given---the value of point at
7830 that time. Within the @code{progn}, the search function then moves
7831 point to just after the zapped-to-character and @code{point} returns the
7832 value of this location. The @code{kill-region} function puts together
7833 these two values of point, the first one as the beginning of the region
7834 and the second one as the end of the region, and removes the region.
7836 The @code{progn} special form is necessary because the
7837 @code{kill-region} command takes two arguments; and it would fail if
7838 @code{search-forward} and @code{point} expressions were written in
7839 sequence as two additional arguments. The @code{progn} expression is
7840 a single argument to @code{kill-region} and returns the one value that
7841 @code{kill-region} needs for its second argument.
7844 @section @code{kill-region}
7847 The @code{zap-to-char} function uses the @code{kill-region} function.
7848 This function clips text from a region and copies that text to
7849 the kill ring, from which it may be retrieved.
7854 (defun kill-region (beg end &optional yank-handler)
7855 "Kill (\"cut\") text between point and mark.
7856 This deletes the text from the buffer and saves it in the kill ring.
7857 The command \\[yank] can retrieve it from there.
7858 \(If you want to kill and then yank immediately, use \\[kill-ring-save].)
7860 If you want to append the killed region to the last killed text,
7861 use \\[append-next-kill] before \\[kill-region].
7863 If the buffer is read-only, Emacs will beep and refrain from deleting
7864 the text, but put the text in the kill ring anyway. This means that
7865 you can use the killing commands to copy text from a read-only buffer.
7867 This is the primitive for programs to kill text (as opposed to deleting it).
7868 Supply two arguments, character positions indicating the stretch of text
7870 Any command that calls this function is a \"kill command\".
7871 If the previous command was also a kill command,
7872 the text killed this time appends to the text killed last time
7873 to make one entry in the kill ring.
7875 In Lisp code, optional third arg YANK-HANDLER, if non-nil,
7876 specifies the yank-handler text property to be set on the killed
7877 text. See `insert-for-yank'."
7878 ;; Pass point first, then mark, because the order matters
7879 ;; when calling kill-append.
7880 (interactive (list (point) (mark)))
7881 (unless (and beg end)
7882 (error "The mark is not set now, so there is no region"))
7884 (let ((string (filter-buffer-substring beg end t)))
7885 (when string ;STRING is nil if BEG = END
7886 ;; Add that string to the kill ring, one way or another.
7887 (if (eq last-command 'kill-region)
7888 (kill-append string (< end beg) yank-handler)
7889 (kill-new string nil yank-handler)))
7890 (when (or string (eq last-command 'kill-region))
7891 (setq this-command 'kill-region))
7893 ((buffer-read-only text-read-only)
7894 ;; The code above failed because the buffer, or some of the characters
7895 ;; in the region, are read-only.
7896 ;; We should beep, in case the user just isn't aware of this.
7897 ;; However, there's no harm in putting
7898 ;; the region's text in the kill ring, anyway.
7899 (copy-region-as-kill beg end)
7900 ;; Set this-command now, so it will be set even if we get an error.
7901 (setq this-command 'kill-region)
7902 ;; This should barf, if appropriate, and give us the correct error.
7903 (if kill-read-only-ok
7904 (progn (message "Read only text copied to kill ring") nil)
7905 ;; Signal an error if the buffer is read-only.
7906 (barf-if-buffer-read-only)
7907 ;; If the buffer isn't read-only, the text is.
7908 (signal 'text-read-only (list (current-buffer)))))))
7911 The Emacs 22 version of that function uses @code{condition-case} and
7912 @code{copy-region-as-kill}, both of which we will explain.
7913 @code{condition-case} is an important special form.
7915 In essence, the @code{kill-region} function calls
7916 @code{condition-case}, which takes three arguments. In this function,
7917 the first argument does nothing. The second argument contains the
7918 code that does the work when all goes well. The third argument
7919 contains the code that is called in the event of an error.
7922 * Complete kill-region:: The function definition.
7923 * condition-case:: Dealing with a problem.
7928 @node Complete kill-region
7929 @unnumberedsubsec The Complete @code{kill-region} Definition
7933 We will go through the @code{condition-case} code in a moment. First,
7934 let us look at the definition of @code{kill-region}, with comments
7940 (defun kill-region (beg end)
7941 "Kill (\"cut\") text between point and mark.
7942 This deletes the text from the buffer and saves it in the kill ring.
7943 The command \\[yank] can retrieve it from there. @dots{} "
7947 ;; @bullet{} Since order matters, pass point first.
7948 (interactive (list (point) (mark)))
7949 ;; @bullet{} And tell us if we cannot cut the text.
7950 ;; 'unless' is an 'if' without a then-part.
7951 (unless (and beg end)
7952 (error "The mark is not set now, so there is no region"))
7956 ;; @bullet{} 'condition-case' takes three arguments.
7957 ;; If the first argument is nil, as it is here,
7958 ;; information about the error signal is not
7959 ;; stored for use by another function.
7964 ;; @bullet{} The second argument to 'condition-case' tells the
7965 ;; Lisp interpreter what to do when all goes well.
7969 ;; It starts with a 'let' function that extracts the string
7970 ;; and tests whether it exists. If so (that is what the
7971 ;; 'when' checks), it calls an 'if' function that determines
7972 ;; whether the previous command was another call to
7973 ;; 'kill-region'; if it was, then the new text is appended to
7974 ;; the previous text; if not, then a different function,
7975 ;; 'kill-new', is called.
7979 ;; The 'kill-append' function concatenates the new string and
7980 ;; the old. The 'kill-new' function inserts text into a new
7981 ;; item in the kill ring.
7985 ;; 'when' is an 'if' without an else-part. The second 'when'
7986 ;; again checks whether the current string exists; in
7987 ;; addition, it checks whether the previous command was
7988 ;; another call to 'kill-region'. If one or the other
7989 ;; condition is true, then it sets the current command to
7990 ;; be 'kill-region'.
7993 (let ((string (filter-buffer-substring beg end t)))
7994 (when string ;STRING is nil if BEG = END
7995 ;; Add that string to the kill ring, one way or another.
7996 (if (eq last-command 'kill-region)
7999 ;; @minus{} 'yank-handler' is an optional argument to
8000 ;; 'kill-region' that tells the 'kill-append' and
8001 ;; 'kill-new' functions how deal with properties
8002 ;; added to the text, such as 'bold' or 'italics'.
8003 (kill-append string (< end beg) yank-handler)
8004 (kill-new string nil yank-handler)))
8005 (when (or string (eq last-command 'kill-region))
8006 (setq this-command 'kill-region))
8011 ;; @bullet{} The third argument to 'condition-case' tells the interpreter
8012 ;; what to do with an error.
8015 ;; The third argument has a conditions part and a body part.
8016 ;; If the conditions are met (in this case,
8017 ;; if text or buffer are read-only)
8018 ;; then the body is executed.
8021 ;; The first part of the third argument is the following:
8022 ((buffer-read-only text-read-only) ;; the if-part
8023 ;; @dots{} the then-part
8024 (copy-region-as-kill beg end)
8027 ;; Next, also as part of the then-part, set this-command, so
8028 ;; it will be set in an error
8029 (setq this-command 'kill-region)
8030 ;; Finally, in the then-part, send a message if you may copy
8031 ;; the text to the kill ring without signaling an error, but
8032 ;; don't if you may not.
8035 (if kill-read-only-ok
8036 (progn (message "Read only text copied to kill ring") nil)
8037 (barf-if-buffer-read-only)
8038 ;; If the buffer isn't read-only, the text is.
8039 (signal 'text-read-only (list (current-buffer)))))
8047 (defun kill-region (beg end)
8048 "Kill between point and mark.
8049 The text is deleted but saved in the kill ring."
8054 ;; 1. 'condition-case' takes three arguments.
8055 ;; If the first argument is nil, as it is here,
8056 ;; information about the error signal is not
8057 ;; stored for use by another function.
8062 ;; 2. The second argument to 'condition-case'
8063 ;; tells the Lisp interpreter what to do when all goes well.
8067 ;; The 'delete-and-extract-region' function usually does the
8068 ;; work. If the beginning and ending of the region are both
8069 ;; the same, then the variable 'string' will be empty, or nil
8070 (let ((string (delete-and-extract-region beg end)))
8074 ;; 'when' is an 'if' clause that cannot take an 'else-part'.
8075 ;; Emacs normally sets the value of 'last-command' to the
8076 ;; previous command.
8079 ;; 'kill-append' concatenates the new string and the old.
8080 ;; 'kill-new' inserts text into a new item in the kill ring.
8082 (if (eq last-command 'kill-region)
8083 ;; if true, prepend string
8084 (kill-append string (< end beg))
8086 (setq this-command 'kill-region))
8090 ;; 3. The third argument to 'condition-case' tells the interpreter
8091 ;; what to do with an error.
8094 ;; The third argument has a conditions part and a body part.
8095 ;; If the conditions are met (in this case,
8096 ;; if text or buffer are read-only)
8097 ;; then the body is executed.
8100 ((buffer-read-only text-read-only) ;; this is the if-part
8102 (copy-region-as-kill beg end)
8105 (if kill-read-only-ok ;; usually this variable is nil
8106 (message "Read only text copied to kill ring")
8107 ;; or else, signal an error if the buffer is read-only;
8108 (barf-if-buffer-read-only)
8109 ;; and, in any case, signal that the text is read-only.
8110 (signal 'text-read-only (list (current-buffer)))))))
8115 @node condition-case
8116 @subsection @code{condition-case}
8117 @findex condition-case
8119 As we have seen earlier (@pxref{Making Errors, , Generate an Error
8120 Message}), when the Emacs Lisp interpreter has trouble evaluating an
8121 expression, it provides you with help; in the jargon, this is called
8122 ``signaling an error''. Usually, the computer stops the program and
8123 shows you a message.
8125 However, some programs undertake complicated actions. They should not
8126 simply stop on an error. In the @code{kill-region} function, the most
8127 likely error is that you will try to kill text that is read-only and
8128 cannot be removed. So the @code{kill-region} function contains code
8129 to handle this circumstance. This code, which makes up the body of
8130 the @code{kill-region} function, is inside of a @code{condition-case}
8134 The template for @code{condition-case} looks like this:
8141 @var{error-handler}@dots{})
8145 The second argument, @var{bodyform}, is straightforward. The
8146 @code{condition-case} special form causes the Lisp interpreter to
8147 evaluate the code in @var{bodyform}. If no error occurs, the special
8148 form returns the code's value and produces the side-effects, if any.
8150 In short, the @var{bodyform} part of a @code{condition-case}
8151 expression determines what should happen when everything works
8154 However, if an error occurs, among its other actions, the function
8155 generating the error signal will define one or more error condition
8158 An error handler is the third argument to @code{condition-case}.
8159 An error handler has two parts, a @var{condition-name} and a
8160 @var{body}. If the @var{condition-name} part of an error handler
8161 matches a condition name generated by an error, then the @var{body}
8162 part of the error handler is run.
8164 As you will expect, the @var{condition-name} part of an error handler
8165 may be either a single condition name or a list of condition names.
8167 Also, a complete @code{condition-case} expression may contain more
8168 than one error handler. When an error occurs, the first applicable
8171 Lastly, the first argument to the @code{condition-case} expression,
8172 the @var{var} argument, is sometimes bound to a variable that
8173 contains information about the error. However, if that argument is
8174 nil, as is the case in @code{kill-region}, that information is
8178 In brief, in the @code{kill-region} function, the code
8179 @code{condition-case} works like this:
8183 @var{If no errors}, @var{run only this code}
8184 @var{but}, @var{if errors}, @var{run this other code}.
8191 copy-region-as-kill is short, 12 lines, and uses
8192 filter-buffer-substring, which is longer, 39 lines
8193 and has delete-and-extract-region in it.
8194 delete-and-extract-region is written in C.
8196 see Initializing a Variable with @code{defvar}
8198 Initializing a Variable with @code{defvar} includes line 8350
8202 @subsection Lisp macro
8206 The part of the @code{condition-case} expression that is evaluated in
8207 the expectation that all goes well has a @code{when}. The code uses
8208 @code{when} to determine whether the @code{string} variable points to
8211 A @code{when} expression is simply a programmers' convenience. It is
8212 an @code{if} without the possibility of an else clause. In your mind,
8213 you can replace @code{when} with @code{if} and understand what goes
8214 on. That is what the Lisp interpreter does.
8216 Technically speaking, @code{when} is a Lisp macro. A Lisp macro
8217 enables you to define new control constructs and other language
8218 features. It tells the interpreter how to compute another Lisp
8219 expression which will in turn compute the value. In this case, the
8220 other expression is an @code{if} expression.
8222 The @code{kill-region} function definition also has an @code{unless}
8223 macro; it is the converse of @code{when}. The @code{unless} macro is
8224 an @code{if} without a then clause
8226 For more about Lisp macros, see @ref{Macros, , Macros, elisp, The GNU
8227 Emacs Lisp Reference Manual}. The C programming language also
8228 provides macros. These are different, but also useful.
8231 We will briefly look at C macros in
8232 @ref{Digression into C}.
8236 Regarding the @code{when} macro, in the @code{condition-case}
8237 expression, when the string has content, then another conditional
8238 expression is executed. This is an @code{if} with both a then-part
8243 (if (eq last-command 'kill-region)
8244 (kill-append string (< end beg) yank-handler)
8245 (kill-new string nil yank-handler))
8249 The then-part is evaluated if the previous command was another call to
8250 @code{kill-region}; if not, the else-part is evaluated.
8252 @code{yank-handler} is an optional argument to @code{kill-region} that
8253 tells the @code{kill-append} and @code{kill-new} functions how deal
8254 with properties added to the text, such as bold or italics.
8256 @code{last-command} is a variable that comes with Emacs that we have
8257 not seen before. Normally, whenever a function is executed, Emacs
8258 sets the value of @code{last-command} to the previous command.
8261 In this segment of the definition, the @code{if} expression checks
8262 whether the previous command was @code{kill-region}. If it was,
8265 (kill-append string (< end beg) yank-handler)
8269 concatenates a copy of the newly clipped text to the just previously
8270 clipped text in the kill ring.
8272 @node copy-region-as-kill
8273 @section @code{copy-region-as-kill}
8274 @findex copy-region-as-kill
8277 The @code{copy-region-as-kill} function copies a region of text from a
8278 buffer and (via either @code{kill-append} or @code{kill-new}) saves it
8279 in the @code{kill-ring}.
8281 If you call @code{copy-region-as-kill} immediately after a
8282 @code{kill-region} command, Emacs appends the newly copied text to the
8283 previously copied text. This means that if you yank back the text, you
8284 get it all, from both this and the previous operation. On the other
8285 hand, if some other command precedes the @code{copy-region-as-kill},
8286 the function copies the text into a separate entry in the kill ring.
8289 * Complete copy-region-as-kill:: The complete function definition.
8290 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
8294 @node Complete copy-region-as-kill
8295 @unnumberedsubsec The complete @code{copy-region-as-kill} function definition
8299 Here is the complete text of the version 22 @code{copy-region-as-kill}
8304 (defun copy-region-as-kill (beg end)
8305 "Save the region as if killed, but don't kill it.
8306 In Transient Mark mode, deactivate the mark.
8307 If `interprogram-cut-function' is non-nil, also save the text for a window
8308 system cut and paste."
8312 (if (eq last-command 'kill-region)
8313 (kill-append (filter-buffer-substring beg end) (< end beg))
8314 (kill-new (filter-buffer-substring beg end)))
8317 (if transient-mark-mode
8318 (setq deactivate-mark t))
8324 As usual, this function can be divided into its component parts:
8328 (defun copy-region-as-kill (@var{argument-list})
8329 "@var{documentation}@dots{}"
8335 The arguments are @code{beg} and @code{end} and the function is
8336 interactive with @code{"r"}, so the two arguments must refer to the
8337 beginning and end of the region. If you have been reading through this
8338 document from the beginning, understanding these parts of a function is
8339 almost becoming routine.
8341 The documentation is somewhat confusing unless you remember that the
8342 word ``kill'' has a meaning different from usual. The Transient Mark
8343 and @code{interprogram-cut-function} comments explain certain
8346 After you once set a mark, a buffer always contains a region. If you
8347 wish, you can use Transient Mark mode to highlight the region
8348 temporarily. (No one wants to highlight the region all the time, so
8349 Transient Mark mode highlights it only at appropriate times. Many
8350 people turn off Transient Mark mode, so the region is never
8353 Also, a windowing system allows you to copy, cut, and paste among
8354 different programs. In the X windowing system, for example, the
8355 @code{interprogram-cut-function} function is @code{x-select-text},
8356 which works with the windowing system's equivalent of the Emacs kill
8359 The body of the @code{copy-region-as-kill} function starts with an
8360 @code{if} clause. What this clause does is distinguish between two
8361 different situations: whether or not this command is executed
8362 immediately after a previous @code{kill-region} command. In the first
8363 case, the new region is appended to the previously copied text.
8364 Otherwise, it is inserted into the beginning of the kill ring as a
8365 separate piece of text from the previous piece.
8367 The last two lines of the function prevent the region from lighting up
8368 if Transient Mark mode is turned on.
8370 The body of @code{copy-region-as-kill} merits discussion in detail.
8372 @node copy-region-as-kill body
8373 @subsection The Body of @code{copy-region-as-kill}
8375 The @code{copy-region-as-kill} function works in much the same way as
8376 the @code{kill-region} function. Both are written so that two or more
8377 kills in a row combine their text into a single entry. If you yank
8378 back the text from the kill ring, you get it all in one piece.
8379 Moreover, kills that kill forward from the current position of the
8380 cursor are added to the end of the previously copied text and commands
8381 that copy text backwards add it to the beginning of the previously
8382 copied text. This way, the words in the text stay in the proper
8385 Like @code{kill-region}, the @code{copy-region-as-kill} function makes
8386 use of the @code{last-command} variable that keeps track of the
8387 previous Emacs command.
8390 * last-command & this-command::
8391 * kill-append function::
8392 * kill-new function::
8396 @node last-command & this-command
8397 @unnumberedsubsubsec @code{last-command} and @code{this-command}
8400 Normally, whenever a function is executed, Emacs sets the value of
8401 @code{this-command} to the function being executed (which in this case
8402 would be @code{copy-region-as-kill}). At the same time, Emacs sets
8403 the value of @code{last-command} to the previous value of
8404 @code{this-command}.
8406 In the first part of the body of the @code{copy-region-as-kill}
8407 function, an @code{if} expression determines whether the value of
8408 @code{last-command} is @code{kill-region}. If so, the then-part of
8409 the @code{if} expression is evaluated; it uses the @code{kill-append}
8410 function to concatenate the text copied at this call to the function
8411 with the text already in the first element (the @sc{car}) of the kill
8412 ring. On the other hand, if the value of @code{last-command} is not
8413 @code{kill-region}, then the @code{copy-region-as-kill} function
8414 attaches a new element to the kill ring using the @code{kill-new}
8418 The @code{if} expression reads as follows; it uses @code{eq}:
8422 (if (eq last-command 'kill-region)
8424 (kill-append (filter-buffer-substring beg end) (< end beg))
8426 (kill-new (filter-buffer-substring beg end)))
8430 @findex filter-buffer-substring
8431 (The @code{filter-buffer-substring} function returns a filtered
8432 substring of the buffer, if any. Optionally---the arguments are not
8433 here, so neither is done---the function may delete the initial text or
8434 return the text without its properties; this function is a replacement
8435 for the older @code{buffer-substring} function, which came before text
8436 properties were implemented.)
8438 @findex eq @r{(example of use)}
8440 The @code{eq} function tests whether its first argument is the same Lisp
8441 object as its second argument. The @code{eq} function is similar to the
8442 @code{equal} function in that it is used to test for equality, but
8443 differs in that it determines whether two representations are actually
8444 the same object inside the computer, but with different names.
8445 @code{equal} determines whether the structure and contents of two
8446 expressions are the same.
8448 If the previous command was @code{kill-region}, then the Emacs Lisp
8449 interpreter calls the @code{kill-append} function
8451 @node kill-append function
8452 @unnumberedsubsubsec The @code{kill-append} function
8456 The @code{kill-append} function looks like this:
8461 (defun kill-append (string before-p &optional yank-handler)
8462 "Append STRING to the end of the latest kill in the kill ring.
8463 If BEFORE-P is non-nil, prepend STRING to the kill.
8465 (let* ((cur (car kill-ring)))
8466 (kill-new (if before-p (concat string cur) (concat cur string))
8467 (or (= (length cur) 0)
8469 (get-text-property 0 'yank-handler cur)))
8476 (defun kill-append (string before-p)
8477 "Append STRING to the end of the latest kill in the kill ring.
8478 If BEFORE-P is non-nil, prepend STRING to the kill.
8479 If `interprogram-cut-function' is set, pass the resulting kill to
8481 (kill-new (if before-p
8482 (concat string (car kill-ring))
8483 (concat (car kill-ring) string))
8488 The @code{kill-append} function is fairly straightforward. It uses
8489 the @code{kill-new} function, which we will discuss in more detail in
8492 (Also, the function provides an optional argument called
8493 @code{yank-handler}; when invoked, this argument tells the function
8494 how to deal with properties added to the text, such as bold or
8497 @c !!! bug in GNU Emacs 22 version of kill-append ?
8498 It has a @code{let*} function to set the value of the first element of
8499 the kill ring to @code{cur}. (I do not know why the function does not
8500 use @code{let} instead; only one value is set in the expression.
8501 Perhaps this is a bug that produces no problems?)
8503 Consider the conditional that is one of the two arguments to
8504 @code{kill-new}. It uses @code{concat} to concatenate the new text to
8505 the @sc{car} of the kill ring. Whether it prepends or appends the
8506 text depends on the results of an @code{if} expression:
8510 (if before-p ; @r{if-part}
8511 (concat string cur) ; @r{then-part}
8512 (concat cur string)) ; @r{else-part}
8517 If the region being killed is before the region that was killed in the
8518 last command, then it should be prepended before the material that was
8519 saved in the previous kill; and conversely, if the killed text follows
8520 what was just killed, it should be appended after the previous text.
8521 The @code{if} expression depends on the predicate @code{before-p} to
8522 decide whether the newly saved text should be put before or after the
8523 previously saved text.
8525 The symbol @code{before-p} is the name of one of the arguments to
8526 @code{kill-append}. When the @code{kill-append} function is
8527 evaluated, it is bound to the value returned by evaluating the actual
8528 argument. In this case, this is the expression @code{(< end beg)}.
8529 This expression does not directly determine whether the killed text in
8530 this command is located before or after the kill text of the last
8531 command; what it does is determine whether the value of the variable
8532 @code{end} is less than the value of the variable @code{beg}. If it
8533 is, it means that the user is most likely heading towards the
8534 beginning of the buffer. Also, the result of evaluating the predicate
8535 expression, @code{(< end beg)}, will be true and the text will be
8536 prepended before the previous text. On the other hand, if the value of
8537 the variable @code{end} is greater than the value of the variable
8538 @code{beg}, the text will be appended after the previous text.
8541 When the newly saved text will be prepended, then the string with the new
8542 text will be concatenated before the old text:
8550 But if the text will be appended, it will be concatenated
8554 (concat cur string))
8557 To understand how this works, we first need to review the
8558 @code{concat} function. The @code{concat} function links together or
8559 unites two strings of text. The result is a string. For example:
8563 (concat "abc" "def")
8569 (car '("first element" "second element")))
8570 @result{} "new first element"
8573 '("first element" "second element")) " modified")
8574 @result{} "first element modified"
8578 We can now make sense of @code{kill-append}: it modifies the contents
8579 of the kill ring. The kill ring is a list, each element of which is
8580 saved text. The @code{kill-append} function uses the @code{kill-new}
8581 function which in turn uses the @code{setcar} function.
8583 @node kill-new function
8584 @unnumberedsubsubsec The @code{kill-new} function
8588 In version 22 the @code{kill-new} function looks like this:
8592 (defun kill-new (string &optional replace yank-handler)
8593 "Make STRING the latest kill in the kill ring.
8594 Set `kill-ring-yank-pointer' to point to it.
8596 If `interprogram-cut-function' is non-nil, apply it to STRING.
8597 Optional second argument REPLACE non-nil means that STRING will replace
8598 the front of the kill ring, rather than being added to the list.
8602 (if (> (length string) 0)
8604 (put-text-property 0 (length string)
8605 'yank-handler yank-handler string))
8607 (signal 'args-out-of-range
8608 (list string "yank-handler specified for empty string"))))
8611 (if (fboundp 'menu-bar-update-yank-menu)
8612 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8615 (if (and replace kill-ring)
8616 (setcar kill-ring string)
8617 (push string kill-ring)
8618 (if (> (length kill-ring) kill-ring-max)
8619 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8622 (setq kill-ring-yank-pointer kill-ring)
8623 (if interprogram-cut-function
8624 (funcall interprogram-cut-function string (not replace))))
8629 (defun kill-new (string &optional replace)
8630 "Make STRING the latest kill in the kill ring.
8631 Set the kill-ring-yank pointer to point to it.
8632 If `interprogram-cut-function' is non-nil, apply it to STRING.
8633 Optional second argument REPLACE non-nil means that STRING will replace
8634 the front of the kill ring, rather than being added to the list."
8635 (and (fboundp 'menu-bar-update-yank-menu)
8636 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8637 (if (and replace kill-ring)
8638 (setcar kill-ring string)
8639 (setq kill-ring (cons string kill-ring))
8640 (if (> (length kill-ring) kill-ring-max)
8641 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8642 (setq kill-ring-yank-pointer kill-ring)
8643 (if interprogram-cut-function
8644 (funcall interprogram-cut-function string (not replace))))
8647 (Notice that the function is not interactive.)
8649 As usual, we can look at this function in parts.
8651 The function definition has an optional @code{yank-handler} argument,
8652 which when invoked tells the function how to deal with properties
8653 added to the text, such as bold or italics. We will skip that.
8656 The first line of the documentation makes sense:
8659 Make STRING the latest kill in the kill ring.
8663 Let's skip over the rest of the documentation for the moment.
8666 Also, let's skip over the initial @code{if} expression and those lines
8667 of code involving @code{menu-bar-update-yank-menu}. We will explain
8671 The critical lines are these:
8675 (if (and replace kill-ring)
8677 (setcar kill-ring string)
8681 (push string kill-ring)
8684 (setq kill-ring (cons string kill-ring))
8685 (if (> (length kill-ring) kill-ring-max)
8686 ;; @r{avoid overly long kill ring}
8687 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8690 (setq kill-ring-yank-pointer kill-ring)
8691 (if interprogram-cut-function
8692 (funcall interprogram-cut-function string (not replace))))
8696 The conditional test is @w{@code{(and replace kill-ring)}}.
8697 This will be true when two conditions are met: the kill ring has
8698 something in it, and the @code{replace} variable is true.
8701 When the @code{kill-append} function sets @code{replace} to be true
8702 and when the kill ring has at least one item in it, the @code{setcar}
8703 expression is executed:
8706 (setcar kill-ring string)
8709 The @code{setcar} function actually changes the first element of the
8710 @code{kill-ring} list to the value of @code{string}. It replaces the
8714 On the other hand, if the kill ring is empty, or replace is false, the
8715 else-part of the condition is executed:
8718 (push string kill-ring)
8723 @code{push} puts its first argument onto the second. It is similar to
8727 (setq kill-ring (cons string kill-ring))
8735 (add-to-list kill-ring string)
8739 When it is false, the expression first constructs a new version of the
8740 kill ring by prepending @code{string} to the existing kill ring as a
8741 new element (that is what the @code{push} does). Then it executes a
8742 second @code{if} clause. This second @code{if} clause keeps the kill
8743 ring from growing too long.
8745 Let's look at these two expressions in order.
8747 The @code{push} line of the else-part sets the new value of the kill
8748 ring to what results from adding the string being killed to the old
8751 We can see how this works with an example.
8757 (setq example-list '("here is a clause" "another clause"))
8762 After evaluating this expression with @kbd{C-x C-e}, you can evaluate
8763 @code{example-list} and see what it returns:
8768 @result{} ("here is a clause" "another clause")
8774 Now, we can add a new element on to this list by evaluating the
8775 following expression:
8776 @findex push, @r{example}
8779 (push "a third clause" example-list)
8784 When we evaluate @code{example-list}, we find its value is:
8789 @result{} ("a third clause" "here is a clause" "another clause")
8794 Thus, the third clause is added to the list by @code{push}.
8797 Now for the second part of the @code{if} clause. This expression
8798 keeps the kill ring from growing too long. It looks like this:
8802 (if (> (length kill-ring) kill-ring-max)
8803 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
8807 The code checks whether the length of the kill ring is greater than
8808 the maximum permitted length. This is the value of
8809 @code{kill-ring-max} (which is 60, by default). If the length of the
8810 kill ring is too long, then this code sets the last element of the
8811 kill ring to @code{nil}. It does this by using two functions,
8812 @code{nthcdr} and @code{setcdr}.
8814 We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
8815 It sets the @sc{cdr} of a list, just as @code{setcar} sets the
8816 @sc{car} of a list. In this case, however, @code{setcdr} will not be
8817 setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
8818 function is used to cause it to set the @sc{cdr} of the next to last
8819 element of the kill ring---this means that since the @sc{cdr} of the
8820 next to last element is the last element of the kill ring, it will set
8821 the last element of the kill ring.
8823 @findex nthcdr, @r{example}
8824 The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
8825 list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
8826 @dots{} It does this @var{N} times and returns the results.
8827 (@xref{nthcdr, , @code{nthcdr}}.)
8829 @findex setcdr, @r{example}
8830 Thus, if we had a four element list that was supposed to be three
8831 elements long, we could set the @sc{cdr} of the next to last element
8832 to @code{nil}, and thereby shorten the list. (If you set the last
8833 element to some other value than @code{nil}, which you could do, then
8834 you would not have shortened the list. @xref{setcdr, ,
8837 You can see shortening by evaluating the following three expressions
8838 in turn. First set the value of @code{trees} to @code{(maple oak pine
8839 birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
8840 and then find the value of @code{trees}:
8844 (setq trees '(maple oak pine birch))
8845 @result{} (maple oak pine birch)
8849 (setcdr (nthcdr 2 trees) nil)
8853 @result{} (maple oak pine)
8858 (The value returned by the @code{setcdr} expression is @code{nil} since
8859 that is what the @sc{cdr} is set to.)
8861 To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
8862 @sc{cdr} a number of times that is one less than the maximum permitted
8863 size of the kill ring and @code{setcdr} sets the @sc{cdr} of that
8864 element (which will be the rest of the elements in the kill ring) to
8865 @code{nil}. This prevents the kill ring from growing too long.
8868 The next to last expression in the @code{kill-new} function is
8871 (setq kill-ring-yank-pointer kill-ring)
8874 The @code{kill-ring-yank-pointer} is a global variable that is set to be
8875 the @code{kill-ring}.
8877 Even though the @code{kill-ring-yank-pointer} is called a
8878 @samp{pointer}, it is a variable just like the kill ring. However, the
8879 name has been chosen to help humans understand how the variable is used.
8882 Now, to return to an early expression in the body of the function:
8886 (if (fboundp 'menu-bar-update-yank-menu)
8887 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8892 It starts with an @code{if} expression
8894 In this case, the expression tests first to see whether
8895 @code{menu-bar-update-yank-menu} exists as a function, and if so,
8896 calls it. The @code{fboundp} function returns true if the symbol it
8897 is testing has a function definition that is not void. If the
8898 symbol's function definition were void, we would receive an error
8899 message, as we did when we created errors intentionally (@pxref{Making
8900 Errors, , Generate an Error Message}).
8903 The then-part contains an expression whose first element is the
8904 function @code{and}.
8907 The @code{and} special form evaluates each of its arguments until one
8908 of the arguments returns a value of @code{nil}, in which case the
8909 @code{and} expression returns @code{nil}; however, if none of the
8910 arguments returns a value of @code{nil}, the value resulting from
8911 evaluating the last argument is returned. (Since such a value is not
8912 @code{nil}, it is considered true in Emacs Lisp.) In other words, an
8913 @code{and} expression returns a true value only if all its arguments
8914 are true. (@xref{Second Buffer Related Review}.)
8916 The expression determines whether the second argument to
8917 @code{menu-bar-update-yank-menu} is true or not.
8919 ;; If we're supposed to be extending an existing string, and that
8920 ;; string really is at the front of the menu, then update it in place.
8923 @code{menu-bar-update-yank-menu} is one of the functions that make it
8924 possible to use the ``Select and Paste'' menu in the Edit item of a menu
8925 bar; using a mouse, you can look at the various pieces of text you
8926 have saved and select one piece to paste.
8928 The last expression in the @code{kill-new} function adds the newly
8929 copied string to whatever facility exists for copying and pasting
8930 among different programs running in a windowing system. In the X
8931 Windowing system, for example, the @code{x-select-text} function takes
8932 the string and stores it in memory operated by X@. You can paste the
8933 string in another program, such as an Xterm.
8936 The expression looks like this:
8940 (if interprogram-cut-function
8941 (funcall interprogram-cut-function string (not replace))))
8945 If an @code{interprogram-cut-function} exists, then Emacs executes
8946 @code{funcall}, which in turn calls its first argument as a function
8947 and passes the remaining arguments to it. (Incidentally, as far as I
8948 can see, this @code{if} expression could be replaced by an @code{and}
8949 expression similar to the one in the first part of the function.)
8951 We are not going to discuss windowing systems and other programs
8952 further, but merely note that this is a mechanism that enables GNU
8953 Emacs to work easily and well with other programs.
8955 This code for placing text in the kill ring, either concatenated with
8956 an existing element or as a new element, leads us to the code for
8957 bringing back text that has been cut out of the buffer---the yank
8958 commands. However, before discussing the yank commands, it is better
8959 to learn how lists are implemented in a computer. This will make
8960 clear such mysteries as the use of the term ``pointer''. But before
8961 that, we will digress into C.
8964 @c is this true in Emacs 22? Does not seems to be
8966 (If the @w{@code{(< end beg))}}
8967 expression is true, @code{kill-append} prepends the string to the just
8968 previously clipped text. For a detailed discussion, see
8969 @ref{kill-append function, , The @code{kill-append} function}.)
8971 If you then yank back the text, i.e., paste it, you get both
8972 pieces of text at once. That way, if you delete two words in a row,
8973 and then yank them back, you get both words, in their proper order,
8974 with one yank. (The @w{@code{(< end beg))}} expression makes sure the
8977 On the other hand, if the previous command is not @code{kill-region},
8978 then the @code{kill-new} function is called, which adds the text to
8979 the kill ring as the latest item, and sets the
8980 @code{kill-ring-yank-pointer} variable to point to it.
8984 @c Evidently, changed for Emacs 22. The zap-to-char command does not
8985 @c use the delete-and-extract-region function
8987 2006 Oct 26, the Digression into C is now OK but should come after
8988 copy-region-as-kill and filter-buffer-substring
8992 copy-region-as-kill is short, 12 lines, and uses
8993 filter-buffer-substring, which is longer, 39 lines
8994 and has delete-and-extract-region in it.
8995 delete-and-extract-region is written in C.
8997 see Initializing a Variable with @code{defvar}
9000 @node Digression into C
9001 @section Digression into C
9002 @findex delete-and-extract-region
9003 @cindex C, a digression into
9004 @cindex Digression into C
9006 The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, ,
9007 @code{copy-region-as-kill}}) uses the @code{filter-buffer-substring}
9008 function, which in turn uses the @code{delete-and-extract-region}
9009 function. It removes the contents of a region and you cannot get them
9012 Unlike the other code discussed here, the
9013 @code{delete-and-extract-region} function is not written in Emacs
9014 Lisp; it is written in C and is one of the primitives of the GNU Emacs
9015 system. Since it is very simple, I will digress briefly from Lisp and
9018 @c GNU Emacs 24 in src/editfns.c
9019 @c the DEFUN for delete-and-extract-region
9022 Like many of the other Emacs primitives,
9023 @code{delete-and-extract-region} is written as an instance of a C
9024 macro, a macro being a template for code. The complete macro looks
9029 DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
9030 Sdelete_and_extract_region, 2, 2, 0,
9031 doc: /* Delete the text between START and END and return it. */)
9032 (Lisp_Object start, Lisp_Object end)
9034 validate_region (&start, &end);
9035 if (XINT (start) == XINT (end))
9036 return empty_unibyte_string;
9037 return del_range_1 (XINT (start), XINT (end), 1, 1);
9042 Without going into the details of the macro writing process, let me
9043 point out that this macro starts with the word @code{DEFUN}. The word
9044 @code{DEFUN} was chosen since the code serves the same purpose as
9045 @code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in
9046 @file{emacs/src/lisp.h}.)
9048 The word @code{DEFUN} is followed by seven parts inside of
9053 The first part is the name given to the function in Lisp,
9054 @code{delete-and-extract-region}.
9057 The second part is the name of the function in C,
9058 @code{Fdelete_and_extract_region}. By convention, it starts with
9059 @samp{F}. Since C does not use hyphens in names, underscores are used
9063 The third part is the name for the C constant structure that records
9064 information on this function for internal use. It is the name of the
9065 function in C but begins with an @samp{S} instead of an @samp{F}.
9068 The fourth and fifth parts specify the minimum and maximum number of
9069 arguments the function can have. This function demands exactly 2
9073 The sixth part is nearly like the argument that follows the
9074 @code{interactive} declaration in a function written in Lisp: a letter
9075 followed, perhaps, by a prompt. The only difference from the Lisp is
9076 when the macro is called with no arguments. Then you write a @code{0}
9077 (which is a null string), as in this macro.
9079 If you were to specify arguments, you would place them between
9080 quotation marks. The C macro for @code{goto-char} includes
9081 @code{"NGoto char: "} in this position to indicate that the function
9082 expects a raw prefix, in this case, a numerical location in a buffer,
9083 and provides a prompt.
9086 The seventh part is a documentation string, just like the one for a
9087 function written in Emacs Lisp. This is written as a C comment. (When
9088 you build Emacs, the program @command{lib-src/make-docfile} extracts
9089 these comments and uses them to make the documentation.)
9093 In a C macro, the formal parameters come next, with a statement of
9094 what kind of object they are, followed by the body
9095 of the macro. For @code{delete-and-extract-region} the body
9096 consists of the following four lines:
9100 validate_region (&start, &end);
9101 if (XINT (start) == XINT (end))
9102 return empty_unibyte_string;
9103 return del_range_1 (XINT (start), XINT (end), 1, 1);
9107 The @code{validate_region} function checks whether the values
9108 passed as the beginning and end of the region are the proper type and
9109 are within range. If the beginning and end positions are the same,
9110 then return an empty string.
9112 The @code{del_range_1} function actually deletes the text. It is a
9113 complex function we will not look into. It updates the buffer and
9114 does other things. However, it is worth looking at the two arguments
9115 passed to @code{del_range}. These are @w{@code{XINT (start)}} and
9116 @w{@code{XINT (end)}}.
9118 As far as the C language is concerned, @code{start} and @code{end} are
9119 two integers that mark the beginning and end of the region to be
9120 deleted@footnote{More precisely, and requiring more expert knowledge
9121 to understand, the two integers are of type @code{Lisp_Object}, which can
9122 also be a C union instead of an integer type.}.
9124 In early versions of Emacs, these two numbers were thirty-two bits
9125 long, but the code is slowly being generalized to handle other
9126 lengths. Three of the available bits are used to specify the type of
9127 information; the remaining bits are used as content.
9129 @samp{XINT} is a C macro that extracts the relevant number from the
9130 longer collection of bits; the three other bits are discarded.
9133 The command in @code{delete-and-extract-region} looks like this:
9136 del_range_1 (XINT (start), XINT (end), 1, 1);
9140 It deletes the region between the beginning position, @code{start},
9141 and the ending position, @code{end}.
9143 From the point of view of the person writing Lisp, Emacs is all very
9144 simple; but hidden underneath is a great deal of complexity to make it
9148 @section Initializing a Variable with @code{defvar}
9150 @cindex Initializing a variable
9151 @cindex Variable initialization
9156 copy-region-as-kill is short, 12 lines, and uses
9157 filter-buffer-substring, which is longer, 39 lines
9158 and has delete-and-extract-region in it.
9159 delete-and-extract-region is written in C.
9161 see Initializing a Variable with @code{defvar}
9165 The @code{copy-region-as-kill} function is written in Emacs Lisp. Two
9166 functions within it, @code{kill-append} and @code{kill-new}, copy a
9167 region in a buffer and save it in a variable called the
9168 @code{kill-ring}. This section describes how the @code{kill-ring}
9169 variable is created and initialized using the @code{defvar} special
9172 (Again we note that the term @code{kill-ring} is a misnomer. The text
9173 that is clipped out of the buffer can be brought back; it is not a ring
9174 of corpses, but a ring of resurrectable text.)
9176 In Emacs Lisp, a variable such as the @code{kill-ring} is created and
9177 given an initial value by using the @code{defvar} special form. The
9178 name comes from ``define variable''.
9180 The @code{defvar} special form is similar to @code{setq} in that it sets
9181 the value of a variable. It is unlike @code{setq} in two ways: first,
9182 it only sets the value of the variable if the variable does not already
9183 have a value. If the variable already has a value, @code{defvar} does
9184 not override the existing value. Second, @code{defvar} has a
9185 documentation string.
9187 (There is a related macro, @code{defcustom}, designed for variables
9188 that people customize. It has more features than @code{defvar}.
9189 (@xref{defcustom, , Setting Variables with @code{defcustom}}.)
9192 * See variable current value::
9193 * defvar and asterisk::
9197 @node See variable current value
9198 @unnumberedsubsec Seeing the Current Value of a Variable
9201 You can see the current value of a variable, any variable, by using
9202 the @code{describe-variable} function, which is usually invoked by
9203 typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring}
9204 (followed by @key{RET}) when prompted, you will see what is in your
9205 current kill ring---this may be quite a lot! Conversely, if you have
9206 been doing nothing this Emacs session except read this document, you
9207 may have nothing in it. Also, you will see the documentation for
9213 List of killed text sequences.
9214 Since the kill ring is supposed to interact nicely with cut-and-paste
9215 facilities offered by window systems, use of this variable should
9218 interact nicely with `interprogram-cut-function' and
9219 `interprogram-paste-function'. The functions `kill-new',
9220 `kill-append', and `current-kill' are supposed to implement this
9221 interaction; you may want to use them instead of manipulating the kill
9227 The kill ring is defined by a @code{defvar} in the following way:
9231 (defvar kill-ring nil
9232 "List of killed text sequences.
9238 In this variable definition, the variable is given an initial value of
9239 @code{nil}, which makes sense, since if you have saved nothing, you want
9240 nothing back if you give a @code{yank} command. The documentation
9241 string is written just like the documentation string of a @code{defun}.
9242 As with the documentation string of the @code{defun}, the first line of
9243 the documentation should be a complete sentence, since some commands,
9244 like @code{apropos}, print only the first line of documentation.
9245 Succeeding lines should not be indented; otherwise they look odd when
9246 you use @kbd{C-h v} (@code{describe-variable}).
9248 @node defvar and asterisk
9249 @subsection @code{defvar} and an asterisk
9250 @findex defvar @r{for a user customizable variable}
9251 @findex defvar @r{with an asterisk}
9253 In the past, Emacs used the @code{defvar} special form both for
9254 internal variables that you would not expect a user to change and for
9255 variables that you do expect a user to change. Although you can still
9256 use @code{defvar} for user customizable variables, please use
9257 @code{defcustom} instead, since it provides a path into
9258 the Customization commands. (@xref{defcustom, , Specifying Variables
9259 using @code{defcustom}}.)
9261 When you specified a variable using the @code{defvar} special form,
9262 you could distinguish a variable that a user might want to change from
9263 others by typing an asterisk, @samp{*}, in the first column of its
9264 documentation string. For example:
9268 (defvar shell-command-default-error-buffer nil
9269 "*Buffer name for `shell-command' @dots{} error output.
9274 @findex set-variable
9276 You could (and still can) use the @code{set-variable} command to
9277 change the value of @code{shell-command-default-error-buffer}
9278 temporarily. However, options set using @code{set-variable} are set
9279 only for the duration of your editing session. The new values are not
9280 saved between sessions. Each time Emacs starts, it reads the original
9281 value, unless you change the value within your @file{.emacs} file,
9282 either by setting it manually or by using @code{customize}.
9283 @xref{Emacs Initialization, , Your @file{.emacs} File}.
9285 For me, the major use of the @code{set-variable} command is to suggest
9286 variables that I might want to set in my @file{.emacs} file. There
9287 are now more than 700 such variables, far too many to remember
9288 readily. Fortunately, you can press @key{TAB} after calling the
9289 @code{M-x set-variable} command to see the list of variables.
9290 (@xref{Examining, , Examining and Setting Variables, emacs,
9291 The GNU Emacs Manual}.)
9294 @node cons & search-fwd Review
9297 Here is a brief summary of some recently introduced functions.
9302 @code{car} returns the first element of a list; @code{cdr} returns the
9303 second and subsequent elements of a list.
9310 (car '(1 2 3 4 5 6 7))
9312 (cdr '(1 2 3 4 5 6 7))
9313 @result{} (2 3 4 5 6 7)
9318 @code{cons} constructs a list by prepending its first argument to its
9332 @code{funcall} evaluates its first argument as a function. It passes
9333 its remaining arguments to its first argument.
9336 Return the result of taking @sc{cdr} @var{n} times on a list.
9344 The ``rest of the rest'', as it were.
9351 (nthcdr 3 '(1 2 3 4 5 6 7))
9358 @code{setcar} changes the first element of a list; @code{setcdr}
9359 changes the second and subsequent elements of a list.
9366 (setq triple '(1 2 3))
9373 (setcdr triple '("foo" "bar"))
9376 @result{} (37 "foo" "bar")
9381 Evaluate each argument in sequence and then return the value of the
9394 @item save-restriction
9395 Record whatever narrowing is in effect in the current buffer, if any,
9396 and restore that narrowing after evaluating the arguments.
9398 @item search-forward
9399 Search for a string, and if the string is found, move point. With a
9400 regular expression, use the similar @code{re-search-forward}.
9401 (@xref{Regexp Search, , Regular Expression Searches}, for an
9402 explanation of regular expression patterns and searches.)
9406 @code{search-forward} and @code{re-search-forward} take four
9411 The string or regular expression to search for.
9414 Optionally, the limit of the search.
9417 Optionally, what to do if the search fails, return @code{nil} or an
9421 Optionally, how many times to repeat the search; if negative, the
9422 search goes backwards.
9426 @itemx delete-and-extract-region
9427 @itemx copy-region-as-kill
9429 @code{kill-region} cuts the text between point and mark from the
9430 buffer and stores that text in the kill ring, so you can get it back
9433 @code{copy-region-as-kill} copies the text between point and mark into
9434 the kill ring, from which you can get it by yanking. The function
9435 does not cut or remove the text from the buffer.
9438 @code{delete-and-extract-region} removes the text between point and
9439 mark from the buffer and throws it away. You cannot get it back.
9440 (This is not an interactive command.)
9443 @node search Exercises
9444 @section Searching Exercises
9448 Write an interactive function that searches for a string. If the
9449 search finds the string, leave point after it and display a message
9450 that says ``Found!''. (Do not use @code{search-forward} for the name
9451 of this function; if you do, you will overwrite the existing version of
9452 @code{search-forward} that comes with Emacs. Use a name such as
9453 @code{test-search} instead.)
9456 Write a function that prints the third element of the kill ring in the
9457 echo area, if any; if the kill ring does not contain a third element,
9458 print an appropriate message.
9461 @node List Implementation
9462 @chapter How Lists are Implemented
9463 @cindex Lists in a computer
9465 In Lisp, atoms are recorded in a straightforward fashion; if the
9466 implementation is not straightforward in practice, it is, nonetheless,
9467 straightforward in theory. The atom @samp{rose}, for example, is
9468 recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s},
9469 @samp{e}. A list, on the other hand, is kept differently. The mechanism
9470 is equally simple, but it takes a moment to get used to the idea. A
9471 list is kept using a series of pairs of pointers. In the series, the
9472 first pointer in each pair points to an atom or to another list, and the
9473 second pointer in each pair points to the next pair, or to the symbol
9474 @code{nil}, which marks the end of the list.
9476 A pointer itself is quite simply the electronic address of what is
9477 pointed to. Hence, a list is kept as a series of electronic addresses.
9480 * Lists diagrammed::
9481 * Symbols as Chest:: Exploring a powerful metaphor.
9486 @node Lists diagrammed
9487 @unnumberedsec Lists diagrammed
9490 For example, the list @code{(rose violet buttercup)} has three elements,
9491 @samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the
9492 electronic address of @samp{rose} is recorded in a segment of computer
9493 memory along with the address that gives the electronic address of where
9494 the atom @samp{violet} is located; and that address (the one that tells
9495 where @samp{violet} is located) is kept along with an address that tells
9496 where the address for the atom @samp{buttercup} is located.
9499 This sounds more complicated than it is and is easier seen in a diagram:
9501 @c clear print-postscript-figures
9502 @c !!! cons-cell-diagram #1
9506 ___ ___ ___ ___ ___ ___
9507 |___|___|--> |___|___|--> |___|___|--> nil
9510 --> rose --> violet --> buttercup
9514 @ifset print-postscript-figures
9517 @center @image{cons-1}
9521 @ifclear print-postscript-figures
9525 ___ ___ ___ ___ ___ ___
9526 |___|___|--> |___|___|--> |___|___|--> nil
9529 --> rose --> violet --> buttercup
9536 In the diagram, each box represents a word of computer memory that
9537 holds a Lisp object, usually in the form of a memory address. The boxes,
9538 i.e., the addresses, are in pairs. Each arrow points to what the address
9539 is the address of, either an atom or another pair of addresses. The
9540 first box is the electronic address of @samp{rose} and the arrow points
9541 to @samp{rose}; the second box is the address of the next pair of boxes,
9542 the first part of which is the address of @samp{violet} and the second
9543 part of which is the address of the next pair. The very last box
9544 points to the symbol @code{nil}, which marks the end of the list.
9547 When a variable is set to a list with a function such as @code{setq},
9548 it stores the address of the first box in the variable. Thus,
9549 evaluation of the expression
9552 (setq bouquet '(rose violet buttercup))
9557 creates a situation like this:
9559 @c cons-cell-diagram #2
9565 | ___ ___ ___ ___ ___ ___
9566 --> |___|___|--> |___|___|--> |___|___|--> nil
9569 --> rose --> violet --> buttercup
9573 @ifset print-postscript-figures
9576 @center @image{cons-2}
9580 @ifclear print-postscript-figures
9586 | ___ ___ ___ ___ ___ ___
9587 --> |___|___|--> |___|___|--> |___|___|--> nil
9590 --> rose --> violet --> buttercup
9597 In this example, the symbol @code{bouquet} holds the address of the first
9601 This same list can be illustrated in a different sort of box notation
9604 @c cons-cell-diagram #2a
9610 | -------------- --------------- ----------------
9611 | | car | cdr | | car | cdr | | car | cdr |
9612 -->| rose | o------->| violet | o------->| butter- | nil |
9613 | | | | | | | cup | |
9614 -------------- --------------- ----------------
9618 @ifset print-postscript-figures
9621 @center @image{cons-2a}
9625 @ifclear print-postscript-figures
9631 | -------------- --------------- ----------------
9632 | | car | cdr | | car | cdr | | car | cdr |
9633 -->| rose | o------->| violet | o------->| butter- | nil |
9634 | | | | | | | cup | |
9635 -------------- --------------- ----------------
9641 (Symbols consist of more than pairs of addresses, but the structure of
9642 a symbol is made up of addresses. Indeed, the symbol @code{bouquet}
9643 consists of a group of address-boxes, one of which is the address of
9644 the printed word @samp{bouquet}, a second of which is the address of a
9645 function definition attached to the symbol, if any, a third of which
9646 is the address of the first pair of address-boxes for the list
9647 @code{(rose violet buttercup)}, and so on. Here we are showing that
9648 the symbol's third address-box points to the first pair of
9649 address-boxes for the list.)
9651 If a symbol is set to the @sc{cdr} of a list, the list itself is not
9652 changed; the symbol simply has an address further down the list. (In
9653 the jargon, @sc{car} and @sc{cdr} are ``non-destructive''.) Thus,
9654 evaluation of the following expression
9657 (setq flowers (cdr bouquet))
9664 @c cons-cell-diagram #3
9671 | ___ ___ | ___ ___ ___ ___
9672 --> | | | --> | | | | | |
9673 |___|___|----> |___|___|--> |___|___|--> nil
9676 --> rose --> violet --> buttercup
9681 @ifset print-postscript-figures
9684 @center @image{cons-3}
9688 @ifclear print-postscript-figures
9695 | ___ ___ | ___ ___ ___ ___
9696 --> | | | --> | | | | | |
9697 |___|___|----> |___|___|--> |___|___|--> nil
9700 --> rose --> violet --> buttercup
9708 The value of @code{flowers} is @code{(violet buttercup)}, which is
9709 to say, the symbol @code{flowers} holds the address of the pair of
9710 address-boxes, the first of which holds the address of @code{violet},
9711 and the second of which holds the address of @code{buttercup}.
9713 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
9714 pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp
9715 Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair
9716 Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more
9717 information about cons cells and dotted pairs.
9720 The function @code{cons} adds a new pair of addresses to the front of
9721 a series of addresses like that shown above. For example, evaluating
9725 (setq bouquet (cons 'lily bouquet))
9732 @c cons-cell-diagram #4
9739 | ___ ___ ___ ___ | ___ ___ ___ ___
9740 --> | | | | | | --> | | | | | |
9741 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9744 --> lily --> rose --> violet --> buttercup
9749 @ifset print-postscript-figures
9752 @center @image{cons-4}
9756 @ifclear print-postscript-figures
9763 | ___ ___ ___ ___ | ___ ___ ___ ___
9764 --> | | | | | | --> | | | | | |
9765 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9768 --> lily --> rose --> violet --> buttercup
9777 However, this does not change the value of the symbol
9778 @code{flowers}, as you can see by evaluating the following,
9781 (eq (cdr (cdr bouquet)) flowers)
9785 which returns @code{t} for true.
9787 Until it is reset, @code{flowers} still has the value
9788 @code{(violet buttercup)}; that is, it has the address of the cons
9789 cell whose first address is of @code{violet}. Also, this does not
9790 alter any of the pre-existing cons cells; they are all still there.
9792 Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address
9793 of the next cons cell in the series; to get the @sc{car} of a list,
9794 you get the address of the first element of the list; to @code{cons} a
9795 new element on a list, you add a new cons cell to the front of the list.
9796 That is all there is to it! The underlying structure of Lisp is
9799 And what does the last address in a series of cons cells refer to? It
9800 is the address of the empty list, of @code{nil}.
9802 In summary, when a Lisp variable is set to a value, it is provided with
9803 the address of the list to which the variable refers.
9805 @node Symbols as Chest
9806 @section Symbols as a Chest of Drawers
9807 @cindex Symbols as a Chest of Drawers
9808 @cindex Chest of Drawers, metaphor for a symbol
9809 @cindex Drawers, Chest of, metaphor for a symbol
9811 In an earlier section, I suggested that you might imagine a symbol as
9812 being a chest of drawers. The function definition is put in one
9813 drawer, the value in another, and so on. What is put in the drawer
9814 holding the value can be changed without affecting the contents of the
9815 drawer holding the function definition, and vice versa.
9817 Actually, what is put in each drawer is the address of the value or
9818 function definition. It is as if you found an old chest in the attic,
9819 and in one of its drawers you found a map giving you directions to
9820 where the buried treasure lies.
9822 (In addition to its name, symbol definition, and variable value, a
9823 symbol has a drawer for a @dfn{property list} which can be used to
9824 record other information. Property lists are not discussed here; see
9825 @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp
9829 Here is a fanciful representation:
9831 @c chest-of-drawers diagram
9836 Chest of Drawers Contents of Drawers
9840 ---------------------
9841 | directions to | [map to]
9842 | symbol name | bouquet
9844 +---------------------+
9846 | symbol definition | [none]
9848 +---------------------+
9849 | directions to | [map to]
9850 | variable value | (rose violet buttercup)
9852 +---------------------+
9854 | property list | [not described here]
9856 +---------------------+
9862 @ifset print-postscript-figures
9865 @center @image{drawers}
9869 @ifclear print-postscript-figures
9874 Chest of Drawers Contents of Drawers
9878 ---------------------
9879 | directions to | [map to]
9880 | symbol name | bouquet
9882 +---------------------+
9884 | symbol definition | [none]
9886 +---------------------+
9887 | directions to | [map to]
9888 | variable value | (rose violet buttercup)
9890 +---------------------+
9892 | property list | [not described here]
9894 +---------------------+
9905 Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two
9906 more flowers on to this list and set this new list to
9907 @code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish.
9908 What does the @code{more-flowers} list now contain?
9911 @chapter Yanking Text Back
9913 @cindex Text retrieval
9914 @cindex Retrieving text
9915 @cindex Pasting text
9917 Whenever you cut text out of a buffer with a kill command in GNU Emacs,
9918 you can bring it back with a yank command. The text that is cut out of
9919 the buffer is put in the kill ring and the yank commands insert the
9920 appropriate contents of the kill ring back into a buffer (not necessarily
9921 the original buffer).
9923 A simple @kbd{C-y} (@code{yank}) command inserts the first item from
9924 the kill ring into the current buffer. If the @kbd{C-y} command is
9925 followed immediately by @kbd{M-y}, the first element is replaced by
9926 the second element. Successive @kbd{M-y} commands replace the second
9927 element with the third, fourth, or fifth element, and so on. When the
9928 last element in the kill ring is reached, it is replaced by the first
9929 element and the cycle is repeated. (Thus the kill ring is called a
9930 ``ring'' rather than just a ``list''. However, the actual data structure
9931 that holds the text is a list.
9932 @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the
9933 list is handled as a ring.)
9936 * Kill Ring Overview::
9937 * kill-ring-yank-pointer:: The kill ring is a list.
9938 * yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
9941 @node Kill Ring Overview
9942 @section Kill Ring Overview
9943 @cindex Kill ring overview
9945 The kill ring is a list of textual strings. This is what it looks like:
9948 ("some text" "a different piece of text" "yet more text")
9951 If this were the contents of my kill ring and I pressed @kbd{C-y}, the
9952 string of characters saying @samp{some text} would be inserted in this
9953 buffer where my cursor is located.
9955 The @code{yank} command is also used for duplicating text by copying it.
9956 The copied text is not cut from the buffer, but a copy of it is put on the
9957 kill ring and is inserted by yanking it back.
9959 Three functions are used for bringing text back from the kill ring:
9960 @code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop},
9961 which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer},
9962 which is used by the two other functions.
9964 These functions refer to the kill ring through a variable called the
9965 @code{kill-ring-yank-pointer}. Indeed, the insertion code for both the
9966 @code{yank} and @code{yank-pop} functions is:
9969 (insert (car kill-ring-yank-pointer))
9973 (Well, no more. In GNU Emacs 22, the function has been replaced by
9974 @code{insert-for-yank} which calls @code{insert-for-yank-1}
9975 repetitively for each @code{yank-handler} segment. In turn,
9976 @code{insert-for-yank-1} strips text properties from the inserted text
9977 according to @code{yank-excluded-properties}. Otherwise, it is just
9978 like @code{insert}. We will stick with plain @code{insert} since it
9979 is easier to understand.)
9981 To begin to understand how @code{yank} and @code{yank-pop} work, it is
9982 first necessary to look at the @code{kill-ring-yank-pointer} variable.
9984 @node kill-ring-yank-pointer
9985 @section The @code{kill-ring-yank-pointer} Variable
9987 @code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is
9988 a variable. It points to something by being bound to the value of what
9989 it points to, like any other Lisp variable.
9992 Thus, if the value of the kill ring is:
9995 ("some text" "a different piece of text" "yet more text")
10000 and the @code{kill-ring-yank-pointer} points to the second clause, the
10001 value of @code{kill-ring-yank-pointer} is:
10004 ("a different piece of text" "yet more text")
10007 As explained in the previous chapter (@pxref{List Implementation}), the
10008 computer does not keep two different copies of the text being pointed to
10009 by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The
10010 words ``a different piece of text'' and ``yet more text'' are not
10011 duplicated. Instead, the two Lisp variables point to the same pieces of
10012 text. Here is a diagram:
10014 @c cons-cell-diagram #5
10018 kill-ring kill-ring-yank-pointer
10020 | ___ ___ | ___ ___ ___ ___
10021 ---> | | | --> | | | | | |
10022 |___|___|----> |___|___|--> |___|___|--> nil
10025 | | --> "yet more text"
10027 | --> "a different piece of text"
10034 @ifset print-postscript-figures
10037 @center @image{cons-5}
10041 @ifclear print-postscript-figures
10045 kill-ring kill-ring-yank-pointer
10047 | ___ ___ | ___ ___ ___ ___
10048 ---> | | | --> | | | | | |
10049 |___|___|----> |___|___|--> |___|___|--> nil
10052 | | --> "yet more text"
10054 | --> "a different piece of text
10063 Both the variable @code{kill-ring} and the variable
10064 @code{kill-ring-yank-pointer} are pointers. But the kill ring itself is
10065 usually described as if it were actually what it is composed of. The
10066 @code{kill-ring} is spoken of as if it were the list rather than that it
10067 points to the list. Conversely, the @code{kill-ring-yank-pointer} is
10068 spoken of as pointing to a list.
10070 These two ways of talking about the same thing sound confusing at first but
10071 make sense on reflection. The kill ring is generally thought of as the
10072 complete structure of data that holds the information of what has recently
10073 been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer}
10074 on the other hand, serves to indicate---that is, to point to---that part
10075 of the kill ring of which the first element (the @sc{car}) will be
10079 In GNU Emacs 22, the @code{kill-new} function calls
10081 @code{(setq kill-ring-yank-pointer kill-ring)}
10083 (defun rotate-yank-pointer (arg)
10084 "Rotate the yanking point in the kill ring.
10085 With argument, rotate that many kills forward (or backward, if negative)."
10087 (current-kill arg))
10089 (defun current-kill (n &optional do-not-move)
10090 "Rotate the yanking point by N places, and then return that kill.
10091 If N is zero, `interprogram-paste-function' is set, and calling it
10092 returns a string, then that string is added to the front of the
10093 kill ring and returned as the latest kill.
10094 If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
10095 yanking point; just return the Nth kill forward."
10096 (let ((interprogram-paste (and (= n 0)
10097 interprogram-paste-function
10098 (funcall interprogram-paste-function))))
10099 (if interprogram-paste
10101 ;; Disable the interprogram cut function when we add the new
10102 ;; text to the kill ring, so Emacs doesn't try to own the
10103 ;; selection, with identical text.
10104 (let ((interprogram-cut-function nil))
10105 (kill-new interprogram-paste))
10106 interprogram-paste)
10107 (or kill-ring (error "Kill ring is empty"))
10108 (let ((ARGth-kill-element
10109 (nthcdr (mod (- n (length kill-ring-yank-pointer))
10110 (length kill-ring))
10113 (setq kill-ring-yank-pointer ARGth-kill-element))
10114 (car ARGth-kill-element)))))
10119 @node yank nthcdr Exercises
10120 @section Exercises with @code{yank} and @code{nthcdr}
10124 Using @kbd{C-h v} (@code{describe-variable}), look at the value of
10125 your kill ring. Add several items to your kill ring; look at its
10126 value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way
10127 around the kill ring. How many items were in your kill ring? Find
10128 the value of @code{kill-ring-max}. Was your kill ring full, or could
10129 you have kept more blocks of text within it?
10132 Using @code{nthcdr} and @code{car}, construct a series of expressions
10133 to return the first, second, third, and fourth elements of a list.
10136 @node Loops & Recursion
10137 @chapter Loops and Recursion
10138 @cindex Loops and recursion
10139 @cindex Recursion and loops
10140 @cindex Repetition (loops)
10142 Emacs Lisp has two primary ways to cause an expression, or a series of
10143 expressions, to be evaluated repeatedly: one uses a @code{while}
10144 loop, and the other uses @dfn{recursion}.
10146 Repetition can be very valuable. For example, to move forward four
10147 sentences, you need only write a program that will move forward one
10148 sentence and then repeat the process four times. Since a computer does
10149 not get bored or tired, such repetitive action does not have the
10150 deleterious effects that excessive or the wrong kinds of repetition can
10153 People mostly write Emacs Lisp functions using @code{while} loops and
10154 their kin; but you can use recursion, which provides a very powerful
10155 way to think about and then to solve problems@footnote{You can write
10156 recursive functions to be frugal or wasteful of mental or computer
10157 resources; as it happens, methods that people find easy---that are
10158 frugal of mental resources---sometimes use considerable computer
10159 resources. Emacs was designed to run on machines that we now consider
10160 limited and its default settings are conservative. You may want to
10161 increase the values of @code{max-specpdl-size} and
10162 @code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to
10163 15 and 30 times their default value.}.
10166 * while:: Causing a stretch of code to repeat.
10168 * Recursion:: Causing a function to call itself.
10169 * Looping exercise::
10173 @section @code{while}
10177 The @code{while} special form tests whether the value returned by
10178 evaluating its first argument is true or false. This is similar to what
10179 the Lisp interpreter does with an @code{if}; what the interpreter does
10180 next, however, is different.
10182 In a @code{while} expression, if the value returned by evaluating the
10183 first argument is false, the Lisp interpreter skips the rest of the
10184 expression (the @dfn{body} of the expression) and does not evaluate it.
10185 However, if the value is true, the Lisp interpreter evaluates the body
10186 of the expression and then again tests whether the first argument to
10187 @code{while} is true or false. If the value returned by evaluating the
10188 first argument is again true, the Lisp interpreter again evaluates the
10189 body of the expression.
10192 The template for a @code{while} expression looks like this:
10196 (while @var{true-or-false-test}
10202 * Looping with while:: Repeat so long as test returns true.
10203 * Loop Example:: A @code{while} loop that uses a list.
10204 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
10205 * Incrementing Loop:: A loop with an incrementing counter.
10206 * Incrementing Loop Details::
10207 * Decrementing Loop:: A loop with a decrementing counter.
10211 @node Looping with while
10212 @unnumberedsubsec Looping with @code{while}
10215 So long as the true-or-false-test of the @code{while} expression
10216 returns a true value when it is evaluated, the body is repeatedly
10217 evaluated. This process is called a loop since the Lisp interpreter
10218 repeats the same thing again and again, like an airplane doing a loop.
10219 When the result of evaluating the true-or-false-test is false, the
10220 Lisp interpreter does not evaluate the rest of the @code{while}
10221 expression and exits the loop.
10223 Clearly, if the value returned by evaluating the first argument to
10224 @code{while} is always true, the body following will be evaluated
10225 again and again @dots{} and again @dots{} forever. Conversely, if the
10226 value returned is never true, the expressions in the body will never
10227 be evaluated. The craft of writing a @code{while} loop consists of
10228 choosing a mechanism such that the true-or-false-test returns true
10229 just the number of times that you want the subsequent expressions to
10230 be evaluated, and then have the test return false.
10232 The value returned by evaluating a @code{while} is the value of the
10233 true-or-false-test. An interesting consequence of this is that a
10234 @code{while} loop that evaluates without error will return @code{nil}
10235 or false regardless of whether it has looped 1 or 100 times or none at
10236 all. A @code{while} expression that evaluates successfully never
10237 returns a true value! What this means is that @code{while} is always
10238 evaluated for its side effects, which is to say, the consequences of
10239 evaluating the expressions within the body of the @code{while} loop.
10240 This makes sense. It is not the mere act of looping that is desired,
10241 but the consequences of what happens when the expressions in the loop
10242 are repeatedly evaluated.
10245 @subsection A @code{while} Loop and a List
10247 A common way to control a @code{while} loop is to test whether a list
10248 has any elements. If it does, the loop is repeated; but if it does not,
10249 the repetition is ended. Since this is an important technique, we will
10250 create a short example to illustrate it.
10252 A simple way to test whether a list has elements is to evaluate the
10253 list: if it has no elements, it is an empty list and will return the
10254 empty list, @code{()}, which is a synonym for @code{nil} or false. On
10255 the other hand, a list with elements will return those elements when it
10256 is evaluated. Since Emacs Lisp considers as true any value that is not
10257 @code{nil}, a list that returns elements will test true in a
10261 For example, you can set the variable @code{empty-list} to @code{nil} by
10262 evaluating the following @code{setq} expression:
10265 (setq empty-list ())
10269 After evaluating the @code{setq} expression, you can evaluate the
10270 variable @code{empty-list} in the usual way, by placing the cursor after
10271 the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your
10278 On the other hand, if you set a variable to be a list with elements, the
10279 list will appear when you evaluate the variable, as you can see by
10280 evaluating the following two expressions:
10284 (setq animals '(gazelle giraffe lion tiger))
10290 Thus, to create a @code{while} loop that tests whether there are any
10291 items in the list @code{animals}, the first part of the loop will be
10302 When the @code{while} tests its first argument, the variable
10303 @code{animals} is evaluated. It returns a list. So long as the list
10304 has elements, the @code{while} considers the results of the test to be
10305 true; but when the list is empty, it considers the results of the test
10308 To prevent the @code{while} loop from running forever, some mechanism
10309 needs to be provided to empty the list eventually. An oft-used
10310 technique is to have one of the subsequent forms in the @code{while}
10311 expression set the value of the list to be the @sc{cdr} of the list.
10312 Each time the @code{cdr} function is evaluated, the list will be made
10313 shorter, until eventually only the empty list will be left. At this
10314 point, the test of the @code{while} loop will return false, and the
10315 arguments to the @code{while} will no longer be evaluated.
10317 For example, the list of animals bound to the variable @code{animals}
10318 can be set to be the @sc{cdr} of the original list with the
10319 following expression:
10322 (setq animals (cdr animals))
10326 If you have evaluated the previous expressions and then evaluate this
10327 expression, you will see @code{(giraffe lion tiger)} appear in the echo
10328 area. If you evaluate the expression again, @code{(lion tiger)} will
10329 appear in the echo area. If you evaluate it again and yet again,
10330 @code{(tiger)} appears and then the empty list, shown by @code{nil}.
10332 A template for a @code{while} loop that uses the @code{cdr} function
10333 repeatedly to cause the true-or-false-test eventually to test false
10338 (while @var{test-whether-list-is-empty}
10340 @var{set-list-to-cdr-of-list})
10344 This test and use of @code{cdr} can be put together in a function that
10345 goes through a list and prints each element of the list on a line of its
10348 @node print-elements-of-list
10349 @subsection An Example: @code{print-elements-of-list}
10350 @findex print-elements-of-list
10352 The @code{print-elements-of-list} function illustrates a @code{while}
10355 @cindex @file{*scratch*} buffer
10356 The function requires several lines for its output. If you are
10357 reading this in a recent instance of GNU Emacs,
10358 @c GNU Emacs 21, GNU Emacs 22, or a later version,
10359 you can evaluate the following expression inside of Info, as usual.
10361 If you are using an earlier version of Emacs, you need to copy the
10362 necessary expressions to your @file{*scratch*} buffer and evaluate
10363 them there. This is because the echo area had only one line in the
10366 You can copy the expressions by marking the beginning of the region
10367 with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to
10368 the end of the region and then copying the region using @kbd{M-w}
10369 (@code{kill-ring-save}, which calls @code{copy-region-as-kill} and
10370 then provides visual feedback). In the @file{*scratch*}
10371 buffer, you can yank the expressions back by typing @kbd{C-y}
10374 After you have copied the expressions to the @file{*scratch*} buffer,
10375 evaluate each expression in turn. Be sure to evaluate the last
10376 expression, @code{(print-elements-of-list animals)}, by typing
10377 @kbd{C-u C-x C-e}, that is, by giving an argument to
10378 @code{eval-last-sexp}. This will cause the result of the evaluation
10379 to be printed in the @file{*scratch*} buffer instead of being printed
10380 in the echo area. (Otherwise you will see something like this in your
10381 echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which
10382 each @samp{^J} stands for a newline.)
10385 In a recent instance of GNU Emacs, you can evaluate these expressions
10386 directly in the Info buffer, and the echo area will grow to show the
10391 (setq animals '(gazelle giraffe lion tiger))
10393 (defun print-elements-of-list (list)
10394 "Print each element of LIST on a line of its own."
10397 (setq list (cdr list))))
10399 (print-elements-of-list animals)
10405 When you evaluate the three expressions in sequence, you will see
10421 Each element of the list is printed on a line of its own (that is what
10422 the function @code{print} does) and then the value returned by the
10423 function is printed. Since the last expression in the function is the
10424 @code{while} loop, and since @code{while} loops always return
10425 @code{nil}, a @code{nil} is printed after the last element of the list.
10427 @node Incrementing Loop
10428 @subsection A Loop with an Incrementing Counter
10430 A loop is not useful unless it stops when it ought. Besides
10431 controlling a loop with a list, a common way of stopping a loop is to
10432 write the first argument as a test that returns false when the correct
10433 number of repetitions are complete. This means that the loop must
10434 have a counter---an expression that counts how many times the loop
10438 @node Incrementing Loop Details
10439 @unnumberedsubsec Details of an Incrementing Loop
10442 The test for a loop with an incrementing counter can be an expression
10443 such as @code{(< count desired-number)} which returns @code{t} for
10444 true if the value of @code{count} is less than the
10445 @code{desired-number} of repetitions and @code{nil} for false if the
10446 value of @code{count} is equal to or is greater than the
10447 @code{desired-number}. The expression that increments the count can
10448 be a simple @code{setq} such as @code{(setq count (1+ count))}, where
10449 @code{1+} is a built-in function in Emacs Lisp that adds 1 to its
10450 argument. (The expression @w{@code{(1+ count)}} has the same result
10451 as @w{@code{(+ count 1)}}, but is easier for a human to read.)
10454 The template for a @code{while} loop controlled by an incrementing
10455 counter looks like this:
10459 @var{set-count-to-initial-value}
10460 (while (< count desired-number) ; @r{true-or-false-test}
10462 (setq count (1+ count))) ; @r{incrementer}
10467 Note that you need to set the initial value of @code{count}; usually it
10471 * Incrementing Example:: Counting pebbles in a triangle.
10472 * Inc Example parts:: The parts of the function definition.
10473 * Inc Example altogether:: Putting the function definition together.
10476 @node Incrementing Example
10477 @unnumberedsubsubsec Example with incrementing counter
10479 Suppose you are playing on the beach and decide to make a triangle of
10480 pebbles, putting one pebble in the first row, two in the second row,
10481 three in the third row and so on, like this:
10499 @bullet{} @bullet{}
10500 @bullet{} @bullet{} @bullet{}
10501 @bullet{} @bullet{} @bullet{} @bullet{}
10508 (About 2500 years ago, Pythagoras and others developed the beginnings of
10509 number theory by considering questions such as this.)
10511 Suppose you want to know how many pebbles you will need to make a
10512 triangle with 7 rows?
10514 Clearly, what you need to do is add up the numbers from 1 to 7. There
10515 are two ways to do this; start with the smallest number, one, and add up
10516 the list in sequence, 1, 2, 3, 4 and so on; or start with the largest
10517 number and add the list going down: 7, 6, 5, 4 and so on. Because both
10518 mechanisms illustrate common ways of writing @code{while} loops, we will
10519 create two examples, one counting up and the other counting down. In
10520 this first example, we will start with 1 and add 2, 3, 4 and so on.
10522 If you are just adding up a short list of numbers, the easiest way to do
10523 it is to add up all the numbers at once. However, if you do not know
10524 ahead of time how many numbers your list will have, or if you want to be
10525 prepared for a very long list, then you need to design your addition so
10526 that what you do is repeat a simple process many times instead of doing
10527 a more complex process once.
10529 For example, instead of adding up all the pebbles all at once, what you
10530 can do is add the number of pebbles in the first row, 1, to the number
10531 in the second row, 2, and then add the total of those two rows to the
10532 third row, 3. Then you can add the number in the fourth row, 4, to the
10533 total of the first three rows; and so on.
10535 The critical characteristic of the process is that each repetitive
10536 action is simple. In this case, at each step we add only two numbers,
10537 the number of pebbles in the row and the total already found. This
10538 process of adding two numbers is repeated again and again until the last
10539 row has been added to the total of all the preceding rows. In a more
10540 complex loop the repetitive action might not be so simple, but it will
10541 be simpler than doing everything all at once.
10543 @node Inc Example parts
10544 @unnumberedsubsubsec The parts of the function definition
10546 The preceding analysis gives us the bones of our function definition:
10547 first, we will need a variable that we can call @code{total} that will
10548 be the total number of pebbles. This will be the value returned by
10551 Second, we know that the function will require an argument: this
10552 argument will be the total number of rows in the triangle. It can be
10553 called @code{number-of-rows}.
10555 Finally, we need a variable to use as a counter. We could call this
10556 variable @code{counter}, but a better name is @code{row-number}. That
10557 is because what the counter does in this function is count rows, and a
10558 program should be written to be as understandable as possible.
10560 When the Lisp interpreter first starts evaluating the expressions in the
10561 function, the value of @code{total} should be set to zero, since we have
10562 not added anything to it. Then the function should add the number of
10563 pebbles in the first row to the total, and then add the number of
10564 pebbles in the second to the total, and then add the number of
10565 pebbles in the third row to the total, and so on, until there are no
10566 more rows left to add.
10568 Both @code{total} and @code{row-number} are used only inside the
10569 function, so they can be declared as local variables with @code{let}
10570 and given initial values. Clearly, the initial value for @code{total}
10571 should be 0. The initial value of @code{row-number} should be 1,
10572 since we start with the first row. This means that the @code{let}
10573 statement will look like this:
10583 After the internal variables are declared and bound to their initial
10584 values, we can begin the @code{while} loop. The expression that serves
10585 as the test should return a value of @code{t} for true so long as the
10586 @code{row-number} is less than or equal to the @code{number-of-rows}.
10587 (If the expression tests true only so long as the row number is less
10588 than the number of rows in the triangle, the last row will never be
10589 added to the total; hence the row number has to be either less than or
10590 equal to the number of rows.)
10593 @findex <= @r{(less than or equal)}
10594 Lisp provides the @code{<=} function that returns true if the value of
10595 its first argument is less than or equal to the value of its second
10596 argument and false otherwise. So the expression that the @code{while}
10597 will evaluate as its test should look like this:
10600 (<= row-number number-of-rows)
10603 The total number of pebbles can be found by repeatedly adding the number
10604 of pebbles in a row to the total already found. Since the number of
10605 pebbles in the row is equal to the row number, the total can be found by
10606 adding the row number to the total. (Clearly, in a more complex
10607 situation, the number of pebbles in the row might be related to the row
10608 number in a more complicated way; if this were the case, the row number
10609 would be replaced by the appropriate expression.)
10612 (setq total (+ total row-number))
10616 What this does is set the new value of @code{total} to be equal to the
10617 sum of adding the number of pebbles in the row to the previous total.
10619 After setting the value of @code{total}, the conditions need to be
10620 established for the next repetition of the loop, if there is one. This
10621 is done by incrementing the value of the @code{row-number} variable,
10622 which serves as a counter. After the @code{row-number} variable has
10623 been incremented, the true-or-false-test at the beginning of the
10624 @code{while} loop tests whether its value is still less than or equal to
10625 the value of the @code{number-of-rows} and if it is, adds the new value
10626 of the @code{row-number} variable to the @code{total} of the previous
10627 repetition of the loop.
10630 The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the
10631 @code{row-number} variable can be incremented with this expression:
10634 (setq row-number (1+ row-number))
10637 @node Inc Example altogether
10638 @unnumberedsubsubsec Putting the function definition together
10640 We have created the parts for the function definition; now we need to
10644 First, the contents of the @code{while} expression:
10648 (while (<= row-number number-of-rows) ; @r{true-or-false-test}
10649 (setq total (+ total row-number))
10650 (setq row-number (1+ row-number))) ; @r{incrementer}
10654 Along with the @code{let} expression varlist, this very nearly
10655 completes the body of the function definition. However, it requires
10656 one final element, the need for which is somewhat subtle.
10658 The final touch is to place the variable @code{total} on a line by
10659 itself after the @code{while} expression. Otherwise, the value returned
10660 by the whole function is the value of the last expression that is
10661 evaluated in the body of the @code{let}, and this is the value
10662 returned by the @code{while}, which is always @code{nil}.
10664 This may not be evident at first sight. It almost looks as if the
10665 incrementing expression is the last expression of the whole function.
10666 But that expression is part of the body of the @code{while}; it is the
10667 last element of the list that starts with the symbol @code{while}.
10668 Moreover, the whole of the @code{while} loop is a list within the body
10672 In outline, the function will look like this:
10676 (defun @var{name-of-function} (@var{argument-list})
10677 "@var{documentation}@dots{}"
10678 (let (@var{varlist})
10679 (while (@var{true-or-false-test})
10680 @var{body-of-while}@dots{} )
10681 @dots{} )) ; @r{Need final expression here.}
10685 The result of evaluating the @code{let} is what is going to be returned
10686 by the @code{defun} since the @code{let} is not embedded within any
10687 containing list, except for the @code{defun} as a whole. However, if
10688 the @code{while} is the last element of the @code{let} expression, the
10689 function will always return @code{nil}. This is not what we want!
10690 Instead, what we want is the value of the variable @code{total}. This
10691 is returned by simply placing the symbol as the last element of the list
10692 starting with @code{let}. It gets evaluated after the preceding
10693 elements of the list are evaluated, which means it gets evaluated after
10694 it has been assigned the correct value for the total.
10696 It may be easier to see this by printing the list starting with
10697 @code{let} all on one line. This format makes it evident that the
10698 @var{varlist} and @code{while} expressions are the second and third
10699 elements of the list starting with @code{let}, and the @code{total} is
10704 (let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total)
10709 Putting everything together, the @code{triangle} function definition
10714 (defun triangle (number-of-rows) ; @r{Version with}
10715 ; @r{ incrementing counter.}
10716 "Add up the number of pebbles in a triangle.
10717 The first row has one pebble, the second row two pebbles,
10718 the third row three pebbles, and so on.
10719 The argument is NUMBER-OF-ROWS."
10724 (while (<= row-number number-of-rows)
10725 (setq total (+ total row-number))
10726 (setq row-number (1+ row-number)))
10732 After you have installed @code{triangle} by evaluating the function, you
10733 can try it out. Here are two examples:
10744 The sum of the first four numbers is 10 and the sum of the first seven
10747 @node Decrementing Loop
10748 @subsection Loop with a Decrementing Counter
10750 Another common way to write a @code{while} loop is to write the test
10751 so that it determines whether a counter is greater than zero. So long
10752 as the counter is greater than zero, the loop is repeated. But when
10753 the counter is equal to or less than zero, the loop is stopped. For
10754 this to work, the counter has to start out greater than zero and then
10755 be made smaller and smaller by a form that is evaluated
10758 The test will be an expression such as @code{(> counter 0)} which
10759 returns @code{t} for true if the value of @code{counter} is greater
10760 than zero, and @code{nil} for false if the value of @code{counter} is
10761 equal to or less than zero. The expression that makes the number
10762 smaller and smaller can be a simple @code{setq} such as @code{(setq
10763 counter (1- counter))}, where @code{1-} is a built-in function in
10764 Emacs Lisp that subtracts 1 from its argument.
10767 The template for a decrementing @code{while} loop looks like this:
10771 (while (> counter 0) ; @r{true-or-false-test}
10773 (setq counter (1- counter))) ; @r{decrementer}
10778 * Decrementing Example:: More pebbles on the beach.
10779 * Dec Example parts:: The parts of the function definition.
10780 * Dec Example altogether:: Putting the function definition together.
10783 @node Decrementing Example
10784 @unnumberedsubsubsec Example with decrementing counter
10786 To illustrate a loop with a decrementing counter, we will rewrite the
10787 @code{triangle} function so the counter decreases to zero.
10789 This is the reverse of the earlier version of the function. In this
10790 case, to find out how many pebbles are needed to make a triangle with
10791 3 rows, add the number of pebbles in the third row, 3, to the number
10792 in the preceding row, 2, and then add the total of those two rows to
10793 the row that precedes them, which is 1.
10795 Likewise, to find the number of pebbles in a triangle with 7 rows, add
10796 the number of pebbles in the seventh row, 7, to the number in the
10797 preceding row, which is 6, and then add the total of those two rows to
10798 the row that precedes them, which is 5, and so on. As in the previous
10799 example, each addition only involves adding two numbers, the total of
10800 the rows already added up and the number of pebbles in the row that is
10801 being added to the total. This process of adding two numbers is
10802 repeated again and again until there are no more pebbles to add.
10804 We know how many pebbles to start with: the number of pebbles in the
10805 last row is equal to the number of rows. If the triangle has seven
10806 rows, the number of pebbles in the last row is 7. Likewise, we know how
10807 many pebbles are in the preceding row: it is one less than the number in
10810 @node Dec Example parts
10811 @unnumberedsubsubsec The parts of the function definition
10813 We start with three variables: the total number of rows in the
10814 triangle; the number of pebbles in a row; and the total number of
10815 pebbles, which is what we want to calculate. These variables can be
10816 named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and
10817 @code{total}, respectively.
10819 Both @code{total} and @code{number-of-pebbles-in-row} are used only
10820 inside the function and are declared with @code{let}. The initial
10821 value of @code{total} should, of course, be zero. However, the
10822 initial value of @code{number-of-pebbles-in-row} should be equal to
10823 the number of rows in the triangle, since the addition will start with
10827 This means that the beginning of the @code{let} expression will look
10833 (number-of-pebbles-in-row number-of-rows))
10838 The total number of pebbles can be found by repeatedly adding the number
10839 of pebbles in a row to the total already found, that is, by repeatedly
10840 evaluating the following expression:
10843 (setq total (+ total number-of-pebbles-in-row))
10847 After the @code{number-of-pebbles-in-row} is added to the @code{total},
10848 the @code{number-of-pebbles-in-row} should be decremented by one, since
10849 the next time the loop repeats, the preceding row will be
10850 added to the total.
10852 The number of pebbles in a preceding row is one less than the number of
10853 pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be
10854 used to compute the number of pebbles in the preceding row. This can be
10855 done with the following expression:
10859 (setq number-of-pebbles-in-row
10860 (1- number-of-pebbles-in-row))
10864 Finally, we know that the @code{while} loop should stop making repeated
10865 additions when there are no pebbles in a row. So the test for
10866 the @code{while} loop is simply:
10869 (while (> number-of-pebbles-in-row 0)
10872 @node Dec Example altogether
10873 @unnumberedsubsubsec Putting the function definition together
10875 We can put these expressions together to create a function definition
10876 that works. However, on examination, we find that one of the local
10877 variables is unneeded!
10880 The function definition looks like this:
10884 ;;; @r{First subtractive version.}
10885 (defun triangle (number-of-rows)
10886 "Add up the number of pebbles in a triangle."
10888 (number-of-pebbles-in-row number-of-rows))
10889 (while (> number-of-pebbles-in-row 0)
10890 (setq total (+ total number-of-pebbles-in-row))
10891 (setq number-of-pebbles-in-row
10892 (1- number-of-pebbles-in-row)))
10897 As written, this function works.
10899 However, we do not need @code{number-of-pebbles-in-row}.
10901 @cindex Argument as local variable
10902 When the @code{triangle} function is evaluated, the symbol
10903 @code{number-of-rows} will be bound to a number, giving it an initial
10904 value. That number can be changed in the body of the function as if
10905 it were a local variable, without any fear that such a change will
10906 effect the value of the variable outside of the function. This is a
10907 very useful characteristic of Lisp; it means that the variable
10908 @code{number-of-rows} can be used anywhere in the function where
10909 @code{number-of-pebbles-in-row} is used.
10912 Here is a second version of the function written a bit more cleanly:
10916 (defun triangle (number) ; @r{Second version.}
10917 "Return sum of numbers 1 through NUMBER inclusive."
10919 (while (> number 0)
10920 (setq total (+ total number))
10921 (setq number (1- number)))
10926 In brief, a properly written @code{while} loop will consist of three parts:
10930 A test that will return false after the loop has repeated itself the
10931 correct number of times.
10934 An expression the evaluation of which will return the value desired
10935 after being repeatedly evaluated.
10938 An expression to change the value passed to the true-or-false-test so
10939 that the test returns false after the loop has repeated itself the right
10943 @node dolist dotimes
10944 @section Save your time: @code{dolist} and @code{dotimes}
10946 In addition to @code{while}, both @code{dolist} and @code{dotimes}
10947 provide for looping. Sometimes these are quicker to write than the
10948 equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, ,
10949 Macros, elisp, The GNU Emacs Lisp Reference Manual}. )
10951 @code{dolist} works like a @code{while} loop that @sc{cdr}s down a
10952 list: @code{dolist} automatically shortens the list each time it
10953 loops---takes the @sc{cdr} of the list---and binds the @sc{car} of
10954 each shorter version of the list to the first of its arguments.
10956 @code{dotimes} loops a specific number of times: you specify the number.
10964 @unnumberedsubsec The @code{dolist} Macro
10967 Suppose, for example, you want to reverse a list, so that
10968 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''.
10971 In practice, you would use the @code{reverse} function, like this:
10975 (setq animals '(gazelle giraffe lion tiger))
10983 Here is how you could reverse the list using a @code{while} loop:
10987 (setq animals '(gazelle giraffe lion tiger))
10989 (defun reverse-list-with-while (list)
10990 "Using while, reverse the order of LIST."
10991 (let (value) ; make sure list starts empty
10993 (setq value (cons (car list) value))
10994 (setq list (cdr list)))
10997 (reverse-list-with-while animals)
11003 And here is how you could use the @code{dolist} macro:
11007 (setq animals '(gazelle giraffe lion tiger))
11009 (defun reverse-list-with-dolist (list)
11010 "Using dolist, reverse the order of LIST."
11011 (let (value) ; make sure list starts empty
11012 (dolist (element list value)
11013 (setq value (cons element value)))))
11015 (reverse-list-with-dolist animals)
11021 In Info, you can place your cursor after the closing parenthesis of
11022 each expression and type @kbd{C-x C-e}; in each case, you should see
11025 (tiger lion giraffe gazelle)
11031 For this example, the existing @code{reverse} function is obviously best.
11032 The @code{while} loop is just like our first example (@pxref{Loop
11033 Example, , A @code{while} Loop and a List}). The @code{while} first
11034 checks whether the list has elements; if so, it constructs a new list
11035 by adding the first element of the list to the existing list (which in
11036 the first iteration of the loop is @code{nil}). Since the second
11037 element is prepended in front of the first element, and the third
11038 element is prepended in front of the second element, the list is reversed.
11040 In the expression using a @code{while} loop,
11041 the @w{@code{(setq list (cdr list))}}
11042 expression shortens the list, so the @code{while} loop eventually
11043 stops. In addition, it provides the @code{cons} expression with a new
11044 first element by creating a new and shorter list at each repetition of
11047 The @code{dolist} expression does very much the same as the
11048 @code{while} expression, except that the @code{dolist} macro does some
11049 of the work you have to do when writing a @code{while} expression.
11051 Like a @code{while} loop, a @code{dolist} loops. What is different is
11052 that it automatically shortens the list each time it loops---it
11053 @sc{cdr}s down the list on its own---and it automatically binds
11054 the @sc{car} of each shorter version of the list to the first of its
11057 In the example, the @sc{car} of each shorter version of the list is
11058 referred to using the symbol @samp{element}, the list itself is called
11059 @samp{list}, and the value returned is called @samp{value}. The
11060 remainder of the @code{dolist} expression is the body.
11062 The @code{dolist} expression binds the @sc{car} of each shorter
11063 version of the list to @code{element} and then evaluates the body of
11064 the expression; and repeats the loop. The result is returned in
11068 @unnumberedsubsec The @code{dotimes} Macro
11071 The @code{dotimes} macro is similar to @code{dolist}, except that it
11072 loops a specific number of times.
11074 The first argument to @code{dotimes} is assigned the numbers 0, 1, 2
11075 and so forth each time around the loop, and the value of the third
11076 argument is returned. You need to provide the value of the second
11077 argument, which is how many times the macro loops.
11080 For example, the following binds the numbers from 0 up to, but not
11081 including, the number 3 to the first argument, @var{number}, and then
11082 constructs a list of the three numbers. (The first number is 0, the
11083 second number is 1, and the third number is 2; this makes a total of
11084 three numbers in all, starting with zero as the first number.)
11088 (let (value) ; otherwise a value is a void variable
11089 (dotimes (number 3 value)
11090 (setq value (cons number value))))
11097 @code{dotimes} returns @code{value}, so the way to use
11098 @code{dotimes} is to operate on some expression @var{number} number of
11099 times and then return the result, either as a list or an atom.
11102 Here is an example of a @code{defun} that uses @code{dotimes} to add
11103 up the number of pebbles in a triangle.
11107 (defun triangle-using-dotimes (number-of-rows)
11108 "Using `dotimes', add up the number of pebbles in a triangle."
11109 (let ((total 0)) ; otherwise a total is a void variable
11110 (dotimes (number number-of-rows total)
11111 (setq total (+ total (1+ number))))))
11113 (triangle-using-dotimes 4)
11121 A recursive function contains code that tells the Lisp interpreter to
11122 call a program that runs exactly like itself, but with slightly
11123 different arguments. The code runs exactly the same because it has
11124 the same name. However, even though the program has the same name, it
11125 is not the same entity. It is different. In the jargon, it is a
11126 different ``instance''.
11128 Eventually, if the program is written correctly, the slightly
11129 different arguments will become sufficiently different from the first
11130 arguments that the final instance will stop.
11133 * Building Robots:: Same model, different serial number ...
11134 * Recursive Definition Parts:: Walk until you stop ...
11135 * Recursion with list:: Using a list as the test whether to recurse.
11136 * Recursive triangle function::
11137 * Recursion with cond::
11138 * Recursive Patterns:: Often used templates.
11139 * No Deferment:: Don't store up work ...
11140 * No deferment solution::
11143 @node Building Robots
11144 @subsection Building Robots: Extending the Metaphor
11145 @cindex Building robots
11146 @cindex Robots, building
11148 It is sometimes helpful to think of a running program as a robot that
11149 does a job. In doing its job, a recursive function calls on a second
11150 robot to help it. The second robot is identical to the first in every
11151 way, except that the second robot helps the first and has been
11152 passed different arguments than the first.
11154 In a recursive function, the second robot may call a third; and the
11155 third may call a fourth, and so on. Each of these is a different
11156 entity; but all are clones.
11158 Since each robot has slightly different instructions---the arguments
11159 will differ from one robot to the next---the last robot should know
11162 Let's expand on the metaphor in which a computer program is a robot.
11164 A function definition provides the blueprints for a robot. When you
11165 install a function definition, that is, when you evaluate a
11166 @code{defun} macro, you install the necessary equipment to build
11167 robots. It is as if you were in a factory, setting up an assembly
11168 line. Robots with the same name are built according to the same
11169 blueprints. So they have the same model number, but a
11170 different serial number.
11172 We often say that a recursive function ``calls itself''. What we mean
11173 is that the instructions in a recursive function cause the Lisp
11174 interpreter to run a different function that has the same name and
11175 does the same job as the first, but with different arguments.
11177 It is important that the arguments differ from one instance to the
11178 next; otherwise, the process will never stop.
11180 @node Recursive Definition Parts
11181 @subsection The Parts of a Recursive Definition
11182 @cindex Parts of a Recursive Definition
11183 @cindex Recursive Definition Parts
11185 A recursive function typically contains a conditional expression which
11190 A true-or-false-test that determines whether the function is called
11191 again, here called the @dfn{do-again-test}.
11194 The name of the function. When this name is called, a new instance of
11195 the function---a new robot, as it were---is created and told what to do.
11198 An expression that returns a different value each time the function is
11199 called, here called the @dfn{next-step-expression}. Consequently, the
11200 argument (or arguments) passed to the new instance of the function
11201 will be different from that passed to the previous instance. This
11202 causes the conditional expression, the @dfn{do-again-test}, to test
11203 false after the correct number of repetitions.
11206 Recursive functions can be much simpler than any other kind of
11207 function. Indeed, when people first start to use them, they often look
11208 so mysteriously simple as to be incomprehensible. Like riding a
11209 bicycle, reading a recursive function definition takes a certain knack
11210 which is hard at first but then seems simple.
11213 There are several different common recursive patterns. A very simple
11214 pattern looks like this:
11218 (defun @var{name-of-recursive-function} (@var{argument-list})
11219 "@var{documentation}@dots{}"
11220 (if @var{do-again-test}
11222 (@var{name-of-recursive-function}
11223 @var{next-step-expression})))
11227 Each time a recursive function is evaluated, a new instance of it is
11228 created and told what to do. The arguments tell the instance what to do.
11230 An argument is bound to the value of the next-step-expression. Each
11231 instance runs with a different value of the next-step-expression.
11233 The value in the next-step-expression is used in the do-again-test.
11235 The value returned by the next-step-expression is passed to the new
11236 instance of the function, which evaluates it (or some
11237 transmogrification of it) to determine whether to continue or stop.
11238 The next-step-expression is designed so that the do-again-test returns
11239 false when the function should no longer be repeated.
11241 The do-again-test is sometimes called the @dfn{stop condition},
11242 since it stops the repetitions when it tests false.
11244 @node Recursion with list
11245 @subsection Recursion with a List
11247 The example of a @code{while} loop that printed the elements of a list
11248 of numbers can be written recursively. Here is the code, including
11249 an expression to set the value of the variable @code{animals} to a list.
11251 If you are reading this in Info in Emacs, you can evaluate this
11252 expression directly in Info. Otherwise, you must copy the example
11253 to the @file{*scratch*} buffer and evaluate each expression there.
11254 Use @kbd{C-u C-x C-e} to evaluate the
11255 @code{(print-elements-recursively animals)} expression so that the
11256 results are printed in the buffer; otherwise the Lisp interpreter will
11257 try to squeeze the results into the one line of the echo area.
11259 Also, place your cursor immediately after the last closing parenthesis
11260 of the @code{print-elements-recursively} function, before the comment.
11261 Otherwise, the Lisp interpreter will try to evaluate the comment.
11263 @findex print-elements-recursively
11266 (setq animals '(gazelle giraffe lion tiger))
11268 (defun print-elements-recursively (list)
11269 "Print each element of LIST on a line of its own.
11271 (when list ; @r{do-again-test}
11272 (print (car list)) ; @r{body}
11273 (print-elements-recursively ; @r{recursive call}
11274 (cdr list)))) ; @r{next-step-expression}
11276 (print-elements-recursively animals)
11280 The @code{print-elements-recursively} function first tests whether
11281 there is any content in the list; if there is, the function prints the
11282 first element of the list, the @sc{car} of the list. Then the
11283 function invokes itself, but gives itself as its argument, not the
11284 whole list, but the second and subsequent elements of the list, the
11285 @sc{cdr} of the list.
11287 Put another way, if the list is not empty, the function invokes
11288 another instance of code that is similar to the initial code, but is a
11289 different thread of execution, with different arguments than the first
11292 Put in yet another way, if the list is not empty, the first robot
11293 assembles a second robot and tells it what to do; the second robot is
11294 a different individual from the first, but is the same model.
11296 When the second evaluation occurs, the @code{when} expression is
11297 evaluated and if true, prints the first element of the list it
11298 receives as its argument (which is the second element of the original
11299 list). Then the function calls itself with the @sc{cdr} of the list
11300 it is invoked with, which (the second time around) is the @sc{cdr} of
11301 the @sc{cdr} of the original list.
11303 Note that although we say that the function ``calls itself'', what we
11304 mean is that the Lisp interpreter assembles and instructs a new
11305 instance of the program. The new instance is a clone of the first,
11306 but is a separate individual.
11308 Each time the function invokes itself, it does so on a
11309 shorter version of the original list. It creates a new instance that
11310 works on a shorter list.
11312 Eventually, the function invokes itself on an empty list. It creates
11313 a new instance whose argument is @code{nil}. The conditional expression
11314 tests the value of @code{list}. Since the value of @code{list} is
11315 @code{nil}, the @code{when} expression tests false so the then-part is
11316 not evaluated. The function as a whole then returns @code{nil}.
11319 When you evaluate the expression @code{(print-elements-recursively
11320 animals)} in the @file{*scratch*} buffer, you see this result:
11336 @node Recursive triangle function
11337 @subsection Recursion in Place of a Counter
11338 @findex triangle-recursively
11341 The @code{triangle} function described in a previous section can also
11342 be written recursively. It looks like this:
11346 (defun triangle-recursively (number)
11347 "Return the sum of the numbers 1 through NUMBER inclusive.
11349 (if (= number 1) ; @r{do-again-test}
11351 (+ number ; @r{else-part}
11352 (triangle-recursively ; @r{recursive call}
11353 (1- number))))) ; @r{next-step-expression}
11355 (triangle-recursively 7)
11360 You can install this function by evaluating it and then try it by
11361 evaluating @code{(triangle-recursively 7)}. (Remember to put your
11362 cursor immediately after the last parenthesis of the function
11363 definition, before the comment.) The function evaluates to 28.
11365 To understand how this function works, let's consider what happens in the
11366 various cases when the function is passed 1, 2, 3, or 4 as the value of
11370 * Recursive Example arg of 1 or 2::
11371 * Recursive Example arg of 3 or 4::
11375 @node Recursive Example arg of 1 or 2
11376 @unnumberedsubsubsec An argument of 1 or 2
11379 First, what happens if the value of the argument is 1?
11381 The function has an @code{if} expression after the documentation
11382 string. It tests whether the value of @code{number} is equal to 1; if
11383 so, Emacs evaluates the then-part of the @code{if} expression, which
11384 returns the number 1 as the value of the function. (A triangle with
11385 one row has one pebble in it.)
11387 Suppose, however, that the value of the argument is 2. In this case,
11388 Emacs evaluates the else-part of the @code{if} expression.
11391 The else-part consists of an addition, the recursive call to
11392 @code{triangle-recursively} and a decrementing action; and it looks like
11396 (+ number (triangle-recursively (1- number)))
11399 When Emacs evaluates this expression, the innermost expression is
11400 evaluated first; then the other parts in sequence. Here are the steps
11404 @item Step 1 @w{ } Evaluate the innermost expression.
11406 The innermost expression is @code{(1- number)} so Emacs decrements the
11407 value of @code{number} from 2 to 1.
11409 @item Step 2 @w{ } Evaluate the @code{triangle-recursively} function.
11411 The Lisp interpreter creates an individual instance of
11412 @code{triangle-recursively}. It does not matter that this function is
11413 contained within itself. Emacs passes the result Step 1 as the
11414 argument used by this instance of the @code{triangle-recursively}
11417 In this case, Emacs evaluates @code{triangle-recursively} with an
11418 argument of 1. This means that this evaluation of
11419 @code{triangle-recursively} returns 1.
11421 @item Step 3 @w{ } Evaluate the value of @code{number}.
11423 The variable @code{number} is the second element of the list that
11424 starts with @code{+}; its value is 2.
11426 @item Step 4 @w{ } Evaluate the @code{+} expression.
11428 The @code{+} expression receives two arguments, the first
11429 from the evaluation of @code{number} (Step 3) and the second from the
11430 evaluation of @code{triangle-recursively} (Step 2).
11432 The result of the addition is the sum of 2 plus 1, and the number 3 is
11433 returned, which is correct. A triangle with two rows has three
11437 @node Recursive Example arg of 3 or 4
11438 @unnumberedsubsubsec An argument of 3 or 4
11440 Suppose that @code{triangle-recursively} is called with an argument of
11444 @item Step 1 @w{ } Evaluate the do-again-test.
11446 The @code{if} expression is evaluated first. This is the do-again
11447 test and returns false, so the else-part of the @code{if} expression
11448 is evaluated. (Note that in this example, the do-again-test causes
11449 the function to call itself when it tests false, not when it tests
11452 @item Step 2 @w{ } Evaluate the innermost expression of the else-part.
11454 The innermost expression of the else-part is evaluated, which decrements
11455 3 to 2. This is the next-step-expression.
11457 @item Step 3 @w{ } Evaluate the @code{triangle-recursively} function.
11459 The number 2 is passed to the @code{triangle-recursively} function.
11461 We already know what happens when Emacs evaluates @code{triangle-recursively} with
11462 an argument of 2. After going through the sequence of actions described
11463 earlier, it returns a value of 3. So that is what will happen here.
11465 @item Step 4 @w{ } Evaluate the addition.
11467 3 will be passed as an argument to the addition and will be added to the
11468 number with which the function was called, which is 3.
11472 The value returned by the function as a whole will be 6.
11474 Now that we know what will happen when @code{triangle-recursively} is
11475 called with an argument of 3, it is evident what will happen if it is
11476 called with an argument of 4:
11480 In the recursive call, the evaluation of
11483 (triangle-recursively (1- 4))
11488 will return the value of evaluating
11491 (triangle-recursively 3)
11495 which is 6 and this value will be added to 4 by the addition in the
11500 The value returned by the function as a whole will be 10.
11502 Each time @code{triangle-recursively} is evaluated, it evaluates a
11503 version of itself---a different instance of itself---with a smaller
11504 argument, until the argument is small enough so that it does not
11507 Note that this particular design for a recursive function
11508 requires that operations be deferred.
11510 Before @code{(triangle-recursively 7)} can calculate its answer, it
11511 must call @code{(triangle-recursively 6)}; and before
11512 @code{(triangle-recursively 6)} can calculate its answer, it must call
11513 @code{(triangle-recursively 5)}; and so on. That is to say, the
11514 calculation that @code{(triangle-recursively 7)} makes must be
11515 deferred until @code{(triangle-recursively 6)} makes its calculation;
11516 and @code{(triangle-recursively 6)} must defer until
11517 @code{(triangle-recursively 5)} completes; and so on.
11519 If each of these instances of @code{triangle-recursively} are thought
11520 of as different robots, the first robot must wait for the second to
11521 complete its job, which must wait until the third completes, and so
11524 There is a way around this kind of waiting, which we will discuss in
11525 @ref{No Deferment, , Recursion without Deferments}.
11527 @node Recursion with cond
11528 @subsection Recursion Example Using @code{cond}
11531 The version of @code{triangle-recursively} described earlier is written
11532 with the @code{if} special form. It can also be written using another
11533 special form called @code{cond}. The name of the special form
11534 @code{cond} is an abbreviation of the word @samp{conditional}.
11536 Although the @code{cond} special form is not used as often in the
11537 Emacs Lisp sources as @code{if}, it is used often enough to justify
11541 The template for a @code{cond} expression looks like this:
11551 where the @var{body} is a series of lists.
11554 Written out more fully, the template looks like this:
11559 (@var{first-true-or-false-test} @var{first-consequent})
11560 (@var{second-true-or-false-test} @var{second-consequent})
11561 (@var{third-true-or-false-test} @var{third-consequent})
11566 When the Lisp interpreter evaluates the @code{cond} expression, it
11567 evaluates the first element (the @sc{car} or true-or-false-test) of
11568 the first expression in a series of expressions within the body of the
11571 If the true-or-false-test returns @code{nil} the rest of that
11572 expression, the consequent, is skipped and the true-or-false-test of the
11573 next expression is evaluated. When an expression is found whose
11574 true-or-false-test returns a value that is not @code{nil}, the
11575 consequent of that expression is evaluated. The consequent can be one
11576 or more expressions. If the consequent consists of more than one
11577 expression, the expressions are evaluated in sequence and the value of
11578 the last one is returned. If the expression does not have a consequent,
11579 the value of the true-or-false-test is returned.
11581 If none of the true-or-false-tests test true, the @code{cond} expression
11582 returns @code{nil}.
11585 Written using @code{cond}, the @code{triangle} function looks like this:
11589 (defun triangle-using-cond (number)
11590 (cond ((<= number 0) 0)
11593 (+ number (triangle-using-cond (1- number))))))
11598 In this example, the @code{cond} returns 0 if the number is less than or
11599 equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+
11600 number (triangle-using-cond (1- number)))} if the number is greater than
11603 @node Recursive Patterns
11604 @subsection Recursive Patterns
11605 @cindex Recursive Patterns
11607 Here are three common recursive patterns. Each involves a list.
11608 Recursion does not need to involve lists, but Lisp is designed for lists
11609 and this provides a sense of its primal capabilities.
11618 @unnumberedsubsubsec Recursive Pattern: @emph{every}
11619 @cindex Every, type of recursive pattern
11620 @cindex Recursive pattern - every
11622 In the @code{every} recursive pattern, an action is performed on every
11626 The basic pattern is:
11630 If a list be empty, return @code{nil}.
11632 Else, act on the beginning of the list (the @sc{car} of the list)
11635 through a recursive call by the function on the rest (the
11636 @sc{cdr}) of the list,
11638 and, optionally, combine the acted-on element, using @code{cons},
11639 with the results of acting on the rest.
11648 (defun square-each (numbers-list)
11649 "Square each of a NUMBERS LIST, recursively."
11650 (if (not numbers-list) ; do-again-test
11653 (* (car numbers-list) (car numbers-list))
11654 (square-each (cdr numbers-list))))) ; next-step-expression
11658 (square-each '(1 2 3))
11665 If @code{numbers-list} is empty, do nothing. But if it has content,
11666 construct a list combining the square of the first number in the list
11667 with the result of the recursive call.
11669 (The example follows the pattern exactly: @code{nil} is returned if
11670 the numbers' list is empty. In practice, you would write the
11671 conditional so it carries out the action when the numbers' list is not
11674 The @code{print-elements-recursively} function (@pxref{Recursion with
11675 list, , Recursion with a List}) is another example of an @code{every}
11676 pattern, except in this case, rather than bring the results together
11677 using @code{cons}, we print each element of output.
11680 The @code{print-elements-recursively} function looks like this:
11684 (setq animals '(gazelle giraffe lion tiger))
11688 (defun print-elements-recursively (list)
11689 "Print each element of LIST on a line of its own.
11691 (when list ; @r{do-again-test}
11692 (print (car list)) ; @r{body}
11693 (print-elements-recursively ; @r{recursive call}
11694 (cdr list)))) ; @r{next-step-expression}
11696 (print-elements-recursively animals)
11701 The pattern for @code{print-elements-recursively} is:
11705 When the list is empty, do nothing.
11707 But when the list has at least one element,
11710 act on the beginning of the list (the @sc{car} of the list),
11712 and make a recursive call on the rest (the @sc{cdr}) of the list.
11717 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
11718 @cindex Accumulate, type of recursive pattern
11719 @cindex Recursive pattern - accumulate
11721 Another recursive pattern is called the @code{accumulate} pattern. In
11722 the @code{accumulate} recursive pattern, an action is performed on
11723 every element of a list and the result of that action is accumulated
11724 with the results of performing the action on the other elements.
11726 This is very like the @code{every} pattern using @code{cons}, except that
11727 @code{cons} is not used, but some other combiner.
11734 If a list be empty, return zero or some other constant.
11736 Else, act on the beginning of the list (the @sc{car} of the list),
11739 and combine that acted-on element, using @code{+} or
11740 some other combining function, with
11742 a recursive call by the function on the rest (the @sc{cdr}) of the list.
11747 Here is an example:
11751 (defun add-elements (numbers-list)
11752 "Add the elements of NUMBERS-LIST together."
11753 (if (not numbers-list)
11755 (+ (car numbers-list) (add-elements (cdr numbers-list)))))
11759 (add-elements '(1 2 3 4))
11764 @xref{Files List, , Making a List of Files}, for an example of the
11765 accumulate pattern.
11768 @unnumberedsubsubsec Recursive Pattern: @emph{keep}
11769 @cindex Keep, type of recursive pattern
11770 @cindex Recursive pattern - keep
11772 A third recursive pattern is called the @code{keep} pattern.
11773 In the @code{keep} recursive pattern, each element of a list is tested;
11774 the element is acted on and the results are kept only if the element
11777 Again, this is very like the @code{every} pattern, except the element is
11778 skipped unless it meets a criterion.
11781 The pattern has three parts:
11785 If a list be empty, return @code{nil}.
11787 Else, if the beginning of the list (the @sc{car} of the list) passes
11791 act on that element and combine it, using @code{cons} with
11793 a recursive call by the function on the rest (the @sc{cdr}) of the list.
11796 Otherwise, if the beginning of the list (the @sc{car} of the list) fails
11800 skip on that element,
11802 and, recursively call the function on the rest (the @sc{cdr}) of the list.
11807 Here is an example that uses @code{cond}:
11811 (defun keep-three-letter-words (word-list)
11812 "Keep three letter words in WORD-LIST."
11814 ;; First do-again-test: stop-condition
11815 ((not word-list) nil)
11817 ;; Second do-again-test: when to act
11818 ((eq 3 (length (symbol-name (car word-list))))
11819 ;; combine acted-on element with recursive call on shorter list
11820 (cons (car word-list) (keep-three-letter-words (cdr word-list))))
11822 ;; Third do-again-test: when to skip element;
11823 ;; recursively call shorter list with next-step expression
11824 (t (keep-three-letter-words (cdr word-list)))))
11828 (keep-three-letter-words '(one two three four five six))
11829 @result{} (one two six)
11833 It goes without saying that you need not use @code{nil} as the test for
11834 when to stop; and you can, of course, combine these patterns.
11837 @subsection Recursion without Deferments
11838 @cindex Deferment in recursion
11839 @cindex Recursion without Deferments
11841 Let's consider again what happens with the @code{triangle-recursively}
11842 function. We will find that the intermediate calculations are
11843 deferred until all can be done.
11846 Here is the function definition:
11850 (defun triangle-recursively (number)
11851 "Return the sum of the numbers 1 through NUMBER inclusive.
11853 (if (= number 1) ; @r{do-again-test}
11855 (+ number ; @r{else-part}
11856 (triangle-recursively ; @r{recursive call}
11857 (1- number))))) ; @r{next-step-expression}
11861 What happens when we call this function with a argument of 7?
11863 The first instance of the @code{triangle-recursively} function adds
11864 the number 7 to the value returned by a second instance of
11865 @code{triangle-recursively}, an instance that has been passed an
11866 argument of 6. That is to say, the first calculation is:
11869 (+ 7 (triangle-recursively 6))
11873 The first instance of @code{triangle-recursively}---you may want to
11874 think of it as a little robot---cannot complete its job. It must hand
11875 off the calculation for @code{(triangle-recursively 6)} to a second
11876 instance of the program, to a second robot. This second individual is
11877 completely different from the first one; it is, in the jargon, a
11878 ``different instantiation''. Or, put another way, it is a different
11879 robot. It is the same model as the first; it calculates triangle
11880 numbers recursively; but it has a different serial number.
11882 And what does @code{(triangle-recursively 6)} return? It returns the
11883 number 6 added to the value returned by evaluating
11884 @code{triangle-recursively} with an argument of 5. Using the robot
11885 metaphor, it asks yet another robot to help it.
11891 (+ 7 6 (triangle-recursively 5))
11895 And what happens next?
11898 (+ 7 6 5 (triangle-recursively 4))
11901 Each time @code{triangle-recursively} is called, except for the last
11902 time, it creates another instance of the program---another robot---and
11903 asks it to make a calculation.
11906 Eventually, the full addition is set up and performed:
11912 This design for the function defers the calculation of the first step
11913 until the second can be done, and defers that until the third can be
11914 done, and so on. Each deferment means the computer must remember what
11915 is being waited on. This is not a problem when there are only a few
11916 steps, as in this example. But it can be a problem when there are
11919 @node No deferment solution
11920 @subsection No Deferment Solution
11921 @cindex No deferment solution
11922 @cindex Solution without deferment
11924 The solution to the problem of deferred operations is to write in a
11925 manner that does not defer operations@footnote{The phrase @dfn{tail
11926 recursive} is used to describe such a process, one that uses
11927 constant space.}. This requires
11928 writing to a different pattern, often one that involves writing two
11929 function definitions, an initialization function and a helper
11932 The initialization function sets up the job; the helper function
11936 Here are the two function definitions for adding up numbers. They are
11937 so simple, I find them hard to understand.
11941 (defun triangle-initialization (number)
11942 "Return the sum of the numbers 1 through NUMBER inclusive.
11943 This is the initialization component of a two function
11944 duo that uses recursion."
11945 (triangle-recursive-helper 0 0 number))
11951 (defun triangle-recursive-helper (sum counter number)
11952 "Return SUM, using COUNTER, through NUMBER inclusive.
11953 This is the helper component of a two function duo
11954 that uses recursion."
11955 (if (> counter number)
11957 (triangle-recursive-helper (+ sum counter) ; @r{sum}
11958 (1+ counter) ; @r{counter}
11959 number))) ; @r{number}
11964 Install both function definitions by evaluating them, then call
11965 @code{triangle-initialization} with 2 rows:
11969 (triangle-initialization 2)
11974 The initialization function calls the first instance of the helper
11975 function with three arguments: zero, zero, and a number which is the
11976 number of rows in the triangle.
11978 The first two arguments passed to the helper function are
11979 initialization values. These values are changed when
11980 @code{triangle-recursive-helper} invokes new instances.@footnote{The
11981 jargon is mildly confusing: @code{triangle-recursive-helper} uses a
11982 process that is iterative in a procedure that is recursive. The
11983 process is called iterative because the computer need only record the
11984 three values, @code{sum}, @code{counter}, and @code{number}; the
11985 procedure is recursive because the function calls itself. On the
11986 other hand, both the process and the procedure used by
11987 @code{triangle-recursively} are called recursive. The word
11988 ``recursive'' has different meanings in the two contexts.}
11990 Let's see what happens when we have a triangle that has one row. (This
11991 triangle will have one pebble in it!)
11994 @code{triangle-initialization} will call its helper with
11995 the arguments @w{@code{0 0 1}}. That function will run the conditional
11996 test whether @code{(> counter number)}:
12004 and find that the result is false, so it will invoke
12005 the else-part of the @code{if} clause:
12009 (triangle-recursive-helper
12010 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
12011 (1+ counter) ; @r{increment counter} @result{} @r{counter}
12012 number) ; @r{number stays the same}
12018 which will first compute:
12022 (triangle-recursive-helper (+ 0 0) ; @r{sum}
12023 (1+ 0) ; @r{counter}
12027 (triangle-recursive-helper 0 1 1)
12031 Again, @code{(> counter number)} will be false, so again, the Lisp
12032 interpreter will evaluate @code{triangle-recursive-helper}, creating a
12033 new instance with new arguments.
12036 This new instance will be;
12040 (triangle-recursive-helper
12041 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
12042 (1+ counter) ; @r{increment counter} @result{} @r{counter}
12043 number) ; @r{number stays the same}
12047 (triangle-recursive-helper 1 2 1)
12051 In this case, the @code{(> counter number)} test will be true! So the
12052 instance will return the value of the sum, which will be 1, as
12055 Now, let's pass @code{triangle-initialization} an argument
12056 of 2, to find out how many pebbles there are in a triangle with two rows.
12058 That function calls @code{(triangle-recursive-helper 0 0 2)}.
12061 In stages, the instances called will be:
12065 @r{sum counter number}
12066 (triangle-recursive-helper 0 1 2)
12068 (triangle-recursive-helper 1 2 2)
12070 (triangle-recursive-helper 3 3 2)
12074 When the last instance is called, the @code{(> counter number)} test
12075 will be true, so the instance will return the value of @code{sum},
12078 This kind of pattern helps when you are writing functions that can use
12079 many resources in a computer.
12082 @node Looping exercise
12083 @section Looping Exercise
12087 Write a function similar to @code{triangle} in which each row has a
12088 value which is the square of the row number. Use a @code{while} loop.
12091 Write a function similar to @code{triangle} that multiplies instead of
12095 Rewrite these two functions recursively. Rewrite these functions
12098 @c comma in printed title causes problem in Info cross reference
12100 Write a function for Texinfo mode that creates an index entry at the
12101 beginning of a paragraph for every @samp{@@dfn} within the paragraph.
12102 (In a Texinfo file, @samp{@@dfn} marks a definition. This book is
12103 written in Texinfo.)
12105 Many of the functions you will need are described in two of the
12106 previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing
12107 Text}, and @ref{Yanking, , Yanking Text Back}. If you use
12108 @code{forward-paragraph} to put the index entry at the beginning of
12109 the paragraph, you will have to use @w{@kbd{C-h f}}
12110 (@code{describe-function}) to find out how to make the command go
12113 For more information, see
12115 @ref{Indicating, , Indicating Definitions, texinfo}.
12118 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to
12119 a Texinfo manual in the current directory. Or, if you are on the
12121 @uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
12124 ``Indicating Definitions, Commands, etc.''@: in @cite{Texinfo, The GNU
12125 Documentation Format}.
12129 @node Regexp Search
12130 @chapter Regular Expression Searches
12131 @cindex Searches, illustrating
12132 @cindex Regular expression searches
12133 @cindex Patterns, searching for
12134 @cindex Motion by sentence and paragraph
12135 @cindex Sentences, movement by
12136 @cindex Paragraphs, movement by
12138 Regular expression searches are used extensively in GNU Emacs. The
12139 two functions, @code{forward-sentence} and @code{forward-paragraph},
12140 illustrate these searches well. They use regular expressions to find
12141 where to move point. The phrase ``regular expression'' is often written
12144 Regular expression searches are described in @ref{Regexp Search, ,
12145 Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in
12146 @ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference
12147 Manual}. In writing this chapter, I am presuming that you have at
12148 least a mild acquaintance with them. The major point to remember is
12149 that regular expressions permit you to search for patterns as well as
12150 for literal strings of characters. For example, the code in
12151 @code{forward-sentence} searches for the pattern of possible
12152 characters that could mark the end of a sentence, and moves point to
12155 Before looking at the code for the @code{forward-sentence} function, it
12156 is worth considering what the pattern that marks the end of a sentence
12157 must be. The pattern is discussed in the next section; following that
12158 is a description of the regular expression search function,
12159 @code{re-search-forward}. The @code{forward-sentence} function
12160 is described in the section following. Finally, the
12161 @code{forward-paragraph} function is described in the last section of
12162 this chapter. @code{forward-paragraph} is a complex function that
12163 introduces several new features.
12166 * sentence-end:: The regular expression for @code{sentence-end}.
12167 * re-search-forward:: Very similar to @code{search-forward}.
12168 * forward-sentence:: A straightforward example of regexp search.
12169 * forward-paragraph:: A somewhat complex example.
12170 * etags:: How to create your own @file{TAGS} table.
12172 * re-search Exercises::
12176 @section The Regular Expression for @code{sentence-end}
12177 @findex sentence-end
12179 The symbol @code{sentence-end} is bound to the pattern that marks the
12180 end of a sentence. What should this regular expression be?
12182 Clearly, a sentence may be ended by a period, a question mark, or an
12183 exclamation mark. Indeed, in English, only clauses that end with one
12184 of those three characters should be considered the end of a sentence.
12185 This means that the pattern should include the character set:
12191 However, we do not want @code{forward-sentence} merely to jump to a
12192 period, a question mark, or an exclamation mark, because such a character
12193 might be used in the middle of a sentence. A period, for example, is
12194 used after abbreviations. So other information is needed.
12196 According to convention, you type two spaces after every sentence, but
12197 only one space after a period, a question mark, or an exclamation mark in
12198 the body of a sentence. So a period, a question mark, or an exclamation
12199 mark followed by two spaces is a good indicator of an end of sentence.
12200 However, in a file, the two spaces may instead be a tab or the end of a
12201 line. This means that the regular expression should include these three
12202 items as alternatives.
12205 This group of alternatives will look like this:
12216 Here, @samp{$} indicates the end of the line, and I have pointed out
12217 where the tab and two spaces are inserted in the expression. Both are
12218 inserted by putting the actual characters into the expression.
12220 Two backslashes, @samp{\\}, are required before the parentheses and
12221 vertical bars: the first backslash quotes the following backslash in
12222 Emacs; and the second indicates that the following character, the
12223 parenthesis or the vertical bar, is special.
12226 Also, a sentence may be followed by one or more carriage returns, like
12237 Like tabs and spaces, a carriage return is inserted into a regular
12238 expression by inserting it literally. The asterisk indicates that the
12239 @key{RET} is repeated zero or more times.
12241 But a sentence end does not consist only of a period, a question mark or
12242 an exclamation mark followed by appropriate space: a closing quotation
12243 mark or a closing brace of some kind may precede the space. Indeed more
12244 than one such mark or brace may precede the space. These require a
12245 expression that looks like this:
12251 In this expression, the first @samp{]} is the first character in the
12252 expression; the second character is @samp{"}, which is preceded by a
12253 @samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last
12254 three characters are @samp{'}, @samp{)}, and @samp{@}}.
12256 All this suggests what the regular expression pattern for matching the
12257 end of a sentence should be; and, indeed, if we evaluate
12258 @code{sentence-end} we find that it returns the following value:
12263 @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[
12269 (Well, not in GNU Emacs 22; that is because of an effort to make the
12270 process simpler and to handle more glyphs and languages. When the
12271 value of @code{sentence-end} is @code{nil}, then use the value defined
12272 by the function @code{sentence-end}. (Here is a use of the difference
12273 between a value and a function in Emacs Lisp.) The function returns a
12274 value constructed from the variables @code{sentence-end-base},
12275 @code{sentence-end-double-space}, @code{sentence-end-without-period},
12276 and @code{sentence-end-without-space}. The critical variable is
12277 @code{sentence-end-base}; its global value is similar to the one
12278 described above but it also contains two additional quotation marks.
12279 These have differing degrees of curliness. The
12280 @code{sentence-end-without-period} variable, when true, tells Emacs
12281 that a sentence may end without a period, such as text in Thai.)
12285 (Note that here the @key{TAB}, two spaces, and @key{RET} are shown
12286 literally in the pattern.)
12288 This regular expression can be deciphered as follows:
12292 The first part of the pattern is the three characters, a period, a question
12293 mark and an exclamation mark, within square brackets. The pattern must
12294 begin with one or other of these characters.
12297 The second part of the pattern is the group of closing braces and
12298 quotation marks, which can appear zero or more times. These may follow
12299 the period, question mark or exclamation mark. In a regular expression,
12300 the backslash, @samp{\}, followed by the double quotation mark,
12301 @samp{"}, indicates the class of string-quote characters. Usually, the
12302 double quotation mark is the only character in this class. The
12303 asterisk, @samp{*}, indicates that the items in the previous group (the
12304 group surrounded by square brackets, @samp{[]}) may be repeated zero or
12307 @item \\($\\| \\| \\)
12308 The third part of the pattern is one or other of: either the end of a
12309 line, or two blank spaces, or a tab. The double back-slashes are used
12310 to prevent Emacs from reading the parentheses and vertical bars as part
12311 of the search pattern; the parentheses are used to mark the group and
12312 the vertical bars are used to indicated that the patterns to either side
12313 of them are alternatives. The dollar sign is used to indicate the end
12314 of a line and both the two spaces and the tab are each inserted as is to
12315 indicate what they are.
12318 Finally, the last part of the pattern indicates that the end of the line
12319 or the whitespace following the period, question mark or exclamation
12320 mark may, but need not, be followed by one or more carriage returns. In
12321 the pattern, the carriage return is inserted as an actual carriage
12322 return between square brackets but here it is shown as @key{RET}.
12326 @node re-search-forward
12327 @section The @code{re-search-forward} Function
12328 @findex re-search-forward
12330 The @code{re-search-forward} function is very like the
12331 @code{search-forward} function. (@xref{search-forward, , The
12332 @code{search-forward} Function}.)
12334 @code{re-search-forward} searches for a regular expression. If the
12335 search is successful, it leaves point immediately after the last
12336 character in the target. If the search is backwards, it leaves point
12337 just before the first character in the target. You may tell
12338 @code{re-search-forward} to return @code{t} for true. (Moving point
12339 is therefore a side effect.)
12341 Like @code{search-forward}, the @code{re-search-forward} function takes
12346 The first argument is the regular expression that the function searches
12347 for. The regular expression will be a string between quotation marks.
12350 The optional second argument limits how far the function will search; it is a
12351 bound, which is specified as a position in the buffer.
12354 The optional third argument specifies how the function responds to
12355 failure: @code{nil} as the third argument causes the function to
12356 signal an error (and print a message) when the search fails; any other
12357 value causes it to return @code{nil} if the search fails and @code{t}
12358 if the search succeeds.
12361 The optional fourth argument is the repeat count. A negative repeat
12362 count causes @code{re-search-forward} to search backwards.
12366 The template for @code{re-search-forward} looks like this:
12370 (re-search-forward "@var{regular-expression}"
12371 @var{limit-of-search}
12372 @var{what-to-do-if-search-fails}
12373 @var{repeat-count})
12377 The second, third, and fourth arguments are optional. However, if you
12378 want to pass a value to either or both of the last two arguments, you
12379 must also pass a value to all the preceding arguments. Otherwise, the
12380 Lisp interpreter will mistake which argument you are passing the value
12384 In the @code{forward-sentence} function, the regular expression will be
12385 the value of the variable @code{sentence-end}. In simple form, that is:
12389 "[.?!][]\"')@}]*\\($\\| \\| \\)[
12395 The limit of the search will be the end of the paragraph (since a
12396 sentence cannot go beyond a paragraph). If the search fails, the
12397 function will return @code{nil}; and the repeat count will be provided
12398 by the argument to the @code{forward-sentence} function.
12400 @node forward-sentence
12401 @section @code{forward-sentence}
12402 @findex forward-sentence
12404 The command to move the cursor forward a sentence is a straightforward
12405 illustration of how to use regular expression searches in Emacs Lisp.
12406 Indeed, the function looks longer and more complicated than it is; this
12407 is because the function is designed to go backwards as well as forwards;
12408 and, optionally, over more than one sentence. The function is usually
12409 bound to the key command @kbd{M-e}.
12412 * Complete forward-sentence::
12413 * fwd-sentence while loops:: Two @code{while} loops.
12414 * fwd-sentence re-search:: A regular expression search.
12418 @node Complete forward-sentence
12419 @unnumberedsubsec Complete @code{forward-sentence} function definition
12423 Here is the code for @code{forward-sentence}:
12428 (defun forward-sentence (&optional arg)
12429 "Move forward to next end of sentence. With argument, repeat.
12430 With negative argument, move backward repeatedly to start of sentence.
12432 The variable `sentence-end' is a regular expression that matches ends of
12433 sentences. Also, every paragraph boundary terminates sentences as well."
12437 (or arg (setq arg 1))
12438 (let ((opoint (point))
12439 (sentence-end (sentence-end)))
12441 (let ((pos (point))
12442 (par-beg (save-excursion (start-of-paragraph-text) (point))))
12443 (if (and (re-search-backward sentence-end par-beg t)
12444 (or (< (match-end 0) pos)
12445 (re-search-backward sentence-end par-beg t)))
12446 (goto-char (match-end 0))
12447 (goto-char par-beg)))
12448 (setq arg (1+ arg)))
12452 (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
12453 (if (re-search-forward sentence-end par-end t)
12454 (skip-chars-backward " \t\n")
12455 (goto-char par-end)))
12456 (setq arg (1- arg)))
12457 (constrain-to-field nil opoint t)))
12465 (defun forward-sentence (&optional arg)
12466 "Move forward to next sentence-end. With argument, repeat.
12467 With negative argument, move backward repeatedly to sentence-beginning.
12468 Sentence ends are identified by the value of sentence-end
12469 treated as a regular expression. Also, every paragraph boundary
12470 terminates sentences as well."
12474 (or arg (setq arg 1))
12477 (save-excursion (start-of-paragraph-text) (point))))
12478 (if (re-search-backward
12479 (concat sentence-end "[^ \t\n]") par-beg t)
12480 (goto-char (1- (match-end 0)))
12481 (goto-char par-beg)))
12482 (setq arg (1+ arg)))
12485 (save-excursion (end-of-paragraph-text) (point))))
12486 (if (re-search-forward sentence-end par-end t)
12487 (skip-chars-backward " \t\n")
12488 (goto-char par-end)))
12489 (setq arg (1- arg))))
12494 The function looks long at first sight and it is best to look at its
12495 skeleton first, and then its muscle. The way to see the skeleton is to
12496 look at the expressions that start in the left-most columns:
12500 (defun forward-sentence (&optional arg)
12501 "@var{documentation}@dots{}"
12503 (or arg (setq arg 1))
12504 (let ((opoint (point)) (sentence-end (sentence-end)))
12506 (let ((pos (point))
12507 (par-beg (save-excursion (start-of-paragraph-text) (point))))
12508 @var{rest-of-body-of-while-loop-when-going-backwards}
12510 (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
12511 @var{rest-of-body-of-while-loop-when-going-forwards}
12512 @var{handle-forms-and-equivalent}
12516 This looks much simpler! The function definition consists of
12517 documentation, an @code{interactive} expression, an @code{or}
12518 expression, a @code{let} expression, and @code{while} loops.
12520 Let's look at each of these parts in turn.
12522 We note that the documentation is thorough and understandable.
12524 The function has an @code{interactive "p"} declaration. This means
12525 that the processed prefix argument, if any, is passed to the
12526 function as its argument. (This will be a number.) If the function
12527 is not passed an argument (it is optional) then the argument
12528 @code{arg} will be bound to 1.
12530 When @code{forward-sentence} is called non-interactively without an
12531 argument, @code{arg} is bound to @code{nil}. The @code{or} expression
12532 handles this. What it does is either leave the value of @code{arg} as
12533 it is, but only if @code{arg} is bound to a value; or it sets the
12534 value of @code{arg} to 1, in the case when @code{arg} is bound to
12537 Next is a @code{let}. That specifies the values of two local
12538 variables, @code{point} and @code{sentence-end}. The local value of
12539 point, from before the search, is used in the
12540 @code{constrain-to-field} function which handles forms and
12541 equivalents. The @code{sentence-end} variable is set by the
12542 @code{sentence-end} function.
12544 @node fwd-sentence while loops
12545 @unnumberedsubsec The @code{while} loops
12547 Two @code{while} loops follow. The first @code{while} has a
12548 true-or-false-test that tests true if the prefix argument for
12549 @code{forward-sentence} is a negative number. This is for going
12550 backwards. The body of this loop is similar to the body of the second
12551 @code{while} clause, but it is not exactly the same. We will skip
12552 this @code{while} loop and concentrate on the second @code{while}
12556 The second @code{while} loop is for moving point forward. Its skeleton
12561 (while (> arg 0) ; @r{true-or-false-test}
12563 (if (@var{true-or-false-test})
12566 (setq arg (1- arg)))) ; @code{while} @r{loop decrementer}
12570 The @code{while} loop is of the decrementing kind.
12571 (@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It
12572 has a true-or-false-test that tests true so long as the counter (in
12573 this case, the variable @code{arg}) is greater than zero; and it has a
12574 decrementer that subtracts 1 from the value of the counter every time
12577 If no prefix argument is given to @code{forward-sentence}, which is
12578 the most common way the command is used, this @code{while} loop will
12579 run once, since the value of @code{arg} will be 1.
12581 The body of the @code{while} loop consists of a @code{let} expression,
12582 which creates and binds a local variable, and has, as its body, an
12583 @code{if} expression.
12586 The body of the @code{while} loop looks like this:
12591 (save-excursion (end-of-paragraph-text) (point))))
12592 (if (re-search-forward sentence-end par-end t)
12593 (skip-chars-backward " \t\n")
12594 (goto-char par-end)))
12598 The @code{let} expression creates and binds the local variable
12599 @code{par-end}. As we shall see, this local variable is designed to
12600 provide a bound or limit to the regular expression search. If the
12601 search fails to find a proper sentence ending in the paragraph, it will
12602 stop on reaching the end of the paragraph.
12604 But first, let us examine how @code{par-end} is bound to the value of
12605 the end of the paragraph. What happens is that the @code{let} sets the
12606 value of @code{par-end} to the value returned when the Lisp interpreter
12607 evaluates the expression
12611 (save-excursion (end-of-paragraph-text) (point))
12616 In this expression, @code{(end-of-paragraph-text)} moves point to the
12617 end of the paragraph, @code{(point)} returns the value of point, and then
12618 @code{save-excursion} restores point to its original position. Thus,
12619 the @code{let} binds @code{par-end} to the value returned by the
12620 @code{save-excursion} expression, which is the position of the end of
12621 the paragraph. (The @code{end-of-paragraph-text} function uses
12622 @code{forward-paragraph}, which we will discuss shortly.)
12625 Emacs next evaluates the body of the @code{let}, which is an @code{if}
12626 expression that looks like this:
12630 (if (re-search-forward sentence-end par-end t) ; @r{if-part}
12631 (skip-chars-backward " \t\n") ; @r{then-part}
12632 (goto-char par-end))) ; @r{else-part}
12636 The @code{if} tests whether its first argument is true and if so,
12637 evaluates its then-part; otherwise, the Emacs Lisp interpreter
12638 evaluates the else-part. The true-or-false-test of the @code{if}
12639 expression is the regular expression search.
12641 It may seem odd to have what looks like the real work of
12642 the @code{forward-sentence} function buried here, but this is a common
12643 way this kind of operation is carried out in Lisp.
12645 @node fwd-sentence re-search
12646 @unnumberedsubsec The regular expression search
12648 The @code{re-search-forward} function searches for the end of the
12649 sentence, that is, for the pattern defined by the @code{sentence-end}
12650 regular expression. If the pattern is found---if the end of the sentence is
12651 found---then the @code{re-search-forward} function does two things:
12655 The @code{re-search-forward} function carries out a side effect, which
12656 is to move point to the end of the occurrence found.
12659 The @code{re-search-forward} function returns a value of true. This is
12660 the value received by the @code{if}, and means that the search was
12665 The side effect, the movement of point, is completed before the
12666 @code{if} function is handed the value returned by the successful
12667 conclusion of the search.
12669 When the @code{if} function receives the value of true from a successful
12670 call to @code{re-search-forward}, the @code{if} evaluates the then-part,
12671 which is the expression @code{(skip-chars-backward " \t\n")}. This
12672 expression moves backwards over any blank spaces, tabs or carriage
12673 returns until a printed character is found and then leaves point after
12674 the character. Since point has already been moved to the end of the
12675 pattern that marks the end of the sentence, this action leaves point
12676 right after the closing printed character of the sentence, which is
12679 On the other hand, if the @code{re-search-forward} function fails to
12680 find a pattern marking the end of the sentence, the function returns
12681 false. The false then causes the @code{if} to evaluate its third
12682 argument, which is @code{(goto-char par-end)}: it moves point to the
12683 end of the paragraph.
12685 (And if the text is in a form or equivalent, and point may not move
12686 fully, then the @code{constrain-to-field} function comes into play.)
12688 Regular expression searches are exceptionally useful and the pattern
12689 illustrated by @code{re-search-forward}, in which the search is the
12690 test of an @code{if} expression, is handy. You will see or write code
12691 incorporating this pattern often.
12693 @node forward-paragraph
12694 @section @code{forward-paragraph}: a Goldmine of Functions
12695 @findex forward-paragraph
12699 (defun forward-paragraph (&optional arg)
12700 "Move forward to end of paragraph.
12701 With argument ARG, do it ARG times;
12702 a negative argument ARG = -N means move backward N paragraphs.
12704 A line which `paragraph-start' matches either separates paragraphs
12705 \(if `paragraph-separate' matches it also) or is the first line of a paragraph.
12706 A paragraph end is the beginning of a line which is not part of the paragraph
12707 to which the end of the previous line belongs, or the end of the buffer.
12708 Returns the count of paragraphs left to move."
12710 (or arg (setq arg 1))
12711 (let* ((opoint (point))
12712 (fill-prefix-regexp
12713 (and fill-prefix (not (equal fill-prefix ""))
12714 (not paragraph-ignore-fill-prefix)
12715 (regexp-quote fill-prefix)))
12716 ;; Remove ^ from paragraph-start and paragraph-sep if they are there.
12717 ;; These regexps shouldn't be anchored, because we look for them
12718 ;; starting at the left-margin. This allows paragraph commands to
12719 ;; work normally with indented text.
12720 ;; This hack will not find problem cases like "whatever\\|^something".
12721 (parstart (if (and (not (equal "" paragraph-start))
12722 (equal ?^ (aref paragraph-start 0)))
12723 (substring paragraph-start 1)
12725 (parsep (if (and (not (equal "" paragraph-separate))
12726 (equal ?^ (aref paragraph-separate 0)))
12727 (substring paragraph-separate 1)
12728 paragraph-separate))
12730 (if fill-prefix-regexp
12731 (concat parsep "\\|"
12732 fill-prefix-regexp "[ \t]*$")
12734 ;; This is used for searching.
12735 (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)"))
12737 (while (and (< arg 0) (not (bobp)))
12738 (if (and (not (looking-at parsep))
12739 (re-search-backward "^\n" (max (1- (point)) (point-min)) t)
12740 (looking-at parsep))
12741 (setq arg (1+ arg))
12742 (setq start (point))
12743 ;; Move back over paragraph-separating lines.
12744 (forward-char -1) (beginning-of-line)
12745 (while (and (not (bobp))
12746 (progn (move-to-left-margin)
12747 (looking-at parsep)))
12751 (setq arg (1+ arg))
12752 ;; Go to end of the previous (non-separating) line.
12754 ;; Search back for line that starts or separates paragraphs.
12755 (if (if fill-prefix-regexp
12756 ;; There is a fill prefix; it overrides parstart.
12757 (let (multiple-lines)
12758 (while (and (progn (beginning-of-line) (not (bobp)))
12759 (progn (move-to-left-margin)
12760 (not (looking-at parsep)))
12761 (looking-at fill-prefix-regexp))
12762 (unless (= (point) start)
12763 (setq multiple-lines t))
12765 (move-to-left-margin)
12766 ;; This deleted code caused a long hanging-indent line
12767 ;; not to be filled together with the following lines.
12768 ;; ;; Don't move back over a line before the paragraph
12769 ;; ;; which doesn't start with fill-prefix
12770 ;; ;; unless that is the only line we've moved over.
12771 ;; (and (not (looking-at fill-prefix-regexp))
12773 ;; (forward-line 1))
12775 (while (and (re-search-backward sp-parstart nil 1)
12776 (setq found-start t)
12777 ;; Found a candidate, but need to check if it is a
12779 (progn (setq start (point))
12780 (move-to-left-margin)
12781 (not (looking-at parsep)))
12782 (not (and (looking-at parstart)
12783 (or (not use-hard-newlines)
12786 (1- start) 'hard)))))
12787 (setq found-start nil)
12792 ;; Move forward over paragraph separators.
12793 ;; We know this cannot reach the place we started
12794 ;; because we know we moved back over a non-separator.
12795 (while (and (not (eobp))
12796 (progn (move-to-left-margin)
12797 (looking-at parsep)))
12799 ;; If line before paragraph is just margin, back up to there.
12801 (if (> (current-column) (current-left-margin))
12803 (skip-chars-backward " \t")
12805 (forward-line 1))))
12806 ;; No starter or separator line => use buffer beg.
12807 (goto-char (point-min))))))
12809 (while (and (> arg 0) (not (eobp)))
12810 ;; Move forward over separator lines...
12811 (while (and (not (eobp))
12812 (progn (move-to-left-margin) (not (eobp)))
12813 (looking-at parsep))
12815 (unless (eobp) (setq arg (1- arg)))
12816 ;; ... and one more line.
12818 (if fill-prefix-regexp
12819 ;; There is a fill prefix; it overrides parstart.
12820 (while (and (not (eobp))
12821 (progn (move-to-left-margin) (not (eobp)))
12822 (not (looking-at parsep))
12823 (looking-at fill-prefix-regexp))
12825 (while (and (re-search-forward sp-parstart nil 1)
12826 (progn (setq start (match-beginning 0))
12829 (progn (move-to-left-margin)
12830 (not (looking-at parsep)))
12831 (or (not (looking-at parstart))
12832 (and use-hard-newlines
12833 (not (get-text-property (1- start) 'hard)))))
12835 (if (< (point) (point-max))
12836 (goto-char start))))
12837 (constrain-to-field nil opoint t)
12838 ;; Return the number of steps that could not be done.
12842 The @code{forward-paragraph} function moves point forward to the end
12843 of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a
12844 number of functions that are important in themselves, including
12845 @code{let*}, @code{match-beginning}, and @code{looking-at}.
12847 The function definition for @code{forward-paragraph} is considerably
12848 longer than the function definition for @code{forward-sentence}
12849 because it works with a paragraph, each line of which may begin with a
12852 A fill prefix consists of a string of characters that are repeated at
12853 the beginning of each line. For example, in Lisp code, it is a
12854 convention to start each line of a paragraph-long comment with
12855 @samp{;;; }. In Text mode, four blank spaces make up another common
12856 fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , ,
12857 emacs, The GNU Emacs Manual}, for more information about fill
12860 The existence of a fill prefix means that in addition to being able to
12861 find the end of a paragraph whose lines begin on the left-most
12862 column, the @code{forward-paragraph} function must be able to find the
12863 end of a paragraph when all or many of the lines in the buffer begin
12864 with the fill prefix.
12866 Moreover, it is sometimes practical to ignore a fill prefix that
12867 exists, especially when blank lines separate paragraphs.
12868 This is an added complication.
12871 * forward-paragraph in brief:: Key parts of the function definition.
12872 * fwd-para let:: The @code{let*} expression.
12873 * fwd-para while:: The forward motion @code{while} loop.
12877 @node forward-paragraph in brief
12878 @unnumberedsubsec Shortened @code{forward-paragraph} function definition
12881 Rather than print all of the @code{forward-paragraph} function, we
12882 will only print parts of it. Read without preparation, the function
12886 In outline, the function looks like this:
12890 (defun forward-paragraph (&optional arg)
12891 "@var{documentation}@dots{}"
12893 (or arg (setq arg 1))
12896 (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code}
12898 (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code}
12903 The first parts of the function are routine: the function's argument
12904 list consists of one optional argument. Documentation follows.
12906 The lower case @samp{p} in the @code{interactive} declaration means
12907 that the processed prefix argument, if any, is passed to the function.
12908 This will be a number, and is the repeat count of how many paragraphs
12909 point will move. The @code{or} expression in the next line handles
12910 the common case when no argument is passed to the function, which occurs
12911 if the function is called from other code rather than interactively.
12912 This case was described earlier. (@xref{forward-sentence, The
12913 @code{forward-sentence} function}.) Now we reach the end of the
12914 familiar part of this function.
12917 @unnumberedsubsec The @code{let*} expression
12919 The next line of the @code{forward-paragraph} function begins a
12920 @code{let*} expression. This is a different than @code{let}. The
12921 symbol is @code{let*} not @code{let}.
12924 The @code{let*} special form is like @code{let} except that Emacs sets
12925 each variable in sequence, one after another, and variables in the
12926 latter part of the varlist can make use of the values to which Emacs
12927 set variables in the earlier part of the varlist.
12930 ( refappend save-excursion, , code save-excursion in code append-to-buffer .)
12933 (@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.)
12935 In the @code{let*} expression in this function, Emacs binds a total of
12936 seven variables: @code{opoint}, @code{fill-prefix-regexp},
12937 @code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and
12938 @code{found-start}.
12940 The variable @code{parsep} appears twice, first, to remove instances
12941 of @samp{^}, and second, to handle fill prefixes.
12943 The variable @code{opoint} is just the value of @code{point}. As you
12944 can guess, it is used in a @code{constrain-to-field} expression, just
12945 as in @code{forward-sentence}.
12947 The variable @code{fill-prefix-regexp} is set to the value returned by
12948 evaluating the following list:
12953 (not (equal fill-prefix ""))
12954 (not paragraph-ignore-fill-prefix)
12955 (regexp-quote fill-prefix))
12960 This is an expression whose first element is the @code{and} special form.
12962 As we learned earlier (@pxref{kill-new function, , The @code{kill-new}
12963 function}), the @code{and} special form evaluates each of its
12964 arguments until one of the arguments returns a value of @code{nil}, in
12965 which case the @code{and} expression returns @code{nil}; however, if
12966 none of the arguments returns a value of @code{nil}, the value
12967 resulting from evaluating the last argument is returned. (Since such
12968 a value is not @code{nil}, it is considered true in Lisp.) In other
12969 words, an @code{and} expression returns a true value only if all its
12970 arguments are true.
12973 In this case, the variable @code{fill-prefix-regexp} is bound to a
12974 non-@code{nil} value only if the following four expressions produce a
12975 true (i.e., a non-@code{nil}) value when they are evaluated; otherwise,
12976 @code{fill-prefix-regexp} is bound to @code{nil}.
12980 When this variable is evaluated, the value of the fill prefix, if any,
12981 is returned. If there is no fill prefix, this variable returns
12984 @item (not (equal fill-prefix "")
12985 This expression checks whether an existing fill prefix is an empty
12986 string, that is, a string with no characters in it. An empty string is
12987 not a useful fill prefix.
12989 @item (not paragraph-ignore-fill-prefix)
12990 This expression returns @code{nil} if the variable
12991 @code{paragraph-ignore-fill-prefix} has been turned on by being set to a
12992 true value such as @code{t}.
12994 @item (regexp-quote fill-prefix)
12995 This is the last argument to the @code{and} special form. If all the
12996 arguments to the @code{and} are true, the value resulting from
12997 evaluating this expression will be returned by the @code{and} expression
12998 and bound to the variable @code{fill-prefix-regexp},
13001 @findex regexp-quote
13003 The result of evaluating this @code{and} expression successfully is that
13004 @code{fill-prefix-regexp} will be bound to the value of
13005 @code{fill-prefix} as modified by the @code{regexp-quote} function.
13006 What @code{regexp-quote} does is read a string and return a regular
13007 expression that will exactly match the string and match nothing else.
13008 This means that @code{fill-prefix-regexp} will be set to a value that
13009 will exactly match the fill prefix if the fill prefix exists.
13010 Otherwise, the variable will be set to @code{nil}.
13012 The next two local variables in the @code{let*} expression are
13013 designed to remove instances of @samp{^} from @code{parstart} and
13014 @code{parsep}, the local variables which indicate the paragraph start
13015 and the paragraph separator. The next expression sets @code{parsep}
13016 again. That is to handle fill prefixes.
13018 This is the setting that requires the definition call @code{let*}
13019 rather than @code{let}. The true-or-false-test for the @code{if}
13020 depends on whether the variable @code{fill-prefix-regexp} evaluates to
13021 @code{nil} or some other value.
13023 If @code{fill-prefix-regexp} does not have a value, Emacs evaluates
13024 the else-part of the @code{if} expression and binds @code{parsep} to
13025 its local value. (@code{parsep} is a regular expression that matches
13026 what separates paragraphs.)
13028 But if @code{fill-prefix-regexp} does have a value, Emacs evaluates
13029 the then-part of the @code{if} expression and binds @code{parsep} to a
13030 regular expression that includes the @code{fill-prefix-regexp} as part
13033 Specifically, @code{parsep} is set to the original value of the
13034 paragraph separate regular expression concatenated with an alternative
13035 expression that consists of the @code{fill-prefix-regexp} followed by
13036 optional whitespace to the end of the line. The whitespace is defined
13037 by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the
13038 regexp as an alternative to @code{parsep}.
13040 According to a comment in the code, the next local variable,
13041 @code{sp-parstart}, is used for searching, and then the final two,
13042 @code{start} and @code{found-start}, are set to @code{nil}.
13044 Now we get into the body of the @code{let*}. The first part of the body
13045 of the @code{let*} deals with the case when the function is given a
13046 negative argument and is therefore moving backwards. We will skip this
13049 @node fwd-para while
13050 @unnumberedsubsec The forward motion @code{while} loop
13052 The second part of the body of the @code{let*} deals with forward
13053 motion. It is a @code{while} loop that repeats itself so long as the
13054 value of @code{arg} is greater than zero. In the most common use of
13055 the function, the value of the argument is 1, so the body of the
13056 @code{while} loop is evaluated exactly once, and the cursor moves
13057 forward one paragraph.
13060 (while (and (> arg 0) (not (eobp)))
13062 ;; Move forward over separator lines...
13063 (while (and (not (eobp))
13064 (progn (move-to-left-margin) (not (eobp)))
13065 (looking-at parsep))
13067 (unless (eobp) (setq arg (1- arg)))
13068 ;; ... and one more line.
13071 (if fill-prefix-regexp
13072 ;; There is a fill prefix; it overrides parstart.
13073 (while (and (not (eobp))
13074 (progn (move-to-left-margin) (not (eobp)))
13075 (not (looking-at parsep))
13076 (looking-at fill-prefix-regexp))
13079 (while (and (re-search-forward sp-parstart nil 1)
13080 (progn (setq start (match-beginning 0))
13083 (progn (move-to-left-margin)
13084 (not (looking-at parsep)))
13085 (or (not (looking-at parstart))
13086 (and use-hard-newlines
13087 (not (get-text-property (1- start) 'hard)))))
13090 (if (< (point) (point-max))
13091 (goto-char start))))
13094 This part handles three situations: when point is between paragraphs,
13095 when there is a fill prefix and when there is no fill prefix.
13098 The @code{while} loop looks like this:
13102 ;; @r{going forwards and not at the end of the buffer}
13103 (while (and (> arg 0) (not (eobp)))
13105 ;; @r{between paragraphs}
13106 ;; Move forward over separator lines...
13107 (while (and (not (eobp))
13108 (progn (move-to-left-margin) (not (eobp)))
13109 (looking-at parsep))
13111 ;; @r{This decrements the loop}
13112 (unless (eobp) (setq arg (1- arg)))
13113 ;; ... and one more line.
13118 (if fill-prefix-regexp
13119 ;; There is a fill prefix; it overrides parstart;
13120 ;; we go forward line by line
13121 (while (and (not (eobp))
13122 (progn (move-to-left-margin) (not (eobp)))
13123 (not (looking-at parsep))
13124 (looking-at fill-prefix-regexp))
13129 ;; There is no fill prefix;
13130 ;; we go forward character by character
13131 (while (and (re-search-forward sp-parstart nil 1)
13132 (progn (setq start (match-beginning 0))
13135 (progn (move-to-left-margin)
13136 (not (looking-at parsep)))
13137 (or (not (looking-at parstart))
13138 (and use-hard-newlines
13139 (not (get-text-property (1- start) 'hard)))))
13144 ;; and if there is no fill prefix and if we are not at the end,
13145 ;; go to whatever was found in the regular expression search
13147 (if (< (point) (point-max))
13148 (goto-char start))))
13153 We can see that this is a decrementing counter @code{while} loop,
13154 using the expression @code{(setq arg (1- arg))} as the decrementer.
13155 That expression is not far from the @code{while}, but is hidden in
13156 another Lisp macro, an @code{unless} macro. Unless we are at the end
13157 of the buffer---that is what the @code{eobp} function determines; it
13158 is an abbreviation of @samp{End Of Buffer P}---we decrease the value
13159 of @code{arg} by one.
13161 (If we are at the end of the buffer, we cannot go forward any more and
13162 the next loop of the @code{while} expression will test false since the
13163 test is an @code{and} with @code{(not (eobp))}. The @code{not}
13164 function means exactly as you expect; it is another name for
13165 @code{null}, a function that returns true when its argument is false.)
13167 Interestingly, the loop count is not decremented until we leave the
13168 space between paragraphs, unless we come to the end of buffer or stop
13169 seeing the local value of the paragraph separator.
13171 That second @code{while} also has a @code{(move-to-left-margin)}
13172 expression. The function is self-explanatory. It is inside a
13173 @code{progn} expression and not the last element of its body, so it is
13174 only invoked for its side effect, which is to move point to the left
13175 margin of the current line.
13178 The @code{looking-at} function is also self-explanatory; it returns
13179 true if the text after point matches the regular expression given as
13182 The rest of the body of the loop looks difficult at first, but makes
13183 sense as you come to understand it.
13186 First consider what happens if there is a fill prefix:
13190 (if fill-prefix-regexp
13191 ;; There is a fill prefix; it overrides parstart;
13192 ;; we go forward line by line
13193 (while (and (not (eobp))
13194 (progn (move-to-left-margin) (not (eobp)))
13195 (not (looking-at parsep))
13196 (looking-at fill-prefix-regexp))
13202 This expression moves point forward line by line so long
13203 as four conditions are true:
13207 Point is not at the end of the buffer.
13210 We can move to the left margin of the text and are
13211 not at the end of the buffer.
13214 The text following point does not separate paragraphs.
13217 The pattern following point is the fill prefix regular expression.
13220 The last condition may be puzzling, until you remember that point was
13221 moved to the beginning of the line early in the @code{forward-paragraph}
13222 function. This means that if the text has a fill prefix, the
13223 @code{looking-at} function will see it.
13226 Consider what happens when there is no fill prefix.
13230 (while (and (re-search-forward sp-parstart nil 1)
13231 (progn (setq start (match-beginning 0))
13234 (progn (move-to-left-margin)
13235 (not (looking-at parsep)))
13236 (or (not (looking-at parstart))
13237 (and use-hard-newlines
13238 (not (get-text-property (1- start) 'hard)))))
13244 This @code{while} loop has us searching forward for
13245 @code{sp-parstart}, which is the combination of possible whitespace
13246 with the local value of the start of a paragraph or of a paragraph
13247 separator. (The latter two are within an expression starting
13248 @code{\(?:} so that they are not referenced by the
13249 @code{match-beginning} function.)
13252 The two expressions,
13256 (setq start (match-beginning 0))
13262 mean go to the start of the text matched by the regular expression
13265 The @code{(match-beginning 0)} expression is new. It returns a number
13266 specifying the location of the start of the text that was matched by
13269 The @code{match-beginning} function is used here because of a
13270 characteristic of a forward search: a successful forward search,
13271 regardless of whether it is a plain search or a regular expression
13272 search, moves point to the end of the text that is found. In this
13273 case, a successful search moves point to the end of the pattern for
13274 @code{sp-parstart}.
13276 However, we want to put point at the end of the current paragraph, not
13277 somewhere else. Indeed, since the search possibly includes the
13278 paragraph separator, point may end up at the beginning of the next one
13279 unless we use an expression that includes @code{match-beginning}.
13281 @findex match-beginning
13282 When given an argument of 0, @code{match-beginning} returns the
13283 position that is the start of the text matched by the most recent
13284 search. In this case, the most recent search looks for
13285 @code{sp-parstart}. The @code{(match-beginning 0)} expression returns
13286 the beginning position of that pattern, rather than the end position
13289 (Incidentally, when passed a positive number as an argument, the
13290 @code{match-beginning} function returns the location of point at that
13291 parenthesized expression in the last search unless that parenthesized
13292 expression begins with @code{\(?:}. I don't know why @code{\(?:}
13293 appears here since the argument is 0.)
13296 The last expression when there is no fill prefix is
13300 (if (< (point) (point-max))
13301 (goto-char start))))
13306 This says that if there is no fill prefix and if we are not at the
13307 end, point should move to the beginning of whatever was found by the
13308 regular expression search for @code{sp-parstart}.
13310 The full definition for the @code{forward-paragraph} function not only
13311 includes code for going forwards, but also code for going backwards.
13313 If you are reading this inside of GNU Emacs and you want to see the
13314 whole function, you can type @kbd{C-h f} (@code{describe-function})
13315 and the name of the function. This gives you the function
13316 documentation and the name of the library containing the function's
13317 source. Place point over the name of the library and press the RET
13318 key; you will be taken directly to the source. (Be sure to install
13319 your sources! Without them, you are like a person who tries to drive
13320 a car with his eyes shut!)
13323 @section Create Your Own @file{TAGS} File
13325 @cindex @file{TAGS} file, create own
13327 Besides @kbd{C-h f} (@code{describe-function}), another way to see the
13328 source of a function is to type @kbd{M-.} (@code{find-tag}) and the
13329 name of the function when prompted for it. This is a good habit to
13330 get into. The @kbd{M-.} (@code{find-tag}) command takes you directly
13331 to the source for a function, variable, or node. The function depends
13332 on tags tables to tell it where to go.
13334 If the @code{find-tag} function first asks you for the name of a
13335 @file{TAGS} table, give it the name of a @file{TAGS} file such as
13336 @file{/usr/local/src/emacs/src/TAGS}. (The exact path to your
13337 @file{TAGS} file depends on how your copy of Emacs was installed. I
13338 just told you the location that provides both my C and my Emacs Lisp
13341 You can also create your own @file{TAGS} file for directories that
13344 You often need to build and install tags tables yourself. They are
13345 not built automatically. A tags table is called a @file{TAGS} file;
13346 the name is in upper case letters.
13348 You can create a @file{TAGS} file by calling the @code{etags} program
13349 that comes as a part of the Emacs distribution. Usually, @code{etags}
13350 is compiled and installed when Emacs is built. (@code{etags} is not
13351 an Emacs Lisp function or a part of Emacs; it is a C program.)
13354 To create a @file{TAGS} file, first switch to the directory in which
13355 you want to create the file. In Emacs you can do this with the
13356 @kbd{M-x cd} command, or by visiting a file in the directory, or by
13357 listing the directory with @kbd{C-x d} (@code{dired}). Then run the
13358 compile command, with @w{@code{etags *.el}} as the command to execute
13361 M-x compile RET etags *.el RET
13365 to create a @file{TAGS} file for Emacs Lisp.
13367 For example, if you have a large number of files in your
13368 @file{~/emacs} directory, as I do---I have 137 @file{.el} files in it,
13369 of which I load 12---you can create a @file{TAGS} file for the Emacs
13370 Lisp files in that directory.
13373 The @code{etags} program takes all the usual shell wildcards. For
13374 example, if you have two directories for which you want a single
13375 @file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where
13376 @file{../elisp/} is the second directory:
13379 M-x compile RET etags *.el ../elisp/*.el RET
13386 M-x compile RET etags --help RET
13390 to see a list of the options accepted by @code{etags} as well as a
13391 list of supported languages.
13393 The @code{etags} program handles more than 20 languages, including
13394 Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java,
13395 LaTeX, Pascal, Perl, PostScript, Python, TeX, Texinfo, makefiles, and
13396 most assemblers. The program has no switches for specifying the
13397 language; it recognizes the language in an input file according to its
13398 file name and contents.
13400 @file{etags} is very helpful when you are writing code yourself and
13401 want to refer back to functions you have already written. Just run
13402 @code{etags} again at intervals as you write new functions, so they
13403 become part of the @file{TAGS} file.
13405 If you think an appropriate @file{TAGS} file already exists for what
13406 you want, but do not know where it is, you can use the @code{locate}
13407 program to attempt to find it.
13409 Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list
13410 for you the full path names of all your @file{TAGS} files. On my
13411 system, this command lists 34 @file{TAGS} files. On the other hand, a
13412 plain vanilla system I recently installed did not contain any
13415 If the tags table you want has been created, you can use the @code{M-x
13416 visit-tags-table} command to specify it. Otherwise, you will need to
13417 create the tag table yourself and then use @code{M-x
13420 @subsubheading Building Tags in the Emacs sources
13421 @cindex Building Tags in the Emacs sources
13422 @cindex Tags in the Emacs sources
13425 The GNU Emacs sources come with a @file{Makefile} that contains a
13426 sophisticated @code{etags} command that creates, collects, and merges
13427 tags tables from all over the Emacs sources and puts the information
13428 into one @file{TAGS} file in the @file{src/} directory. (The
13429 @file{src/} directory is below the top level of your Emacs directory.)
13432 To build this @file{TAGS} file, go to the top level of your Emacs
13433 source directory and run the compile command @code{make tags}:
13436 M-x compile RET make tags RET
13440 (The @code{make tags} command works well with the GNU Emacs sources,
13441 as well as with some other source packages.)
13443 For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs
13446 @node Regexp Review
13449 Here is a brief summary of some recently introduced functions.
13453 Repeatedly evaluate the body of the expression so long as the first
13454 element of the body tests true. Then return @code{nil}. (The
13455 expression is evaluated only for its side effects.)
13464 (insert (format "foo is %d.\n" foo))
13465 (setq foo (1- foo))))
13467 @result{} foo is 2.
13474 (The @code{insert} function inserts its arguments at point; the
13475 @code{format} function returns a string formatted from its arguments
13476 the way @code{message} formats its arguments; @code{\n} produces a new
13479 @item re-search-forward
13480 Search for a pattern, and if the pattern is found, move point to rest
13484 Takes four arguments, like @code{search-forward}:
13488 A regular expression that specifies the pattern to search for.
13489 (Remember to put quotation marks around this argument!)
13492 Optionally, the limit of the search.
13495 Optionally, what to do if the search fails, return @code{nil} or an
13499 Optionally, how many times to repeat the search; if negative, the
13500 search goes backwards.
13504 Bind some variables locally to particular values,
13505 and then evaluate the remaining arguments, returning the value of the
13506 last one. While binding the local variables, use the local values of
13507 variables bound earlier, if any.
13516 (message "`bar' is %d." bar))
13517 @result{} ‘bar’ is 21.
13521 @item match-beginning
13522 Return the position of the start of the text found by the last regular
13526 Return @code{t} for true if the text after point matches the argument,
13527 which should be a regular expression.
13530 Return @code{t} for true if point is at the end of the accessible part
13531 of a buffer. The end of the accessible part is the end of the buffer
13532 if the buffer is not narrowed; it is the end of the narrowed part if
13533 the buffer is narrowed.
13537 @node re-search Exercises
13538 @section Exercises with @code{re-search-forward}
13542 Write a function to search for a regular expression that matches two
13543 or more blank lines in sequence.
13546 Write a function to search for duplicated words, such as ``the the''.
13547 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
13548 Manual}, for information on how to write a regexp (a regular
13549 expression) to match a string that is composed of two identical
13550 halves. You can devise several regexps; some are better than others.
13551 The function I use is described in an appendix, along with several
13552 regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}.
13555 @node Counting Words
13556 @chapter Counting via Repetition and Regexps
13557 @cindex Repetition for word counting
13558 @cindex Regular expressions for word counting
13560 Repetition and regular expression searches are powerful tools that you
13561 often use when you write code in Emacs Lisp. This chapter illustrates
13562 the use of regular expression searches through the construction of
13563 word count commands using @code{while} loops and recursion.
13566 * Why Count Words::
13567 * @value{COUNT-WORDS}:: Use a regexp, but find a problem.
13568 * recursive-count-words:: Start with case of no words in region.
13569 * Counting Exercise::
13573 @node Why Count Words
13574 @unnumberedsec Counting words
13577 The standard Emacs distribution contains functions for counting the
13578 number of lines and words within a region.
13580 Certain types of writing ask you to count words. Thus, if you write
13581 an essay, you may be limited to 800 words; if you write a novel, you
13582 may discipline yourself to write 1000 words a day. It seems odd, but
13583 for a long time, Emacs lacked a word count command. Perhaps people used
13584 Emacs mostly for code or types of documentation that did not require
13585 word counts; or perhaps they restricted themselves to the operating
13586 system word count command, @code{wc}. Alternatively, people may have
13587 followed the publishers' convention and computed a word count by
13588 dividing the number of characters in a document by five.
13590 There are many ways to implement a command to count words. Here are
13591 some examples, which you may wish to compare with the standard Emacs
13592 command, @code{count-words-region}.
13594 @node @value{COUNT-WORDS}
13595 @section The @code{@value{COUNT-WORDS}} Function
13596 @findex @value{COUNT-WORDS}
13598 A word count command could count words in a line, paragraph, region,
13599 or buffer. What should the command cover? You could design the
13600 command to count the number of words in a complete buffer. However,
13601 the Emacs tradition encourages flexibility---you may want to count
13602 words in just a section, rather than all of a buffer. So it makes
13603 more sense to design the command to count the number of words in a
13604 region. Once you have a command to count words in a region, you can,
13605 if you wish, count words in a whole buffer by marking it with
13606 @w{@kbd{C-x h}} (@code{mark-whole-buffer}).
13608 Clearly, counting words is a repetitive act: starting from the
13609 beginning of the region, you count the first word, then the second
13610 word, then the third word, and so on, until you reach the end of the
13611 region. This means that word counting is ideally suited to recursion
13612 or to a @code{while} loop.
13615 * Design @value{COUNT-WORDS}:: The definition using a @code{while} loop.
13616 * Whitespace Bug:: The Whitespace Bug in @code{@value{COUNT-WORDS}}.
13620 @node Design @value{COUNT-WORDS}
13621 @unnumberedsubsec Designing @code{@value{COUNT-WORDS}}
13624 First, we will implement the word count command with a @code{while}
13625 loop, then with recursion. The command will, of course, be
13629 The template for an interactive function definition is, as always:
13633 (defun @var{name-of-function} (@var{argument-list})
13634 "@var{documentation}@dots{}"
13635 (@var{interactive-expression}@dots{})
13640 What we need to do is fill in the slots.
13642 The name of the function should be self-explanatory and similar to the
13643 existing @code{count-lines-region} name. This makes the name easier
13644 to remember. @code{count-words-region} is the obvious choice. Since
13645 that name is now used for the standard Emacs command to count words, we
13646 will name our implementation @code{@value{COUNT-WORDS}}.
13648 The function counts words within a region. This means that the
13649 argument list must contain symbols that are bound to the two
13650 positions, the beginning and end of the region. These two positions
13651 can be called @samp{beginning} and @samp{end} respectively. The first
13652 line of the documentation should be a single sentence, since that is
13653 all that is printed as documentation by a command such as
13654 @code{apropos}. The interactive expression will be of the form
13655 @samp{(interactive "r")}, since that will cause Emacs to pass the
13656 beginning and end of the region to the function's argument list. All
13659 The body of the function needs to be written to do three tasks:
13660 first, to set up conditions under which the @code{while} loop can
13661 count words, second, to run the @code{while} loop, and third, to send
13662 a message to the user.
13664 When a user calls @code{@value{COUNT-WORDS}}, point may be at the
13665 beginning or the end of the region. However, the counting process
13666 must start at the beginning of the region. This means we will want
13667 to put point there if it is not already there. Executing
13668 @code{(goto-char beginning)} ensures this. Of course, we will want to
13669 return point to its expected position when the function finishes its
13670 work. For this reason, the body must be enclosed in a
13671 @code{save-excursion} expression.
13673 The central part of the body of the function consists of a
13674 @code{while} loop in which one expression jumps point forward word by
13675 word, and another expression counts those jumps. The true-or-false-test
13676 of the @code{while} loop should test true so long as point should jump
13677 forward, and false when point is at the end of the region.
13679 We could use @code{(forward-word 1)} as the expression for moving point
13680 forward word by word, but it is easier to see what Emacs identifies as a
13681 ``word'' if we use a regular expression search.
13683 A regular expression search that finds the pattern for which it is
13684 searching leaves point after the last character matched. This means
13685 that a succession of successful word searches will move point forward
13688 As a practical matter, we want the regular expression search to jump
13689 over whitespace and punctuation between words as well as over the
13690 words themselves. A regexp that refuses to jump over interword
13691 whitespace would never jump more than one word! This means that
13692 the regexp should include the whitespace and punctuation that follows
13693 a word, if any, as well as the word itself. (A word may end a buffer
13694 and not have any following whitespace or punctuation, so that part of
13695 the regexp must be optional.)
13697 Thus, what we want for the regexp is a pattern defining one or more
13698 word constituent characters followed, optionally, by one or more
13699 characters that are not word constituents. The regular expression for
13707 The buffer's syntax table determines which characters are and are not
13708 word constituents. For more information about syntax,
13709 @pxref{Syntax Tables, , Syntax Tables, elisp, The GNU Emacs Lisp
13713 The search expression looks like this:
13716 (re-search-forward "\\w+\\W*")
13720 (Note that paired backslashes precede the @samp{w} and @samp{W}. A
13721 single backslash has special meaning to the Emacs Lisp interpreter.
13722 It indicates that the following character is interpreted differently
13723 than usual. For example, the two characters, @samp{\n}, stand for
13724 @samp{newline}, rather than for a backslash followed by @samp{n}. Two
13725 backslashes in a row stand for an ordinary, unspecial backslash, so
13726 Emacs Lisp interpreter ends of seeing a single backslash followed by a
13727 letter. So it discovers the letter is special.)
13729 We need a counter to count how many words there are; this variable
13730 must first be set to 0 and then incremented each time Emacs goes
13731 around the @code{while} loop. The incrementing expression is simply:
13734 (setq count (1+ count))
13737 Finally, we want to tell the user how many words there are in the
13738 region. The @code{message} function is intended for presenting this
13739 kind of information to the user. The message has to be phrased so
13740 that it reads properly regardless of how many words there are in the
13741 region: we don't want to say that ``there are 1 words in the region''.
13742 The conflict between singular and plural is ungrammatical. We can
13743 solve this problem by using a conditional expression that evaluates
13744 different messages depending on the number of words in the region.
13745 There are three possibilities: no words in the region, one word in the
13746 region, and more than one word. This means that the @code{cond}
13747 special form is appropriate.
13750 All this leads to the following function definition:
13754 ;;; @r{First version; has bugs!}
13755 (defun @value{COUNT-WORDS} (beginning end)
13756 "Print number of words in the region.
13757 Words are defined as at least one word-constituent
13758 character followed by at least one character that
13759 is not a word-constituent. The buffer's syntax
13760 table determines which characters these are."
13762 (message "Counting words in region ... ")
13766 ;;; @r{1. Set up appropriate conditions.}
13768 (goto-char beginning)
13773 ;;; @r{2. Run the} while @r{loop.}
13774 (while (< (point) end)
13775 (re-search-forward "\\w+\\W*")
13776 (setq count (1+ count)))
13780 ;;; @r{3. Send a message to the user.}
13781 (cond ((zerop count)
13783 "The region does NOT have any words."))
13786 "The region has 1 word."))
13789 "The region has %d words." count))))))
13794 As written, the function works, but not in all circumstances.
13796 @node Whitespace Bug
13797 @subsection The Whitespace Bug in @code{@value{COUNT-WORDS}}
13799 The @code{@value{COUNT-WORDS}} command described in the preceding
13800 section has two bugs, or rather, one bug with two manifestations.
13801 First, if you mark a region containing only whitespace in the middle
13802 of some text, the @code{@value{COUNT-WORDS}} command tells you that the
13803 region contains one word! Second, if you mark a region containing
13804 only whitespace at the end of the buffer or the accessible portion of
13805 a narrowed buffer, the command displays an error message that looks
13809 Search failed: "\\w+\\W*"
13812 If you are reading this in Info in GNU Emacs, you can test for these
13815 First, evaluate the function in the usual manner to install it.
13817 Here is a copy of the definition. Place your cursor after the closing
13818 parenthesis and type @kbd{C-x C-e} to install it.
13822 ;; @r{First version; has bugs!}
13823 (defun @value{COUNT-WORDS} (beginning end)
13824 "Print number of words in the region.
13825 Words are defined as at least one word-constituent character followed
13826 by at least one character that is not a word-constituent. The buffer's
13827 syntax table determines which characters these are."
13831 (message "Counting words in region ... ")
13835 ;;; @r{1. Set up appropriate conditions.}
13837 (goto-char beginning)
13842 ;;; @r{2. Run the} while @r{loop.}
13843 (while (< (point) end)
13844 (re-search-forward "\\w+\\W*")
13845 (setq count (1+ count)))
13849 ;;; @r{3. Send a message to the user.}
13850 (cond ((zerop count)
13851 (message "The region does NOT have any words."))
13852 ((= 1 count) (message "The region has 1 word."))
13853 (t (message "The region has %d words." count))))))
13859 If you wish, you can also install this keybinding by evaluating it:
13862 (global-set-key "\C-c=" '@value{COUNT-WORDS})
13865 To conduct the first test, set mark and point to the beginning and end
13866 of the following line and then type @kbd{C-c =} (or @kbd{M-x
13867 @value{COUNT-WORDS}} if you have not bound @kbd{C-c =}):
13874 Emacs will tell you, correctly, that the region has three words.
13876 Repeat the test, but place mark at the beginning of the line and place
13877 point just @emph{before} the word @samp{one}. Again type the command
13878 @kbd{C-c =} (or @kbd{M-x @value{COUNT-WORDS}}). Emacs should tell you
13879 that the region has no words, since it is composed only of the
13880 whitespace at the beginning of the line. But instead Emacs tells you
13881 that the region has one word!
13883 For the third test, copy the sample line to the end of the
13884 @file{*scratch*} buffer and then type several spaces at the end of the
13885 line. Place mark right after the word @samp{three} and point at the
13886 end of line. (The end of the line will be the end of the buffer.)
13887 Type @kbd{C-c =} (or @kbd{M-x @value{COUNT-WORDS}}) as you did before.
13888 Again, Emacs should tell you that the region has no words, since it is
13889 composed only of the whitespace at the end of the line. Instead,
13890 Emacs displays an error message saying @samp{Search failed}.
13892 The two bugs stem from the same problem.
13894 Consider the first manifestation of the bug, in which the command
13895 tells you that the whitespace at the beginning of the line contains
13896 one word. What happens is this: The @code{M-x @value{COUNT-WORDS}}
13897 command moves point to the beginning of the region. The @code{while}
13898 tests whether the value of point is smaller than the value of
13899 @code{end}, which it is. Consequently, the regular expression search
13900 looks for and finds the first word. It leaves point after the word.
13901 @code{count} is set to one. The @code{while} loop repeats; but this
13902 time the value of point is larger than the value of @code{end}, the
13903 loop is exited; and the function displays a message saying the number
13904 of words in the region is one. In brief, the regular expression
13905 search looks for and finds the word even though it is outside
13908 In the second manifestation of the bug, the region is whitespace at
13909 the end of the buffer. Emacs says @samp{Search failed}. What happens
13910 is that the true-or-false-test in the @code{while} loop tests true, so
13911 the search expression is executed. But since there are no more words
13912 in the buffer, the search fails.
13914 In both manifestations of the bug, the search extends or attempts to
13915 extend outside of the region.
13917 The solution is to limit the search to the region---this is a fairly
13918 simple action, but as you may have come to expect, it is not quite as
13919 simple as you might think.
13921 As we have seen, the @code{re-search-forward} function takes a search
13922 pattern as its first argument. But in addition to this first,
13923 mandatory argument, it accepts three optional arguments. The optional
13924 second argument bounds the search. The optional third argument, if
13925 @code{t}, causes the function to return @code{nil} rather than signal
13926 an error if the search fails. The optional fourth argument is a
13927 repeat count. (In Emacs, you can see a function's documentation by
13928 typing @kbd{C-h f}, the name of the function, and then @key{RET}.)
13930 In the @code{@value{COUNT-WORDS}} definition, the value of the end of
13931 the region is held by the variable @code{end} which is passed as an
13932 argument to the function. Thus, we can add @code{end} as an argument
13933 to the regular expression search expression:
13936 (re-search-forward "\\w+\\W*" end)
13939 However, if you make only this change to the @code{@value{COUNT-WORDS}}
13940 definition and then test the new version of the definition on a
13941 stretch of whitespace, you will receive an error message saying
13942 @samp{Search failed}.
13944 What happens is this: the search is limited to the region, and fails
13945 as you expect because there are no word-constituent characters in the
13946 region. Since it fails, we receive an error message. But we do not
13947 want to receive an error message in this case; we want to receive the
13948 message ``The region does NOT have any words.''
13950 The solution to this problem is to provide @code{re-search-forward}
13951 with a third argument of @code{t}, which causes the function to return
13952 @code{nil} rather than signal an error if the search fails.
13954 However, if you make this change and try it, you will see the message
13955 ``Counting words in region ... '' and @dots{} you will keep on seeing
13956 that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}).
13958 Here is what happens: the search is limited to the region, as before,
13959 and it fails because there are no word-constituent characters in the
13960 region, as expected. Consequently, the @code{re-search-forward}
13961 expression returns @code{nil}. It does nothing else. In particular,
13962 it does not move point, which it does as a side effect if it finds the
13963 search target. After the @code{re-search-forward} expression returns
13964 @code{nil}, the next expression in the @code{while} loop is evaluated.
13965 This expression increments the count. Then the loop repeats. The
13966 true-or-false-test tests true because the value of point is still less
13967 than the value of end, since the @code{re-search-forward} expression
13968 did not move point. @dots{} and the cycle repeats @dots{}
13970 The @code{@value{COUNT-WORDS}} definition requires yet another
13971 modification, to cause the true-or-false-test of the @code{while} loop
13972 to test false if the search fails. Put another way, there are two
13973 conditions that must be satisfied in the true-or-false-test before the
13974 word count variable is incremented: point must still be within the
13975 region and the search expression must have found a word to count.
13977 Since both the first condition and the second condition must be true
13978 together, the two expressions, the region test and the search
13979 expression, can be joined with an @code{and} special form and embedded in
13980 the @code{while} loop as the true-or-false-test, like this:
13983 (and (< (point) end) (re-search-forward "\\w+\\W*" end t))
13986 @c colon in printed section title causes problem in Info cross reference
13987 @c also trouble with an overfull hbox
13990 (For information about @code{and}, see
13991 @ref{kill-new function, , The @code{kill-new} function}.)
13995 (@xref{kill-new function, , The @code{kill-new} function}, for
13996 information about @code{and}.)
13999 The @code{re-search-forward} expression returns @code{t} if the search
14000 succeeds and as a side effect moves point. Consequently, as words are
14001 found, point is moved through the region. When the search expression
14002 fails to find another word, or when point reaches the end of the
14003 region, the true-or-false-test tests false, the @code{while} loop
14004 exits, and the @code{@value{COUNT-WORDS}} function displays one or
14005 other of its messages.
14007 After incorporating these final changes, the @code{@value{COUNT-WORDS}}
14008 works without bugs (or at least, without bugs that I have found!).
14009 Here is what it looks like:
14013 ;;; @r{Final version:} @code{while}
14014 (defun @value{COUNT-WORDS} (beginning end)
14015 "Print number of words in the region."
14017 (message "Counting words in region ... ")
14021 ;;; @r{1. Set up appropriate conditions.}
14024 (goto-char beginning)
14028 ;;; @r{2. Run the} while @r{loop.}
14029 (while (and (< (point) end)
14030 (re-search-forward "\\w+\\W*" end t))
14031 (setq count (1+ count)))
14035 ;;; @r{3. Send a message to the user.}
14036 (cond ((zerop count)
14038 "The region does NOT have any words."))
14041 "The region has 1 word."))
14044 "The region has %d words." count))))))
14048 @node recursive-count-words
14049 @section Count Words Recursively
14050 @cindex Count words recursively
14051 @cindex Recursively counting words
14052 @cindex Words, counted recursively
14054 You can write the function for counting words recursively as well as
14055 with a @code{while} loop. Let's see how this is done.
14057 First, we need to recognize that the @code{@value{COUNT-WORDS}}
14058 function has three jobs: it sets up the appropriate conditions for
14059 counting to occur; it counts the words in the region; and it sends a
14060 message to the user telling how many words there are.
14062 If we write a single recursive function to do everything, we will
14063 receive a message for every recursive call. If the region contains 13
14064 words, we will receive thirteen messages, one right after the other.
14065 We don't want this! Instead, we must write two functions to do the
14066 job, one of which (the recursive function) will be used inside of the
14067 other. One function will set up the conditions and display the
14068 message; the other will return the word count.
14070 Let us start with the function that causes the message to be displayed.
14071 We can continue to call this @code{@value{COUNT-WORDS}}.
14073 This is the function that the user will call. It will be interactive.
14074 Indeed, it will be similar to our previous versions of this
14075 function, except that it will call @code{recursive-count-words} to
14076 determine how many words are in the region.
14079 We can readily construct a template for this function, based on our
14084 ;; @r{Recursive version; uses regular expression search}
14085 (defun @value{COUNT-WORDS} (beginning end)
14086 "@var{documentation}@dots{}"
14087 (@var{interactive-expression}@dots{})
14091 ;;; @r{1. Set up appropriate conditions.}
14092 (@var{explanatory message})
14093 (@var{set-up functions}@dots{}
14097 ;;; @r{2. Count the words.}
14098 @var{recursive call}
14102 ;;; @r{3. Send a message to the user.}
14103 @var{message providing word count}))
14107 The definition looks straightforward, except that somehow the count
14108 returned by the recursive call must be passed to the message
14109 displaying the word count. A little thought suggests that this can be
14110 done by making use of a @code{let} expression: we can bind a variable
14111 in the varlist of a @code{let} expression to the number of words in
14112 the region, as returned by the recursive call; and then the
14113 @code{cond} expression, using binding, can display the value to the
14116 Often, one thinks of the binding within a @code{let} expression as
14117 somehow secondary to the primary work of a function. But in this
14118 case, what you might consider the primary job of the function,
14119 counting words, is done within the @code{let} expression.
14122 Using @code{let}, the function definition looks like this:
14126 (defun @value{COUNT-WORDS} (beginning end)
14127 "Print number of words in the region."
14132 ;;; @r{1. Set up appropriate conditions.}
14133 (message "Counting words in region ... ")
14135 (goto-char beginning)
14139 ;;; @r{2. Count the words.}
14140 (let ((count (recursive-count-words end)))
14144 ;;; @r{3. Send a message to the user.}
14145 (cond ((zerop count)
14147 "The region does NOT have any words."))
14150 "The region has 1 word."))
14153 "The region has %d words." count))))))
14157 Next, we need to write the recursive counting function.
14159 A recursive function has at least three parts: the do-again-test, the
14160 next-step-expression, and the recursive call.
14162 The do-again-test determines whether the function will or will not be
14163 called again. Since we are counting words in a region and can use a
14164 function that moves point forward for every word, the do-again-test
14165 can check whether point is still within the region. The do-again-test
14166 should find the value of point and determine whether point is before,
14167 at, or after the value of the end of the region. We can use the
14168 @code{point} function to locate point. Clearly, we must pass the
14169 value of the end of the region to the recursive counting function as an
14172 In addition, the do-again-test should also test whether the search finds a
14173 word. If it does not, the function should not call itself again.
14175 The next-step-expression changes a value so that when the recursive
14176 function is supposed to stop calling itself, it stops. More
14177 precisely, the next-step-expression changes a value so that at the
14178 right time, the do-again-test stops the recursive function from
14179 calling itself again. In this case, the next-step-expression can be
14180 the expression that moves point forward, word by word.
14182 The third part of a recursive function is the recursive call.
14184 Somewhere, also, we also need a part that does the work of the
14185 function, a part that does the counting. A vital part!
14188 But already, we have an outline of the recursive counting function:
14192 (defun recursive-count-words (region-end)
14193 "@var{documentation}@dots{}"
14194 @var{do-again-test}
14195 @var{next-step-expression}
14196 @var{recursive call})
14200 Now we need to fill in the slots. Let's start with the simplest cases
14201 first: if point is at or beyond the end of the region, there cannot
14202 be any words in the region, so the function should return zero.
14203 Likewise, if the search fails, there are no words to count, so the
14204 function should return zero.
14206 On the other hand, if point is within the region and the search
14207 succeeds, the function should call itself again.
14210 Thus, the do-again-test should look like this:
14214 (and (< (point) region-end)
14215 (re-search-forward "\\w+\\W*" region-end t))
14219 Note that the search expression is part of the do-again-test---the
14220 function returns @code{t} if its search succeeds and @code{nil} if it
14221 fails. (@xref{Whitespace Bug, , The Whitespace Bug in
14222 @code{@value{COUNT-WORDS}}}, for an explanation of how
14223 @code{re-search-forward} works.)
14225 The do-again-test is the true-or-false test of an @code{if} clause.
14226 Clearly, if the do-again-test succeeds, the then-part of the @code{if}
14227 clause should call the function again; but if it fails, the else-part
14228 should return zero since either point is outside the region or the
14229 search failed because there were no words to find.
14231 But before considering the recursive call, we need to consider the
14232 next-step-expression. What is it? Interestingly, it is the search
14233 part of the do-again-test.
14235 In addition to returning @code{t} or @code{nil} for the
14236 do-again-test, @code{re-search-forward} moves point forward as a side
14237 effect of a successful search. This is the action that changes the
14238 value of point so that the recursive function stops calling itself
14239 when point completes its movement through the region. Consequently,
14240 the @code{re-search-forward} expression is the next-step-expression.
14243 In outline, then, the body of the @code{recursive-count-words}
14244 function looks like this:
14248 (if @var{do-again-test-and-next-step-combined}
14250 @var{recursive-call-returning-count}
14256 How to incorporate the mechanism that counts?
14258 If you are not used to writing recursive functions, a question like
14259 this can be troublesome. But it can and should be approached
14262 We know that the counting mechanism should be associated in some way
14263 with the recursive call. Indeed, since the next-step-expression moves
14264 point forward by one word, and since a recursive call is made for
14265 each word, the counting mechanism must be an expression that adds one
14266 to the value returned by a call to @code{recursive-count-words}.
14269 Consider several cases:
14273 If there are two words in the region, the function should return
14274 a value resulting from adding one to the value returned when it counts
14275 the first word, plus the number returned when it counts the remaining
14276 words in the region, which in this case is one.
14279 If there is one word in the region, the function should return
14280 a value resulting from adding one to the value returned when it counts
14281 that word, plus the number returned when it counts the remaining
14282 words in the region, which in this case is zero.
14285 If there are no words in the region, the function should return zero.
14288 From the sketch we can see that the else-part of the @code{if} returns
14289 zero for the case of no words. This means that the then-part of the
14290 @code{if} must return a value resulting from adding one to the value
14291 returned from a count of the remaining words.
14294 The expression will look like this, where @code{1+} is a function that
14295 adds one to its argument.
14298 (1+ (recursive-count-words region-end))
14302 The whole @code{recursive-count-words} function will then look like
14307 (defun recursive-count-words (region-end)
14308 "@var{documentation}@dots{}"
14310 ;;; @r{1. do-again-test}
14311 (if (and (< (point) region-end)
14312 (re-search-forward "\\w+\\W*" region-end t))
14316 ;;; @r{2. then-part: the recursive call}
14317 (1+ (recursive-count-words region-end))
14319 ;;; @r{3. else-part}
14325 Let's examine how this works:
14327 If there are no words in the region, the else part of the @code{if}
14328 expression is evaluated and consequently the function returns zero.
14330 If there is one word in the region, the value of point is less than
14331 the value of @code{region-end} and the search succeeds. In this case,
14332 the true-or-false-test of the @code{if} expression tests true, and the
14333 then-part of the @code{if} expression is evaluated. The counting
14334 expression is evaluated. This expression returns a value (which will
14335 be the value returned by the whole function) that is the sum of one
14336 added to the value returned by a recursive call.
14338 Meanwhile, the next-step-expression has caused point to jump over the
14339 first (and in this case only) word in the region. This means that
14340 when @code{(recursive-count-words region-end)} is evaluated a second
14341 time, as a result of the recursive call, the value of point will be
14342 equal to or greater than the value of region end. So this time,
14343 @code{recursive-count-words} will return zero. The zero will be added
14344 to one, and the original evaluation of @code{recursive-count-words}
14345 will return one plus zero, which is one, which is the correct amount.
14347 Clearly, if there are two words in the region, the first call to
14348 @code{recursive-count-words} returns one added to the value returned
14349 by calling @code{recursive-count-words} on a region containing the
14350 remaining word---that is, it adds one to one, producing two, which is
14351 the correct amount.
14353 Similarly, if there are three words in the region, the first call to
14354 @code{recursive-count-words} returns one added to the value returned
14355 by calling @code{recursive-count-words} on a region containing the
14356 remaining two words---and so on and so on.
14360 With full documentation the two functions look like this:
14364 The recursive function:
14366 @findex recursive-count-words
14369 (defun recursive-count-words (region-end)
14370 "Number of words between point and REGION-END."
14374 ;;; @r{1. do-again-test}
14375 (if (and (< (point) region-end)
14376 (re-search-forward "\\w+\\W*" region-end t))
14380 ;;; @r{2. then-part: the recursive call}
14381 (1+ (recursive-count-words region-end))
14383 ;;; @r{3. else-part}
14394 ;;; @r{Recursive version}
14395 (defun @value{COUNT-WORDS} (beginning end)
14396 "Print number of words in the region.
14400 Words are defined as at least one word-constituent
14401 character followed by at least one character that is
14402 not a word-constituent. The buffer's syntax table
14403 determines which characters these are."
14407 (message "Counting words in region ... ")
14409 (goto-char beginning)
14410 (let ((count (recursive-count-words end)))
14413 (cond ((zerop count)
14415 "The region does NOT have any words."))
14419 (message "The region has 1 word."))
14422 "The region has %d words." count))))))
14426 @node Counting Exercise
14427 @section Exercise: Counting Punctuation
14429 Using a @code{while} loop, write a function to count the number of
14430 punctuation marks in a region---period, comma, semicolon, colon,
14431 exclamation mark, and question mark. Do the same using recursion.
14433 @node Words in a defun
14434 @chapter Counting Words in a @code{defun}
14435 @cindex Counting words in a @code{defun}
14436 @cindex Word counting in a @code{defun}
14438 Our next project is to count the number of words in a function
14439 definition. Clearly, this can be done using some variant of
14440 @code{@value{COUNT-WORDS}}. @xref{Counting Words, , Counting via
14441 Repetition and Regexps}. If we are just going to count the words in
14442 one definition, it is easy enough to mark the definition with the
14443 @kbd{C-M-h} (@code{mark-defun}) command, and then call
14444 @code{@value{COUNT-WORDS}}.
14446 However, I am more ambitious: I want to count the words and symbols in
14447 every definition in the Emacs sources and then print a graph that
14448 shows how many functions there are of each length: how many contain 40
14449 to 49 words or symbols, how many contain 50 to 59 words or symbols,
14450 and so on. I have often been curious how long a typical function is,
14451 and this will tell.
14454 * Divide and Conquer::
14455 * Words and Symbols:: What to count?
14456 * Syntax:: What constitutes a word or symbol?
14457 * count-words-in-defun:: Very like @code{@value{COUNT-WORDS}}.
14458 * Several defuns:: Counting several defuns in a file.
14459 * Find a File:: Do you want to look at a file?
14460 * lengths-list-file:: A list of the lengths of many definitions.
14461 * Several files:: Counting in definitions in different files.
14462 * Several files recursively:: Recursively counting in different files.
14463 * Prepare the data:: Prepare the data for display in a graph.
14467 @node Divide and Conquer
14468 @unnumberedsec Divide and Conquer
14471 Described in one phrase, the histogram project is daunting; but
14472 divided into numerous small steps, each of which we can take one at a
14473 time, the project becomes less fearsome. Let us consider what the
14478 First, write a function to count the words in one definition. This
14479 includes the problem of handling symbols as well as words.
14482 Second, write a function to list the numbers of words in each function
14483 in a file. This function can use the @code{count-words-in-defun}
14487 Third, write a function to list the numbers of words in each function
14488 in each of several files. This entails automatically finding the
14489 various files, switching to them, and counting the words in the
14490 definitions within them.
14493 Fourth, write a function to convert the list of numbers that we
14494 created in step three to a form that will be suitable for printing as
14498 Fifth, write a function to print the results as a graph.
14501 This is quite a project! But if we take each step slowly, it will not
14504 @node Words and Symbols
14505 @section What to Count?
14506 @cindex Words and symbols in defun
14508 When we first start thinking about how to count the words in a
14509 function definition, the first question is (or ought to be) what are
14510 we going to count? When we speak of ``words'' with respect to a Lisp
14511 function definition, we are actually speaking, in large part, of
14512 symbols. For example, the following @code{multiply-by-seven}
14513 function contains the five symbols @code{defun},
14514 @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In
14515 addition, in the documentation string, it contains the four words
14516 @samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The
14517 symbol @samp{number} is repeated, so the definition contains a total
14518 of ten words and symbols.
14522 (defun multiply-by-seven (number)
14523 "Multiply NUMBER by seven."
14529 However, if we mark the @code{multiply-by-seven} definition with
14530 @kbd{C-M-h} (@code{mark-defun}), and then call
14531 @code{@value{COUNT-WORDS}} on it, we will find that
14532 @code{@value{COUNT-WORDS}} claims the definition has eleven words, not
14533 ten! Something is wrong!
14535 The problem is twofold: @code{@value{COUNT-WORDS}} does not count the
14536 @samp{*} as a word, and it counts the single symbol,
14537 @code{multiply-by-seven}, as containing three words. The hyphens are
14538 treated as if they were interword spaces rather than intraword
14539 connectors: @samp{multiply-by-seven} is counted as if it were written
14540 @samp{multiply by seven}.
14542 The cause of this confusion is the regular expression search within
14543 the @code{@value{COUNT-WORDS}} definition that moves point forward word
14544 by word. In the canonical version of @code{@value{COUNT-WORDS}}, the
14552 This regular expression is a pattern defining one or more word
14553 constituent characters possibly followed by one or more characters
14554 that are not word constituents. What is meant by ``word constituent
14555 characters'' brings us to the issue of syntax, which is worth a section
14559 @section What Constitutes a Word or Symbol?
14560 @cindex Syntax categories and tables
14562 Emacs treats different characters as belonging to different
14563 @dfn{syntax categories}. For example, the regular expression,
14564 @samp{\\w+}, is a pattern specifying one or more @emph{word
14565 constituent} characters. Word constituent characters are members of
14566 one syntax category. Other syntax categories include the class of
14567 punctuation characters, such as the period and the comma, and the
14568 class of whitespace characters, such as the blank space and the tab
14569 character. (For more information, @pxref{Syntax Tables, , Syntax
14570 Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
14572 Syntax tables specify which characters belong to which categories.
14573 Usually, a hyphen is not specified as a word constituent character.
14574 Instead, it is specified as being in the class of characters that are
14575 part of symbol names but not words. This means that the
14576 @code{@value{COUNT-WORDS}} function treats it in the same way it treats
14577 an interword white space, which is why @code{@value{COUNT-WORDS}}
14578 counts @samp{multiply-by-seven} as three words.
14580 There are two ways to cause Emacs to count @samp{multiply-by-seven} as
14581 one symbol: modify the syntax table or modify the regular expression.
14583 We could redefine a hyphen as a word constituent character by
14584 modifying the syntax table that Emacs keeps for each mode. This
14585 action would serve our purpose, except that a hyphen is merely the
14586 most common character within symbols that is not typically a word
14587 constituent character; there are others, too.
14589 Alternatively, we can redefine the regexp used in the
14590 @code{@value{COUNT-WORDS}} definition so as to include symbols. This
14591 procedure has the merit of clarity, but the task is a little tricky.
14594 The first part is simple enough: the pattern must match at least one
14595 character that is a word or symbol constituent. Thus:
14598 "\\(\\w\\|\\s_\\)+"
14602 The @samp{\\(} is the first part of the grouping construct that
14603 includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated
14604 by the @samp{\\|}. The @samp{\\w} matches any word-constituent
14605 character and the @samp{\\s_} matches any character that is part of a
14606 symbol name but not a word-constituent character. The @samp{+}
14607 following the group indicates that the word or symbol constituent
14608 characters must be matched at least once.
14610 However, the second part of the regexp is more difficult to design.
14611 What we want is to follow the first part with optionally one or more
14612 characters that are not constituents of a word or symbol. At first,
14613 I thought I could define this with the following:
14616 "\\(\\W\\|\\S_\\)*"
14620 The upper case @samp{W} and @samp{S} match characters that are
14621 @emph{not} word or symbol constituents. Unfortunately, this
14622 expression matches any character that is either not a word constituent
14623 or not a symbol constituent. This matches any character!
14625 I then noticed that every word or symbol in my test region was
14626 followed by white space (blank space, tab, or newline). So I tried
14627 placing a pattern to match one or more blank spaces after the pattern
14628 for one or more word or symbol constituents. This failed, too. Words
14629 and symbols are often separated by whitespace, but in actual code
14630 parentheses may follow symbols and punctuation may follow words. So
14631 finally, I designed a pattern in which the word or symbol constituents
14632 are followed optionally by characters that are not white space and
14633 then followed optionally by white space.
14636 Here is the full regular expression:
14639 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14642 @node count-words-in-defun
14643 @section The @code{count-words-in-defun} Function
14644 @cindex Counting words in a @code{defun}
14646 We have seen that there are several ways to write a
14647 @code{count-words-region} function. To write a
14648 @code{count-words-in-defun}, we need merely adapt one of these
14651 The version that uses a @code{while} loop is easy to understand, so I
14652 am going to adapt that. Because @code{count-words-in-defun} will be
14653 part of a more complex program, it need not be interactive and it need
14654 not display a message but just return the count. These considerations
14655 simplify the definition a little.
14657 On the other hand, @code{count-words-in-defun} will be used within a
14658 buffer that contains function definitions. Consequently, it is
14659 reasonable to ask that the function determine whether it is called
14660 when point is within a function definition, and if it is, to return
14661 the count for that definition. This adds complexity to the
14662 definition, but saves us from needing to pass arguments to the
14666 These considerations lead us to prepare the following template:
14670 (defun count-words-in-defun ()
14671 "@var{documentation}@dots{}"
14672 (@var{set up}@dots{}
14673 (@var{while loop}@dots{})
14674 @var{return count})
14679 As usual, our job is to fill in the slots.
14683 We are presuming that this function will be called within a buffer
14684 containing function definitions. Point will either be within a
14685 function definition or not. For @code{count-words-in-defun} to work,
14686 point must move to the beginning of the definition, a counter must
14687 start at zero, and the counting loop must stop when point reaches the
14688 end of the definition.
14690 The @code{beginning-of-defun} function searches backwards for an
14691 opening delimiter such as a @samp{(} at the beginning of a line, and
14692 moves point to that position, or else to the limit of the search. In
14693 practice, this means that @code{beginning-of-defun} moves point to the
14694 beginning of an enclosing or preceding function definition, or else to
14695 the beginning of the buffer. We can use @code{beginning-of-defun} to
14696 place point where we wish to start.
14698 The @code{while} loop requires a counter to keep track of the words or
14699 symbols being counted. A @code{let} expression can be used to create
14700 a local variable for this purpose, and bind it to an initial value of zero.
14702 The @code{end-of-defun} function works like @code{beginning-of-defun}
14703 except that it moves point to the end of the definition.
14704 @code{end-of-defun} can be used as part of an expression that
14705 determines the position of the end of the definition.
14707 The set up for @code{count-words-in-defun} takes shape rapidly: first
14708 we move point to the beginning of the definition, then we create a
14709 local variable to hold the count, and finally, we record the position
14710 of the end of the definition so the @code{while} loop will know when to stop
14714 The code looks like this:
14718 (beginning-of-defun)
14720 (end (save-excursion (end-of-defun) (point))))
14725 The code is simple. The only slight complication is likely to concern
14726 @code{end}: it is bound to the position of the end of the definition
14727 by a @code{save-excursion} expression that returns the value of point
14728 after @code{end-of-defun} temporarily moves it to the end of the
14731 The second part of the @code{count-words-in-defun}, after the set up,
14732 is the @code{while} loop.
14734 The loop must contain an expression that jumps point forward word by
14735 word and symbol by symbol, and another expression that counts the
14736 jumps. The true-or-false-test for the @code{while} loop should test
14737 true so long as point should jump forward, and false when point is at
14738 the end of the definition. We have already redefined the regular
14739 expression for this, so the loop is straightforward:
14743 (while (and (< (point) end)
14745 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t))
14746 (setq count (1+ count)))
14750 The third part of the function definition returns the count of words
14751 and symbols. This part is the last expression within the body of the
14752 @code{let} expression, and can be, very simply, the local variable
14753 @code{count}, which when evaluated returns the count.
14756 Put together, the @code{count-words-in-defun} definition looks like this:
14758 @findex count-words-in-defun
14761 (defun count-words-in-defun ()
14762 "Return the number of words and symbols in a defun."
14763 (beginning-of-defun)
14765 (end (save-excursion (end-of-defun) (point))))
14769 (and (< (point) end)
14771 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14773 (setq count (1+ count)))
14778 How to test this? The function is not interactive, but it is easy to
14779 put a wrapper around the function to make it interactive; we can use
14780 almost the same code as for the recursive version of
14781 @code{@value{COUNT-WORDS}}:
14785 ;;; @r{Interactive version.}
14786 (defun count-words-defun ()
14787 "Number of words and symbols in a function definition."
14790 "Counting words and symbols in function definition ... ")
14793 (let ((count (count-words-in-defun)))
14797 "The definition does NOT have any words or symbols."))
14802 "The definition has 1 word or symbol."))
14805 "The definition has %d words or symbols." count)))))
14811 Let's re-use @kbd{C-c =} as a convenient keybinding:
14814 (global-set-key "\C-c=" 'count-words-defun)
14817 Now we can try out @code{count-words-defun}: install both
14818 @code{count-words-in-defun} and @code{count-words-defun}, and set the
14819 keybinding, and then place the cursor within the following definition:
14823 (defun multiply-by-seven (number)
14824 "Multiply NUMBER by seven."
14831 Success! The definition has 10 words and symbols.
14833 The next problem is to count the numbers of words and symbols in
14834 several definitions within a single file.
14836 @node Several defuns
14837 @section Count Several @code{defuns} Within a File
14839 A file such as @file{simple.el} may have a hundred or more function
14840 definitions within it. Our long term goal is to collect statistics on
14841 many files, but as a first step, our immediate goal is to collect
14842 statistics on one file.
14844 The information will be a series of numbers, each number being the
14845 length of a function definition. We can store the numbers in a list.
14847 We know that we will want to incorporate the information regarding one
14848 file with information about many other files; this means that the
14849 function for counting definition lengths within one file need only
14850 return the list of lengths. It need not and should not display any
14853 The word count commands contain one expression to jump point forward
14854 word by word and another expression to count the jumps. The function
14855 to return the lengths of definitions can be designed to work the same
14856 way, with one expression to jump point forward definition by
14857 definition and another expression to construct the lengths' list.
14859 This statement of the problem makes it elementary to write the
14860 function definition. Clearly, we will start the count at the
14861 beginning of the file, so the first command will be @code{(goto-char
14862 (point-min))}. Next, we start the @code{while} loop; and the
14863 true-or-false test of the loop can be a regular expression search for
14864 the next function definition---so long as the search succeeds, point
14865 is moved forward and then the body of the loop is evaluated. The body
14866 needs an expression that constructs the lengths' list. @code{cons},
14867 the list construction command, can be used to create the list. That
14868 is almost all there is to it.
14871 Here is what this fragment of code looks like:
14875 (goto-char (point-min))
14876 (while (re-search-forward "^(defun" nil t)
14878 (cons (count-words-in-defun) lengths-list)))
14882 What we have left out is the mechanism for finding the file that
14883 contains the function definitions.
14885 In previous examples, we either used this, the Info file, or we
14886 switched back and forth to some other buffer, such as the
14887 @file{*scratch*} buffer.
14889 Finding a file is a new process that we have not yet discussed.
14892 @section Find a File
14893 @cindex Find a File
14895 To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file})
14896 command. This command is almost, but not quite right for the lengths
14900 Let's look at the source for @code{find-file}:
14904 (defun find-file (filename)
14905 "Edit file FILENAME.
14906 Switch to a buffer visiting file FILENAME,
14907 creating one if none already exists."
14908 (interactive "FFind file: ")
14909 (switch-to-buffer (find-file-noselect filename)))
14914 (The most recent version of the @code{find-file} function definition
14915 permits you to specify optional wildcards to visit multiple files; that
14916 makes the definition more complex and we will not discuss it here,
14917 since it is not relevant. You can see its source using either
14918 @kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).)
14922 (defun find-file (filename &optional wildcards)
14923 "Edit file FILENAME.
14924 Switch to a buffer visiting file FILENAME,
14925 creating one if none already exists.
14926 Interactively, the default if you just type RET is the current directory,
14927 but the visited file name is available through the minibuffer history:
14928 type M-n to pull it into the minibuffer.
14930 Interactively, or if WILDCARDS is non-nil in a call from Lisp,
14931 expand wildcards (if any) and visit multiple files. You can
14932 suppress wildcard expansion by setting `find-file-wildcards' to nil.
14934 To visit a file without any kind of conversion and without
14935 automatically choosing a major mode, use \\[find-file-literally]."
14936 (interactive (find-file-read-args "Find file: " nil))
14937 (let ((value (find-file-noselect filename nil nil wildcards)))
14939 (mapcar 'switch-to-buffer (nreverse value))
14940 (switch-to-buffer value))))
14943 The definition I am showing possesses short but complete documentation
14944 and an interactive specification that prompts you for a file name when
14945 you use the command interactively. The body of the definition
14946 contains two functions, @code{find-file-noselect} and
14947 @code{switch-to-buffer}.
14949 According to its documentation as shown by @kbd{C-h f} (the
14950 @code{describe-function} command), the @code{find-file-noselect}
14951 function reads the named file into a buffer and returns the buffer.
14952 (Its most recent version includes an optional wildcards argument,
14953 too, as well as another to read a file literally and an other you
14954 suppress warning messages. These optional arguments are irrelevant.)
14956 However, the @code{find-file-noselect} function does not select the
14957 buffer in which it puts the file. Emacs does not switch its attention
14958 (or yours if you are using @code{find-file-noselect}) to the selected
14959 buffer. That is what @code{switch-to-buffer} does: it switches the
14960 buffer to which Emacs attention is directed; and it switches the
14961 buffer displayed in the window to the new buffer. We have discussed
14962 buffer switching elsewhere. (@xref{Switching Buffers}.)
14964 In this histogram project, we do not need to display each file on the
14965 screen as the program determines the length of each definition within
14966 it. Instead of employing @code{switch-to-buffer}, we can work with
14967 @code{set-buffer}, which redirects the attention of the computer
14968 program to a different buffer but does not redisplay it on the screen.
14969 So instead of calling on @code{find-file} to do the job, we must write
14970 our own expression.
14972 The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
14974 @node lengths-list-file
14975 @section @code{lengths-list-file} in Detail
14977 The core of the @code{lengths-list-file} function is a @code{while}
14978 loop containing a function to move point forward defun by defun, and
14979 a function to count the number of words and symbols in each defun.
14980 This core must be surrounded by functions that do various other tasks,
14981 including finding the file, and ensuring that point starts out at the
14982 beginning of the file. The function definition looks like this:
14983 @findex lengths-list-file
14987 (defun lengths-list-file (filename)
14988 "Return list of definitions' lengths within FILE.
14989 The returned list is a list of numbers.
14990 Each number is the number of words or
14991 symbols in one function definition."
14994 (message "Working on `%s' ... " filename)
14996 (let ((buffer (find-file-noselect filename))
14998 (set-buffer buffer)
14999 (setq buffer-read-only t)
15001 (goto-char (point-min))
15002 (while (re-search-forward "^(defun" nil t)
15004 (cons (count-words-in-defun) lengths-list)))
15005 (kill-buffer buffer)
15011 The function is passed one argument, the name of the file on which it
15012 will work. It has four lines of documentation, but no interactive
15013 specification. Since people worry that a computer is broken if they
15014 don't see anything going on, the first line of the body is a
15017 The next line contains a @code{save-excursion} that returns Emacs's
15018 attention to the current buffer when the function completes. This is
15019 useful in case you embed this function in another function that
15020 presumes point is restored to the original buffer.
15022 In the varlist of the @code{let} expression, Emacs finds the file and
15023 binds the local variable @code{buffer} to the buffer containing the
15024 file. At the same time, Emacs creates @code{lengths-list} as a local
15027 Next, Emacs switches its attention to the buffer.
15029 In the following line, Emacs makes the buffer read-only. Ideally,
15030 this line is not necessary. None of the functions for counting words
15031 and symbols in a function definition should change the buffer.
15032 Besides, the buffer is not going to be saved, even if it were changed.
15033 This line is entirely the consequence of great, perhaps excessive,
15034 caution. The reason for the caution is that this function and those
15035 it calls work on the sources for Emacs and it is inconvenient if they
15036 are inadvertently modified. It goes without saying that I did not
15037 realize a need for this line until an experiment went awry and started
15038 to modify my Emacs source files @dots{}
15040 Next comes a call to widen the buffer if it is narrowed. This
15041 function is usually not needed---Emacs creates a fresh buffer if none
15042 already exists; but if a buffer visiting the file already exists Emacs
15043 returns that one. In this case, the buffer may be narrowed and must
15044 be widened. If we wanted to be fully user-friendly, we would
15045 arrange to save the restriction and the location of point, but we
15048 The @code{(goto-char (point-min))} expression moves point to the
15049 beginning of the buffer.
15051 Then comes a @code{while} loop in which the work of the function is
15052 carried out. In the loop, Emacs determines the length of each
15053 definition and constructs a lengths' list containing the information.
15055 Emacs kills the buffer after working through it. This is to save
15056 space inside of Emacs. My version of GNU Emacs 19 contained over 300
15057 source files of interest; GNU Emacs 22 contains over a thousand source
15058 files. Another function will apply @code{lengths-list-file} to each
15061 Finally, the last expression within the @code{let} expression is the
15062 @code{lengths-list} variable; its value is returned as the value of
15063 the whole function.
15065 You can try this function by installing it in the usual fashion. Then
15066 place your cursor after the following expression and type @kbd{C-x
15067 C-e} (@code{eval-last-sexp}).
15069 @c !!! 22.1.1 lisp sources location here
15072 "/usr/local/share/emacs/22.1/lisp/emacs-lisp/debug.el")
15076 You may need to change the pathname of the file; the one here is for
15077 GNU Emacs version 22.1. To change the expression, copy it to
15078 the @file{*scratch*} buffer and edit it.
15082 Also, to see the full length of the list, rather than a truncated
15083 version, you may have to evaluate the following:
15084 @c We do not want to insert, so do not mention the zero prefix argument.
15087 (custom-set-variables '(eval-expression-print-length nil))
15091 (@xref{defcustom, , Specifying Variables using @code{defcustom}}.
15092 Then evaluate the @code{lengths-list-file} expression.)
15095 The lengths' list for @file{debug.el} takes less than a second to
15096 produce and looks like this in GNU Emacs 22:
15099 (83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587)
15103 (Using my old machine, the version 19 lengths' list for @file{debug.el}
15104 took seven seconds to produce and looked like this:
15107 (75 41 80 62 20 45 44 68 45 12 34 235)
15111 The newer version of @file{debug.el} contains more defuns than the
15112 earlier one; and my new machine is much faster than the old one.)
15114 Note that the length of the last definition in the file is first in
15117 @node Several files
15118 @section Count Words in @code{defuns} in Different Files
15120 In the previous section, we created a function that returns a list of
15121 the lengths of each definition in a file. Now, we want to define a
15122 function to return a master list of the lengths of the definitions in
15125 Working on each of a list of files is a repetitious act, so we can use
15126 either a @code{while} loop or recursion.
15129 * lengths-list-many-files:: Return a list of the lengths of defuns.
15130 * append:: Attach one list to another.
15134 @node lengths-list-many-files
15135 @unnumberedsubsec Determine the lengths of @code{defuns}
15138 The design using a @code{while} loop is routine. The argument passed
15139 the function is a list of files. As we saw earlier (@pxref{Loop
15140 Example}), you can write a @code{while} loop so that the body of the
15141 loop is evaluated if such a list contains elements, but to exit the
15142 loop if the list is empty. For this design to work, the body of the
15143 loop must contain an expression that shortens the list each time the
15144 body is evaluated, so that eventually the list is empty. The usual
15145 technique is to set the value of the list to the value of the @sc{cdr}
15146 of the list each time the body is evaluated.
15149 The template looks like this:
15153 (while @var{test-whether-list-is-empty}
15155 @var{set-list-to-cdr-of-list})
15159 Also, we remember that a @code{while} loop returns @code{nil} (the
15160 result of evaluating the true-or-false-test), not the result of any
15161 evaluation within its body. (The evaluations within the body of the
15162 loop are done for their side effects.) However, the expression that
15163 sets the lengths' list is part of the body---and that is the value
15164 that we want returned by the function as a whole. To do this, we
15165 enclose the @code{while} loop within a @code{let} expression, and
15166 arrange that the last element of the @code{let} expression contains
15167 the value of the lengths' list. (@xref{Incrementing Example, , Loop
15168 Example with an Incrementing Counter}.)
15170 @findex lengths-list-many-files
15172 These considerations lead us directly to the function itself:
15176 ;;; @r{Use @code{while} loop.}
15177 (defun lengths-list-many-files (list-of-files)
15178 "Return list of lengths of defuns in LIST-OF-FILES."
15181 (let (lengths-list)
15183 ;;; @r{true-or-false-test}
15184 (while list-of-files
15189 ;;; @r{Generate a lengths' list.}
15191 (expand-file-name (car list-of-files)))))
15195 ;;; @r{Make files' list shorter.}
15196 (setq list-of-files (cdr list-of-files)))
15198 ;;; @r{Return final value of lengths' list.}
15203 @code{expand-file-name} is a built-in function that converts a file
15204 name to the absolute, long, path name form. The function employs the
15205 name of the directory in which the function is called.
15207 @c !!! 22.1.1 lisp sources location here
15209 Thus, if @code{expand-file-name} is called on @code{debug.el} when
15210 Emacs is visiting the
15211 @file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory,
15221 @c !!! 22.1.1 lisp sources location here
15223 /usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el
15226 The only other new element of this function definition is the as yet
15227 unstudied function @code{append}, which merits a short section for
15231 @subsection The @code{append} Function
15234 The @code{append} function attaches one list to another. Thus,
15237 (append '(1 2 3 4) '(5 6 7 8))
15248 This is exactly how we want to attach two lengths' lists produced by
15249 @code{lengths-list-file} to each other. The results contrast with
15253 (cons '(1 2 3 4) '(5 6 7 8))
15258 which constructs a new list in which the first argument to @code{cons}
15259 becomes the first element of the new list:
15262 ((1 2 3 4) 5 6 7 8)
15265 @node Several files recursively
15266 @section Recursively Count Words in Different Files
15268 Besides a @code{while} loop, you can work on each of a list of files
15269 with recursion. A recursive version of @code{lengths-list-many-files}
15270 is short and simple.
15272 The recursive function has the usual parts: the do-again-test, the
15273 next-step-expression, and the recursive call. The do-again-test
15274 determines whether the function should call itself again, which it
15275 will do if the @code{list-of-files} contains any remaining elements;
15276 the next-step-expression resets the @code{list-of-files} to the
15277 @sc{cdr} of itself, so eventually the list will be empty; and the
15278 recursive call calls itself on the shorter list. The complete
15279 function is shorter than this description!
15280 @findex recursive-lengths-list-many-files
15284 (defun recursive-lengths-list-many-files (list-of-files)
15285 "Return list of lengths of each defun in LIST-OF-FILES."
15286 (if list-of-files ; @r{do-again-test}
15289 (expand-file-name (car list-of-files)))
15290 (recursive-lengths-list-many-files
15291 (cdr list-of-files)))))
15296 In a sentence, the function returns the lengths' list for the first of
15297 the @code{list-of-files} appended to the result of calling itself on
15298 the rest of the @code{list-of-files}.
15300 Here is a test of @code{recursive-lengths-list-many-files}, along with
15301 the results of running @code{lengths-list-file} on each of the files
15304 Install @code{recursive-lengths-list-many-files} and
15305 @code{lengths-list-file}, if necessary, and then evaluate the
15306 following expressions. You may need to change the files' pathnames;
15307 those here work when this Info file and the Emacs sources are located
15308 in their customary places. To change the expressions, copy them to
15309 the @file{*scratch*} buffer, edit them, and then evaluate them.
15311 The results are shown after the @samp{@result{}}. (These results are
15312 for files from Emacs version 22.1.1; files from other versions of
15313 Emacs may produce different results.)
15315 @c !!! 22.1.1 lisp sources location here
15318 (cd "/usr/local/share/emacs/22.1.1/")
15320 (lengths-list-file "./lisp/macros.el")
15321 @result{} (283 263 480 90)
15325 (lengths-list-file "./lisp/mail/mailalias.el")
15326 @result{} (38 32 29 95 178 180 321 218 324)
15330 (lengths-list-file "./lisp/makesum.el")
15335 (recursive-lengths-list-many-files
15336 '("./lisp/macros.el"
15337 "./lisp/mail/mailalias.el"
15338 "./lisp/makesum.el"))
15339 @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181)
15343 The @code{recursive-lengths-list-many-files} function produces the
15346 The next step is to prepare the data in the list for display in a graph.
15348 @node Prepare the data
15349 @section Prepare the Data for Display in a Graph
15351 The @code{recursive-lengths-list-many-files} function returns a list
15352 of numbers. Each number records the length of a function definition.
15353 What we need to do now is transform this data into a list of numbers
15354 suitable for generating a graph. The new list will tell how many
15355 functions definitions contain less than 10 words and
15356 symbols, how many contain between 10 and 19 words and symbols, how
15357 many contain between 20 and 29 words and symbols, and so on.
15359 In brief, we need to go through the lengths' list produced by the
15360 @code{recursive-lengths-list-many-files} function and count the number
15361 of defuns within each range of lengths, and produce a list of those
15365 * Data for Display in Detail::
15366 * Sorting:: Sorting lists.
15367 * Files List:: Making a list of files.
15368 * Counting function definitions::
15372 @node Data for Display in Detail
15373 @unnumberedsubsec The Data for Display in Detail
15376 Based on what we have done before, we can readily foresee that it
15377 should not be too hard to write a function that @sc{cdr}s down the
15378 lengths' list, looks at each element, determines which length range it
15379 is in, and increments a counter for that range.
15381 However, before beginning to write such a function, we should consider
15382 the advantages of sorting the lengths' list first, so the numbers are
15383 ordered from smallest to largest. First, sorting will make it easier
15384 to count the numbers in each range, since two adjacent numbers will
15385 either be in the same length range or in adjacent ranges. Second, by
15386 inspecting a sorted list, we can discover the highest and lowest
15387 number, and thereby determine the largest and smallest length range
15391 @subsection Sorting Lists
15394 Emacs contains a function to sort lists, called (as you might guess)
15395 @code{sort}. The @code{sort} function takes two arguments, the list
15396 to be sorted, and a predicate that determines whether the first of
15397 two list elements is less than the second.
15399 As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong
15400 Type Object as an Argument}), a predicate is a function that
15401 determines whether some property is true or false. The @code{sort}
15402 function will reorder a list according to whatever property the
15403 predicate uses; this means that @code{sort} can be used to sort
15404 non-numeric lists by non-numeric criteria---it can, for example,
15405 alphabetize a list.
15408 The @code{<} function is used when sorting a numeric list. For example,
15411 (sort '(4 8 21 17 33 7 21 7) '<)
15419 (4 7 7 8 17 21 21 33)
15423 (Note that in this example, both the arguments are quoted so that the
15424 symbols are not evaluated before being passed to @code{sort} as
15427 Sorting the list returned by the
15428 @code{recursive-lengths-list-many-files} function is straightforward;
15429 it uses the @code{<} function:
15433 In GNU Emacs 22, eval
15435 (cd "/usr/local/share/emacs/22.0.50/")
15437 (recursive-lengths-list-many-files
15438 '("./lisp/macros.el"
15439 "./lisp/mail/mailalias.el"
15440 "./lisp/makesum.el"))
15448 (recursive-lengths-list-many-files
15449 '("./lisp/macros.el"
15450 "./lisp/mailalias.el"
15451 "./lisp/makesum.el"))
15461 (29 32 38 85 90 95 178 180 181 218 263 283 321 324 480)
15465 (Note that in this example, the first argument to @code{sort} is not
15466 quoted, since the expression must be evaluated so as to produce the
15467 list that is passed to @code{sort}.)
15470 @subsection Making a List of Files
15472 The @code{recursive-lengths-list-many-files} function requires a list
15473 of files as its argument. For our test examples, we constructed such
15474 a list by hand; but the Emacs Lisp source directory is too large for
15475 us to do for that. Instead, we will write a function to do the job
15476 for us. In this function, we will use both a @code{while} loop and a
15479 @findex directory-files
15480 We did not have to write a function like this for older versions of
15481 GNU Emacs, since they placed all the @samp{.el} files in one
15482 directory. Instead, we were able to use the @code{directory-files}
15483 function, which lists the names of files that match a specified
15484 pattern within a single directory.
15486 However, recent versions of Emacs place Emacs Lisp files in
15487 sub-directories of the top level @file{lisp} directory. This
15488 re-arrangement eases navigation. For example, all the mail related
15489 files are in a @file{lisp} sub-directory called @file{mail}. But at
15490 the same time, this arrangement forces us to create a file listing
15491 function that descends into the sub-directories.
15493 @findex files-in-below-directory
15494 We can create this function, called @code{files-in-below-directory},
15495 using familiar functions such as @code{car}, @code{nthcdr}, and
15496 @code{substring} in conjunction with an existing function called
15497 @code{directory-files-and-attributes}. This latter function not only
15498 lists all the filenames in a directory, including the names
15499 of sub-directories, but also their attributes.
15501 To restate our goal: to create a function that will enable us
15502 to feed filenames to @code{recursive-lengths-list-many-files}
15503 as a list that looks like this (but with more elements):
15507 ("./lisp/macros.el"
15508 "./lisp/mail/rmail.el"
15509 "./lisp/makesum.el")
15513 The @code{directory-files-and-attributes} function returns a list of
15514 lists. Each of the lists within the main list consists of 13
15515 elements. The first element is a string that contains the name of the
15516 file---which, in GNU/Linux, may be a @dfn{directory file}, that is to
15517 say, a file with the special attributes of a directory. The second
15518 element of the list is @code{t} for a directory, a string
15519 for symbolic link (the string is the name linked to), or @code{nil}.
15521 For example, the first @samp{.el} file in the @file{lisp/} directory
15522 is @file{abbrev.el}. Its name is
15523 @file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a
15524 directory or a symbolic link.
15527 This is how @code{directory-files-and-attributes} lists that file and
15539 (20615 27034 579989 697000)
15541 (20615 26327 734791 805000)
15553 On the other hand, @file{mail/} is a directory within the @file{lisp/}
15554 directory. The beginning of its listing looks like this:
15565 (To learn about the different attributes, look at the documentation of
15566 @code{file-attributes}. Bear in mind that the @code{file-attributes}
15567 function does not list the filename, so its first element is
15568 @code{directory-files-and-attributes}'s second element.)
15570 We will want our new function, @code{files-in-below-directory}, to
15571 list the @samp{.el} files in the directory it is told to check, and in
15572 any directories below that directory.
15574 This gives us a hint on how to construct
15575 @code{files-in-below-directory}: within a directory, the function
15576 should add @samp{.el} filenames to a list; and if, within a directory,
15577 the function comes upon a sub-directory, it should go into that
15578 sub-directory and repeat its actions.
15580 However, we should note that every directory contains a name that
15581 refers to itself, called @file{.} (``dot''), and a name that refers to
15582 its parent directory, called @file{..} (``dot dot''). (In
15583 @file{/}, the root directory, @file{..} refers to itself, since
15584 @file{/} has no parent.) Clearly, we do not want our
15585 @code{files-in-below-directory} function to enter those directories,
15586 since they always lead us, directly or indirectly, to the current
15589 Consequently, our @code{files-in-below-directory} function must do
15594 Check to see whether it is looking at a filename that ends in
15595 @samp{.el}; and if so, add its name to a list.
15598 Check to see whether it is looking at a filename that is the name of a
15599 directory; and if so,
15603 Check to see whether it is looking at @file{.} or @file{..}; and if
15607 Or else, go into that directory and repeat the process.
15611 Let's write a function definition to do these tasks. We will use a
15612 @code{while} loop to move from one filename to another within a
15613 directory, checking what needs to be done; and we will use a recursive
15614 call to repeat the actions on each sub-directory. The recursive
15615 pattern is Accumulate
15616 (@pxref{Accumulate}),
15617 using @code{append} as the combiner.
15620 (directory-files "/usr/local/src/emacs/lisp/" t "\\.el$")
15621 (shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'")
15623 (directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$")
15624 (shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'")
15627 @c /usr/local/share/emacs/22.1.1/lisp/
15630 Here is the function:
15634 (defun files-in-below-directory (directory)
15635 "List the .el files in DIRECTORY and in its sub-directories."
15636 ;; Although the function will be used non-interactively,
15637 ;; it will be easier to test if we make it interactive.
15638 ;; The directory will have a name such as
15639 ;; "/usr/local/share/emacs/22.1.1/lisp/"
15640 (interactive "DDirectory name: ")
15643 (let (el-files-list
15644 (current-directory-list
15645 (directory-files-and-attributes directory t)))
15646 ;; while we are in the current directory
15647 (while current-directory-list
15651 ;; check to see whether filename ends in '.el'
15652 ;; and if so, append its name to a list.
15653 ((equal ".el" (substring (car (car current-directory-list)) -3))
15654 (setq el-files-list
15655 (cons (car (car current-directory-list)) el-files-list)))
15658 ;; check whether filename is that of a directory
15659 ((eq t (car (cdr (car current-directory-list))))
15660 ;; decide whether to skip or recurse
15663 (substring (car (car current-directory-list)) -1))
15664 ;; then do nothing since filename is that of
15665 ;; current directory or parent, "." or ".."
15669 ;; else descend into the directory and repeat the process
15670 (setq el-files-list
15672 (files-in-below-directory
15673 (car (car current-directory-list)))
15675 ;; move to the next filename in the list; this also
15676 ;; shortens the list so the while loop eventually comes to an end
15677 (setq current-directory-list (cdr current-directory-list)))
15678 ;; return the filenames
15683 @c (files-in-below-directory "/usr/local/src/emacs/lisp/")
15684 @c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
15686 The @code{files-in-below-directory} @code{directory-files} function
15687 takes one argument, the name of a directory.
15690 Thus, on my system,
15692 @c (length (files-in-below-directory "/usr/local/src/emacs/lisp/"))
15694 @c !!! 22.1.1 lisp sources location here
15698 (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/"))
15703 tells me that in and below my Lisp sources directory are 1031
15706 @code{files-in-below-directory} returns a list in reverse alphabetical
15707 order. An expression to sort the list in alphabetical order looks
15713 (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
15720 "Test how long it takes to find lengths of all sorted elisp defuns."
15721 (insert "\n" (current-time-string) "\n")
15724 (recursive-lengths-list-many-files
15725 (files-in-below-directory "/usr/local/src/emacs/lisp/"))
15727 (insert (format "%s" (current-time-string))))
15730 @node Counting function definitions
15731 @subsection Counting function definitions
15733 Our immediate goal is to generate a list that tells us how many
15734 function definitions contain fewer than 10 words and symbols, how many
15735 contain between 10 and 19 words and symbols, how many contain between
15736 20 and 29 words and symbols, and so on.
15738 With a sorted list of numbers, this is easy: count how many elements
15739 of the list are smaller than 10, then, after moving past the numbers
15740 just counted, count how many are smaller than 20, then, after moving
15741 past the numbers just counted, count how many are smaller than 30, and
15742 so on. Each of the numbers, 10, 20, 30, 40, and the like, is one
15743 larger than the top of that range. We can call the list of such
15744 numbers the @code{top-of-ranges} list.
15747 If we wished, we could generate this list automatically, but it is
15748 simpler to write a list manually. Here it is:
15749 @vindex top-of-ranges
15753 (defvar top-of-ranges
15756 110 120 130 140 150
15757 160 170 180 190 200
15758 210 220 230 240 250
15759 260 270 280 290 300)
15760 "List specifying ranges for `defuns-per-range'.")
15764 To change the ranges, we edit this list.
15766 Next, we need to write the function that creates the list of the
15767 number of definitions within each range. Clearly, this function must
15768 take the @code{sorted-lengths} and the @code{top-of-ranges} lists
15771 The @code{defuns-per-range} function must do two things again and
15772 again: it must count the number of definitions within a range
15773 specified by the current top-of-range value; and it must shift to the
15774 next higher value in the @code{top-of-ranges} list after counting the
15775 number of definitions in the current range. Since each of these
15776 actions is repetitive, we can use @code{while} loops for the job.
15777 One loop counts the number of definitions in the range defined by the
15778 current top-of-range value, and the other loop selects each of the
15779 top-of-range values in turn.
15781 Several entries of the @code{sorted-lengths} list are counted for each
15782 range; this means that the loop for the @code{sorted-lengths} list
15783 will be inside the loop for the @code{top-of-ranges} list, like a
15784 small gear inside a big gear.
15786 The inner loop counts the number of definitions within the range. It
15787 is a simple counting loop of the type we have seen before.
15788 (@xref{Incrementing Loop, , A loop with an incrementing counter}.)
15789 The true-or-false test of the loop tests whether the value from the
15790 @code{sorted-lengths} list is smaller than the current value of the
15791 top of the range. If it is, the function increments the counter and
15792 tests the next value from the @code{sorted-lengths} list.
15795 The inner loop looks like this:
15799 (while @var{length-element-smaller-than-top-of-range}
15800 (setq number-within-range (1+ number-within-range))
15801 (setq sorted-lengths (cdr sorted-lengths)))
15805 The outer loop must start with the lowest value of the
15806 @code{top-of-ranges} list, and then be set to each of the succeeding
15807 higher values in turn. This can be done with a loop like this:
15811 (while top-of-ranges
15812 @var{body-of-loop}@dots{}
15813 (setq top-of-ranges (cdr top-of-ranges)))
15818 Put together, the two loops look like this:
15822 (while top-of-ranges
15824 ;; @r{Count the number of elements within the current range.}
15825 (while @var{length-element-smaller-than-top-of-range}
15826 (setq number-within-range (1+ number-within-range))
15827 (setq sorted-lengths (cdr sorted-lengths)))
15829 ;; @r{Move to next range.}
15830 (setq top-of-ranges (cdr top-of-ranges)))
15834 In addition, in each circuit of the outer loop, Emacs should record
15835 the number of definitions within that range (the value of
15836 @code{number-within-range}) in a list. We can use @code{cons} for
15837 this purpose. (@xref{cons, , @code{cons}}.)
15839 The @code{cons} function works fine, except that the list it
15840 constructs will contain the number of definitions for the highest
15841 range at its beginning and the number of definitions for the lowest
15842 range at its end. This is because @code{cons} attaches new elements
15843 of the list to the beginning of the list, and since the two loops are
15844 working their way through the lengths' list from the lower end first,
15845 the @code{defuns-per-range-list} will end up largest number first.
15846 But we will want to print our graph with smallest values first and the
15847 larger later. The solution is to reverse the order of the
15848 @code{defuns-per-range-list}. We can do this using the
15849 @code{nreverse} function, which reverses the order of a list.
15856 (nreverse '(1 2 3 4))
15867 Note that the @code{nreverse} function is destructive---that is,
15868 it changes the list to which it is applied; this contrasts with the
15869 @code{car} and @code{cdr} functions, which are non-destructive. In
15870 this case, we do not want the original @code{defuns-per-range-list},
15871 so it does not matter that it is destroyed. (The @code{reverse}
15872 function provides a reversed copy of a list, leaving the original list
15877 Put all together, the @code{defuns-per-range} looks like this:
15881 (defun defuns-per-range (sorted-lengths top-of-ranges)
15882 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
15883 (let ((top-of-range (car top-of-ranges))
15884 (number-within-range 0)
15885 defuns-per-range-list)
15890 (while top-of-ranges
15896 ;; @r{Need number for numeric test.}
15897 (car sorted-lengths)
15898 (< (car sorted-lengths) top-of-range))
15902 ;; @r{Count number of definitions within current range.}
15903 (setq number-within-range (1+ number-within-range))
15904 (setq sorted-lengths (cdr sorted-lengths)))
15906 ;; @r{Exit inner loop but remain within outer loop.}
15910 (setq defuns-per-range-list
15911 (cons number-within-range defuns-per-range-list))
15912 (setq number-within-range 0) ; @r{Reset count to zero.}
15916 ;; @r{Move to next range.}
15917 (setq top-of-ranges (cdr top-of-ranges))
15918 ;; @r{Specify next top of range value.}
15919 (setq top-of-range (car top-of-ranges)))
15923 ;; @r{Exit outer loop and count the number of defuns larger than}
15924 ;; @r{ the largest top-of-range value.}
15925 (setq defuns-per-range-list
15927 (length sorted-lengths)
15928 defuns-per-range-list))
15932 ;; @r{Return a list of the number of definitions within each range,}
15933 ;; @r{ smallest to largest.}
15934 (nreverse defuns-per-range-list)))
15940 The function is straightforward except for one subtle feature. The
15941 true-or-false test of the inner loop looks like this:
15945 (and (car sorted-lengths)
15946 (< (car sorted-lengths) top-of-range))
15952 instead of like this:
15955 (< (car sorted-lengths) top-of-range)
15958 The purpose of the test is to determine whether the first item in the
15959 @code{sorted-lengths} list is less than the value of the top of the
15962 The simple version of the test works fine unless the
15963 @code{sorted-lengths} list has a @code{nil} value. In that case, the
15964 @code{(car sorted-lengths)} expression function returns
15965 @code{nil}. The @code{<} function cannot compare a number to
15966 @code{nil}, which is an empty list, so Emacs signals an error and
15967 stops the function from attempting to continue to execute.
15969 The @code{sorted-lengths} list always becomes @code{nil} when the
15970 counter reaches the end of the list. This means that any attempt to
15971 use the @code{defuns-per-range} function with the simple version of
15972 the test will fail.
15974 We solve the problem by using the @code{(car sorted-lengths)}
15975 expression in conjunction with the @code{and} expression. The
15976 @code{(car sorted-lengths)} expression returns a non-@code{nil}
15977 value so long as the list has at least one number within it, but
15978 returns @code{nil} if the list is empty. The @code{and} expression
15979 first evaluates the @code{(car sorted-lengths)} expression, and
15980 if it is @code{nil}, returns false @emph{without} evaluating the
15981 @code{<} expression. But if the @code{(car sorted-lengths)}
15982 expression returns a non-@code{nil} value, the @code{and} expression
15983 evaluates the @code{<} expression, and returns that value as the value
15984 of the @code{and} expression.
15986 @c colon in printed section title causes problem in Info cross reference
15987 This way, we avoid an error.
15990 (For information about @code{and}, see
15991 @ref{kill-new function, , The @code{kill-new} function}.)
15995 (@xref{kill-new function, , The @code{kill-new} function}, for
15996 information about @code{and}.)
15999 Here is a short test of the @code{defuns-per-range} function. First,
16000 evaluate the expression that binds (a shortened)
16001 @code{top-of-ranges} list to the list of values, then evaluate the
16002 expression for binding the @code{sorted-lengths} list, and then
16003 evaluate the @code{defuns-per-range} function.
16007 ;; @r{(Shorter list than we will use later.)}
16008 (setq top-of-ranges
16009 '(110 120 130 140 150
16010 160 170 180 190 200))
16012 (setq sorted-lengths
16013 '(85 86 110 116 122 129 154 176 179 200 265 300 300))
16015 (defuns-per-range sorted-lengths top-of-ranges)
16021 The list returned looks like this:
16024 (2 2 2 0 0 1 0 2 0 0 4)
16028 Indeed, there are two elements of the @code{sorted-lengths} list
16029 smaller than 110, two elements between 110 and 119, two elements
16030 between 120 and 129, and so on. There are four elements with a value
16033 @c The next step is to turn this numbers' list into a graph.
16034 @node Readying a Graph
16035 @chapter Readying a Graph
16036 @cindex Readying a graph
16037 @cindex Graph prototype
16038 @cindex Prototype graph
16039 @cindex Body of graph
16041 Our goal is to construct a graph showing the numbers of function
16042 definitions of various lengths in the Emacs lisp sources.
16044 As a practical matter, if you were creating a graph, you would
16045 probably use a program such as @code{gnuplot} to do the job.
16046 (@code{gnuplot} is nicely integrated into GNU Emacs.) In this case,
16047 however, we create one from scratch, and in the process we will
16048 re-acquaint ourselves with some of what we learned before and learn
16051 In this chapter, we will first write a simple graph printing function.
16052 This first definition will be a @dfn{prototype}, a rapidly written
16053 function that enables us to reconnoiter this unknown graph-making
16054 territory. We will discover dragons, or find that they are myth.
16055 After scouting the terrain, we will feel more confident and enhance
16056 the function to label the axes automatically.
16059 * Columns of a graph::
16060 * graph-body-print:: How to print the body of a graph.
16061 * recursive-graph-body-print::
16063 * Line Graph Exercise::
16067 @node Columns of a graph
16068 @unnumberedsec Printing the Columns of a Graph
16071 Since Emacs is designed to be flexible and work with all kinds of
16072 terminals, including character-only terminals, the graph will need to
16073 be made from one of the typewriter symbols. An asterisk will do; as
16074 we enhance the graph-printing function, we can make the choice of
16075 symbol a user option.
16077 We can call this function @code{graph-body-print}; it will take a
16078 @code{numbers-list} as its only argument. At this stage, we will not
16079 label the graph, but only print its body.
16081 The @code{graph-body-print} function inserts a vertical column of
16082 asterisks for each element in the @code{numbers-list}. The height of
16083 each line is determined by the value of that element of the
16084 @code{numbers-list}.
16086 Inserting columns is a repetitive act; that means that this function can
16087 be written either with a @code{while} loop or recursively.
16089 Our first challenge is to discover how to print a column of asterisks.
16090 Usually, in Emacs, we print characters onto a screen horizontally,
16091 line by line, by typing. We have two routes we can follow: write our
16092 own column-insertion function or discover whether one exists in Emacs.
16094 To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
16095 command. This command is like the @kbd{C-h a} (@code{command-apropos})
16096 command, except that the latter finds only those functions that are
16097 commands. The @kbd{M-x apropos} command lists all symbols that match
16098 a regular expression, including functions that are not interactive.
16101 What we want to look for is some command that prints or inserts
16102 columns. Very likely, the name of the function will contain either
16103 the word ``print'' or the word ``insert'' or the word ``column''.
16104 Therefore, we can simply type @kbd{M-x apropos RET
16105 print\|insert\|column RET} and look at the result. On my system, this
16106 command once too takes quite some time, and then produced a list of 79
16107 functions and variables. Now it does not take much time at all and
16108 produces a list of 211 functions and variables. Scanning down the
16109 list, the only function that looks as if it might do the job is
16110 @code{insert-rectangle}.
16113 Indeed, this is the function we want; its documentation says:
16118 Insert text of RECTANGLE with upper left corner at point.
16119 RECTANGLE's first line is inserted at point,
16120 its second line is inserted at a point vertically under point, etc.
16121 RECTANGLE should be a list of strings.
16122 After this command, the mark is at the upper left corner
16123 and point is at the lower right corner.
16127 We can run a quick test, to make sure it does what we expect of it.
16129 Here is the result of placing the cursor after the
16130 @code{insert-rectangle} expression and typing @kbd{C-u C-x C-e}
16131 (@code{eval-last-sexp}). The function inserts the strings
16132 @samp{"first"}, @samp{"second"}, and @samp{"third"} at and below
16133 point. Also the function returns @code{nil}.
16137 (insert-rectangle '("first" "second" "third"))first
16144 Of course, we won't be inserting the text of the
16145 @code{insert-rectangle} expression itself into the buffer in which we
16146 are making the graph, but will call the function from our program. We
16147 shall, however, have to make sure that point is in the buffer at the
16148 place where the @code{insert-rectangle} function will insert its
16151 If you are reading this in Info, you can see how this works by
16152 switching to another buffer, such as the @file{*scratch*} buffer,
16153 placing point somewhere in the buffer, typing @kbd{M-:}, typing the
16154 @code{insert-rectangle} expression into the minibuffer at the prompt,
16155 and then typing @key{RET}. This causes Emacs to evaluate the
16156 expression in the minibuffer, but to use as the value of point the
16157 position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the
16158 keybinding for @code{eval-expression}. Also, @code{nil} does not
16159 appear in the @file{*scratch*} buffer since the expression is
16160 evaluated in the minibuffer.)
16162 We find when we do this that point ends up at the end of the last
16163 inserted line---that is to say, this function moves point as a
16164 side-effect. If we were to repeat the command, with point at this
16165 position, the next insertion would be below and to the right of the
16166 previous insertion. We don't want this! If we are going to make a
16167 bar graph, the columns need to be beside each other.
16169 So we discover that each cycle of the column-inserting @code{while}
16170 loop must reposition point to the place we want it, and that place
16171 will be at the top, not the bottom, of the column. Moreover, we
16172 remember that when we print a graph, we do not expect all the columns
16173 to be the same height. This means that the top of each column may be
16174 at a different height from the previous one. We cannot simply
16175 reposition point to the same line each time, but moved over to the
16176 right---or perhaps we can@dots{}
16178 We are planning to make the columns of the bar graph out of asterisks.
16179 The number of asterisks in the column is the number specified by the
16180 current element of the @code{numbers-list}. We need to construct a
16181 list of asterisks of the right length for each call to
16182 @code{insert-rectangle}. If this list consists solely of the requisite
16183 number of asterisks, then we will have position point the right number
16184 of lines above the base for the graph to print correctly. This could
16187 Alternatively, if we can figure out some way to pass
16188 @code{insert-rectangle} a list of the same length each time, then we
16189 can place point on the same line each time, but move it over one
16190 column to the right for each new column. If we do this, however, some
16191 of the entries in the list passed to @code{insert-rectangle} must be
16192 blanks rather than asterisks. For example, if the maximum height of
16193 the graph is 5, but the height of the column is 3, then
16194 @code{insert-rectangle} requires an argument that looks like this:
16197 (" " " " "*" "*" "*")
16200 This last proposal is not so difficult, so long as we can determine
16201 the column height. There are two ways for us to specify the column
16202 height: we can arbitrarily state what it will be, which would work
16203 fine for graphs of that height; or we can search through the list of
16204 numbers and use the maximum height of the list as the maximum height
16205 of the graph. If the latter operation were difficult, then the former
16206 procedure would be easiest, but there is a function built into Emacs
16207 that determines the maximum of its arguments. We can use that
16208 function. The function is called @code{max} and it returns the
16209 largest of all its arguments, which must be numbers. Thus, for
16217 returns 7. (A corresponding function called @code{min} returns the
16218 smallest of all its arguments.)
16222 However, we cannot simply call @code{max} on the @code{numbers-list};
16223 the @code{max} function expects numbers as its argument, not a list of
16224 numbers. Thus, the following expression,
16227 (max '(3 4 6 5 7 3))
16232 produces the following error message;
16235 Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3)
16239 We need a function that passes a list of arguments to a function.
16240 This function is @code{apply}. This function applies its first
16241 argument (a function) to its remaining arguments, the last of which
16248 (apply 'max 3 4 7 3 '(4 8 5))
16254 (Incidentally, I don't know how you would learn of this function
16255 without a book such as this. It is possible to discover other
16256 functions, like @code{search-forward} or @code{insert-rectangle}, by
16257 guessing at a part of their names and then using @code{apropos}. Even
16258 though its base in metaphor is clear---apply its first argument to
16259 the rest---I doubt a novice would come up with that particular word
16260 when using @code{apropos} or other aid. Of course, I could be wrong;
16261 after all, the function was first named by someone who had to invent
16264 The second and subsequent arguments to @code{apply} are optional, so
16265 we can use @code{apply} to call a function and pass the elements of a
16266 list to it, like this, which also returns 8:
16269 (apply 'max '(4 8 5))
16272 This latter way is how we will use @code{apply}. The
16273 @code{recursive-lengths-list-many-files} function returns a numbers'
16274 list to which we can apply @code{max} (we could also apply @code{max} to
16275 the sorted numbers' list; it does not matter whether the list is
16279 Hence, the operation for finding the maximum height of the graph is this:
16282 (setq max-graph-height (apply 'max numbers-list))
16285 Now we can return to the question of how to create a list of strings
16286 for a column of the graph. Told the maximum height of the graph
16287 and the number of asterisks that should appear in the column, the
16288 function should return a list of strings for the
16289 @code{insert-rectangle} command to insert.
16291 Each column is made up of asterisks or blanks. Since the function is
16292 passed the value of the height of the column and the number of
16293 asterisks in the column, the number of blanks can be found by
16294 subtracting the number of asterisks from the height of the column.
16295 Given the number of blanks and the number of asterisks, two
16296 @code{while} loops can be used to construct the list:
16300 ;;; @r{First version.}
16301 (defun column-of-graph (max-graph-height actual-height)
16302 "Return list of strings that is one column of a graph."
16303 (let ((insert-list nil)
16304 (number-of-top-blanks
16305 (- max-graph-height actual-height)))
16309 ;; @r{Fill in asterisks.}
16310 (while (> actual-height 0)
16311 (setq insert-list (cons "*" insert-list))
16312 (setq actual-height (1- actual-height)))
16316 ;; @r{Fill in blanks.}
16317 (while (> number-of-top-blanks 0)
16318 (setq insert-list (cons " " insert-list))
16319 (setq number-of-top-blanks
16320 (1- number-of-top-blanks)))
16324 ;; @r{Return whole list.}
16329 If you install this function and then evaluate the following
16330 expression you will see that it returns the list as desired:
16333 (column-of-graph 5 3)
16341 (" " " " "*" "*" "*")
16344 As written, @code{column-of-graph} contains a major flaw: the symbols
16345 used for the blank and for the marked entries in the column are
16346 hard-coded as a space and asterisk. This is fine for a prototype,
16347 but you, or another user, may wish to use other symbols. For example,
16348 in testing the graph function, you many want to use a period in place
16349 of the space, to make sure the point is being repositioned properly
16350 each time the @code{insert-rectangle} function is called; or you might
16351 want to substitute a @samp{+} sign or other symbol for the asterisk.
16352 You might even want to make a graph-column that is more than one
16353 display column wide. The program should be more flexible. The way to
16354 do that is to replace the blank and the asterisk with two variables
16355 that we can call @code{graph-blank} and @code{graph-symbol} and define
16356 those variables separately.
16358 Also, the documentation is not well written. These considerations
16359 lead us to the second version of the function:
16363 (defvar graph-symbol "*"
16364 "String used as symbol in graph, usually an asterisk.")
16368 (defvar graph-blank " "
16369 "String used as blank in graph, usually a blank space.
16370 graph-blank must be the same number of columns wide
16376 (For an explanation of @code{defvar}, see
16377 @ref{defvar, , Initializing a Variable with @code{defvar}}.)
16381 ;;; @r{Second version.}
16382 (defun column-of-graph (max-graph-height actual-height)
16383 "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols.
16387 The graph-symbols are contiguous entries at the end
16389 The list will be inserted as one column of a graph.
16390 The strings are either graph-blank or graph-symbol."
16394 (let ((insert-list nil)
16395 (number-of-top-blanks
16396 (- max-graph-height actual-height)))
16400 ;; @r{Fill in @code{graph-symbols}.}
16401 (while (> actual-height 0)
16402 (setq insert-list (cons graph-symbol insert-list))
16403 (setq actual-height (1- actual-height)))
16407 ;; @r{Fill in @code{graph-blanks}.}
16408 (while (> number-of-top-blanks 0)
16409 (setq insert-list (cons graph-blank insert-list))
16410 (setq number-of-top-blanks
16411 (1- number-of-top-blanks)))
16413 ;; @r{Return whole list.}
16418 If we wished, we could rewrite @code{column-of-graph} a third time to
16419 provide optionally for a line graph as well as for a bar graph. This
16420 would not be hard to do. One way to think of a line graph is that it
16421 is no more than a bar graph in which the part of each bar that is
16422 below the top is blank. To construct a column for a line graph, the
16423 function first constructs a list of blanks that is one shorter than
16424 the value, then it uses @code{cons} to attach a graph symbol to the
16425 list; then it uses @code{cons} again to attach the top blanks to
16428 It is easy to see how to write such a function, but since we don't
16429 need it, we will not do it. But the job could be done, and if it were
16430 done, it would be done with @code{column-of-graph}. Even more
16431 important, it is worth noting that few changes would have to be made
16432 anywhere else. The enhancement, if we ever wish to make it, is
16435 Now, finally, we come to our first actual graph printing function.
16436 This prints the body of a graph, not the labels for the vertical and
16437 horizontal axes, so we can call this @code{graph-body-print}.
16439 @node graph-body-print
16440 @section The @code{graph-body-print} Function
16441 @findex graph-body-print
16443 After our preparation in the preceding section, the
16444 @code{graph-body-print} function is straightforward. The function
16445 will print column after column of asterisks and blanks, using the
16446 elements of a numbers' list to specify the number of asterisks in each
16447 column. This is a repetitive act, which means we can use a
16448 decrementing @code{while} loop or recursive function for the job. In
16449 this section, we will write the definition using a @code{while} loop.
16451 The @code{column-of-graph} function requires the height of the graph
16452 as an argument, so we should determine and record that as a local variable.
16454 This leads us to the following template for the @code{while} loop
16455 version of this function:
16459 (defun graph-body-print (numbers-list)
16460 "@var{documentation}@dots{}"
16461 (let ((height @dots{}
16466 (while numbers-list
16467 @var{insert-columns-and-reposition-point}
16468 (setq numbers-list (cdr numbers-list)))))
16473 We need to fill in the slots of the template.
16475 Clearly, we can use the @code{(apply 'max numbers-list)} expression to
16476 determine the height of the graph.
16478 The @code{while} loop will cycle through the @code{numbers-list} one
16479 element at a time. As it is shortened by the @code{(setq numbers-list
16480 (cdr numbers-list))} expression, the @sc{car} of each instance of the
16481 list is the value of the argument for @code{column-of-graph}.
16483 At each cycle of the @code{while} loop, the @code{insert-rectangle}
16484 function inserts the list returned by @code{column-of-graph}. Since
16485 the @code{insert-rectangle} function moves point to the lower right of
16486 the inserted rectangle, we need to save the location of point at the
16487 time the rectangle is inserted, move back to that position after the
16488 rectangle is inserted, and then move horizontally to the next place
16489 from which @code{insert-rectangle} is called.
16491 If the inserted columns are one character wide, as they will be if
16492 single blanks and asterisks are used, the repositioning command is
16493 simply @code{(forward-char 1)}; however, the width of a column may be
16494 greater than one. This means that the repositioning command should be
16495 written @code{(forward-char symbol-width)}. The @code{symbol-width}
16496 itself is the length of a @code{graph-blank} and can be found using
16497 the expression @code{(length graph-blank)}. The best place to bind
16498 the @code{symbol-width} variable to the value of the width of graph
16499 column is in the varlist of the @code{let} expression.
16502 These considerations lead to the following function definition:
16506 (defun graph-body-print (numbers-list)
16507 "Print a bar graph of the NUMBERS-LIST.
16508 The numbers-list consists of the Y-axis values."
16510 (let ((height (apply 'max numbers-list))
16511 (symbol-width (length graph-blank))
16516 (while numbers-list
16517 (setq from-position (point))
16519 (column-of-graph height (car numbers-list)))
16520 (goto-char from-position)
16521 (forward-char symbol-width)
16524 ;; @r{Draw graph column by column.}
16526 (setq numbers-list (cdr numbers-list)))
16529 ;; @r{Place point for X axis labels.}
16530 (forward-line height)
16537 The one unexpected expression in this function is the
16538 @w{@code{(sit-for 0)}} expression in the @code{while} loop. This
16539 expression makes the graph printing operation more interesting to
16540 watch than it would be otherwise. The expression causes Emacs to
16541 @dfn{sit} or do nothing for a zero length of time and then redraw the
16542 screen. Placed here, it causes Emacs to redraw the screen column by
16543 column. Without it, Emacs would not redraw the screen until the
16546 We can test @code{graph-body-print} with a short list of numbers.
16550 Install @code{graph-symbol}, @code{graph-blank},
16551 @code{column-of-graph}, which are in
16553 @ref{Readying a Graph, , Readying a Graph},
16556 @ref{Columns of a graph},
16558 and @code{graph-body-print}.
16562 Copy the following expression:
16565 (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3))
16569 Switch to the @file{*scratch*} buffer and place the cursor where you
16570 want the graph to start.
16573 Type @kbd{M-:} (@code{eval-expression}).
16576 Yank the @code{graph-body-print} expression into the minibuffer
16577 with @kbd{C-y} (@code{yank)}.
16580 Press @key{RET} to evaluate the @code{graph-body-print} expression.
16584 Emacs will print a graph like this:
16598 @node recursive-graph-body-print
16599 @section The @code{recursive-graph-body-print} Function
16600 @findex recursive-graph-body-print
16602 The @code{graph-body-print} function may also be written recursively.
16603 The recursive solution is divided into two parts: an outside wrapper
16604 that uses a @code{let} expression to determine the values of several
16605 variables that need only be found once, such as the maximum height of
16606 the graph, and an inside function that is called recursively to print
16610 The wrapper is uncomplicated:
16614 (defun recursive-graph-body-print (numbers-list)
16615 "Print a bar graph of the NUMBERS-LIST.
16616 The numbers-list consists of the Y-axis values."
16617 (let ((height (apply 'max numbers-list))
16618 (symbol-width (length graph-blank))
16620 (recursive-graph-body-print-internal
16627 The recursive function is a little more difficult. It has four parts:
16628 the do-again-test, the printing code, the recursive call, and the
16629 next-step-expression. The do-again-test is a @code{when}
16630 expression that determines whether the @code{numbers-list} contains
16631 any remaining elements; if it does, the function prints one column of
16632 the graph using the printing code and calls itself again. The
16633 function calls itself again according to the value produced by the
16634 next-step-expression which causes the call to act on a shorter
16635 version of the @code{numbers-list}.
16639 (defun recursive-graph-body-print-internal
16640 (numbers-list height symbol-width)
16641 "Print a bar graph.
16642 Used within recursive-graph-body-print function."
16647 (setq from-position (point))
16649 (column-of-graph height (car numbers-list)))
16652 (goto-char from-position)
16653 (forward-char symbol-width)
16654 (sit-for 0) ; @r{Draw graph column by column.}
16655 (recursive-graph-body-print-internal
16656 (cdr numbers-list) height symbol-width)))
16661 After installation, this expression can be tested; here is a sample:
16664 (recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1))
16668 Here is what @code{recursive-graph-body-print} produces:
16682 Either of these two functions, @code{graph-body-print} or
16683 @code{recursive-graph-body-print}, create the body of a graph.
16686 @section Need for Printed Axes
16688 A graph needs printed axes, so you can orient yourself. For a do-once
16689 project, it may be reasonable to draw the axes by hand using Emacs's
16690 Picture mode; but a graph drawing function may be used more than once.
16692 For this reason, I have written enhancements to the basic
16693 @code{print-graph-body} function that automatically print labels for
16694 the horizontal and vertical axes. Since the label printing functions
16695 do not contain much new material, I have placed their description in
16696 an appendix. @xref{Full Graph, , A Graph with Labeled Axes}.
16698 @node Line Graph Exercise
16701 Write a line graph version of the graph printing functions.
16703 @node Emacs Initialization
16704 @chapter Your @file{.emacs} File
16705 @cindex @file{.emacs} file
16706 @cindex Customizing your @file{.emacs} file
16707 @cindex Initialization file
16709 ``You don't have to like Emacs to like it''---this seemingly
16710 paradoxical statement is the secret of GNU Emacs. The plain, out-of-the-box
16711 Emacs is a generic tool. Most people who use it, customize
16712 it to suit themselves.
16714 GNU Emacs is mostly written in Emacs Lisp; this means that by writing
16715 expressions in Emacs Lisp you can change or extend Emacs.
16718 * Default Configuration::
16719 * Site-wide Init:: You can write site-wide init files.
16720 * defcustom:: Emacs will write code for you.
16721 * Beginning init File:: How to write a @file{.emacs} init file.
16722 * Text and Auto-fill:: Automatically wrap lines.
16723 * Mail Aliases:: Use abbreviations for email addresses.
16724 * Indent Tabs Mode:: Don't use tabs with @TeX{}
16725 * Keybindings:: Create some personal keybindings.
16726 * Keymaps:: More about key binding.
16727 * Loading Files:: Load (i.e., evaluate) files automatically.
16728 * Autoload:: Make functions available.
16729 * Simple Extension:: Define a function; bind it to a key.
16730 * X11 Colors:: Colors in X.
16732 * Mode Line:: How to customize your mode line.
16736 @node Default Configuration
16737 @unnumberedsec Emacs's Default Configuration
16740 There are those who appreciate Emacs's default configuration. After
16741 all, Emacs starts you in C mode when you edit a C file, starts you in
16742 Fortran mode when you edit a Fortran file, and starts you in
16743 Fundamental mode when you edit an unadorned file. This all makes
16744 sense, if you do not know who is going to use Emacs. Who knows what a
16745 person hopes to do with an unadorned file? Fundamental mode is the
16746 right default for such a file, just as C mode is the right default for
16747 editing C code. (Enough programming languages have syntaxes
16748 that enable them to share or nearly share features, so C mode is
16749 now provided by CC mode, the C Collection.)
16751 But when you do know who is going to use Emacs---you,
16752 yourself---then it makes sense to customize Emacs.
16754 For example, I seldom want Fundamental mode when I edit an
16755 otherwise undistinguished file; I want Text mode. This is why I
16756 customize Emacs: so it suits me.
16758 You can customize and extend Emacs by writing or adapting a
16759 @file{~/.emacs} file. This is your personal initialization file; its
16760 contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You
16761 may also add @file{.el} to @file{~/.emacs} and call it a
16762 @file{~/.emacs.el} file. In the past, you were forbidden to type the
16763 extra keystrokes that the name @file{~/.emacs.el} requires, but now
16764 you may. The new format is consistent with the Emacs Lisp file
16765 naming conventions; the old format saves typing.}
16767 A @file{~/.emacs} file contains Emacs Lisp code. You can write this
16768 code yourself; or you can use Emacs's @code{customize} feature to write
16769 the code for you. You can combine your own expressions and
16770 auto-written Customize expressions in your @file{.emacs} file.
16772 (I myself prefer to write my own expressions, except for those,
16773 particularly fonts, that I find easier to manipulate using the
16774 @code{customize} command. I combine the two methods.)
16776 Most of this chapter is about writing expressions yourself. It
16777 describes a simple @file{.emacs} file; for more information, see
16778 @ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and
16779 @ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference
16782 @node Site-wide Init
16783 @section Site-wide Initialization Files
16785 @cindex @file{default.el} init file
16786 @cindex @file{site-init.el} init file
16787 @cindex @file{site-load.el} init file
16788 In addition to your personal initialization file, Emacs automatically
16789 loads various site-wide initialization files, if they exist. These
16790 have the same form as your @file{.emacs} file, but are loaded by
16793 Two site-wide initialization files, @file{site-load.el} and
16794 @file{site-init.el}, are loaded into Emacs and then dumped if a
16795 dumped version of Emacs is created, as is most common. (Dumped
16796 copies of Emacs load more quickly. However, once a file is loaded and
16797 dumped, a change to it does not lead to a change in Emacs unless you
16798 load it yourself or re-dump Emacs. @xref{Building Emacs, , Building
16799 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the
16800 @file{INSTALL} file.)
16802 Three other site-wide initialization files are loaded automatically
16803 each time you start Emacs, if they exist. These are
16804 @file{site-start.el}, which is loaded @emph{before} your @file{.emacs}
16805 file, and @file{default.el}, and the terminal type file, which are both
16806 loaded @emph{after} your @file{.emacs} file.
16808 Settings and definitions in your @file{.emacs} file will overwrite
16809 conflicting settings and definitions in a @file{site-start.el} file,
16810 if it exists; but the settings and definitions in a @file{default.el}
16811 or terminal type file will overwrite those in your @file{.emacs} file.
16812 (You can prevent interference from a terminal type file by setting
16813 @code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A
16814 Simple Extension}.)
16816 @c Rewritten to avoid overfull hbox.
16817 The @file{INSTALL} file that comes in the distribution contains
16818 descriptions of the @file{site-init.el} and @file{site-load.el} files.
16820 The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files
16821 control loading. These files are in the @file{lisp} directory of the
16822 Emacs distribution and are worth perusing.
16824 The @file{loaddefs.el} file contains a good many suggestions as to
16825 what to put into your own @file{.emacs} file, or into a site-wide
16826 initialization file.
16829 @section Specifying Variables using @code{defcustom}
16832 You can specify variables using @code{defcustom} so that you and
16833 others can then use Emacs's @code{customize} feature to set their
16834 values. (You cannot use @code{customize} to write function
16835 definitions; but you can write @code{defuns} in your @file{.emacs}
16836 file. Indeed, you can write any Lisp expression in your @file{.emacs}
16839 The @code{customize} feature depends on the @code{defcustom} macro.
16840 Although you can use @code{defvar} or @code{setq} for variables that
16841 users set, the @code{defcustom} macro is designed for the job.
16843 You can use your knowledge of @code{defvar} for writing the
16844 first three arguments for @code{defcustom}. The first argument to
16845 @code{defcustom} is the name of the variable. The second argument is
16846 the variable's initial value, if any; and this value is set only if
16847 the value has not already been set. The third argument is the
16850 The fourth and subsequent arguments to @code{defcustom} specify types
16851 and options; these are not featured in @code{defvar}. (These
16852 arguments are optional.)
16854 Each of these arguments consists of a keyword followed by a value.
16855 Each keyword starts with the colon character @samp{:}.
16858 For example, the customizable user option variable
16859 @code{text-mode-hook} looks like this:
16863 (defcustom text-mode-hook nil
16864 "Normal hook run when entering Text mode and many related modes."
16866 :options '(turn-on-auto-fill flyspell-mode)
16872 The name of the variable is @code{text-mode-hook}; it has no default
16873 value; and its documentation string tells you what it does.
16875 The @code{:type} keyword tells Emacs the kind of data to which
16876 @code{text-mode-hook} should be set and how to display the value in a
16877 Customization buffer.
16879 The @code{:options} keyword specifies a suggested list of values for
16880 the variable. Usually, @code{:options} applies to a hook.
16881 The list is only a suggestion; it is not exclusive; a person who sets
16882 the variable may set it to other values; the list shown following the
16883 @code{:options} keyword is intended to offer convenient choices to a
16886 Finally, the @code{:group} keyword tells the Emacs Customization
16887 command in which group the variable is located. This tells where to
16890 The @code{defcustom} macro recognizes more than a dozen keywords.
16891 For more information, see @ref{Customization, , Writing Customization
16892 Definitions, elisp, The GNU Emacs Lisp Reference Manual}.
16894 Consider @code{text-mode-hook} as an example.
16896 There are two ways to customize this variable. You can use the
16897 customization command or write the appropriate expressions yourself.
16900 Using the customization command, you can type:
16907 and find that the group for editing files of data is called ``data''.
16908 Enter that group. Text Mode Hook is the first member. You can click
16909 on its various options, such as @code{turn-on-auto-fill}, to set the
16910 values. After you click on the button to
16913 Save for Future Sessions
16917 Emacs will write an expression into your @file{.emacs} file.
16918 It will look like this:
16922 (custom-set-variables
16923 ;; custom-set-variables was added by Custom.
16924 ;; If you edit it by hand, you could mess it up, so be careful.
16925 ;; Your init file should contain only one such instance.
16926 ;; If there is more than one, they won't work right.
16927 '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
16932 (The @code{text-mode-hook-identify} function tells
16933 @code{toggle-text-mode-auto-fill} which buffers are in Text mode.
16934 It comes on automatically.)
16936 The @code{custom-set-variables} function works somewhat differently
16937 than a @code{setq}. While I have never learned the differences, I
16938 modify the @code{custom-set-variables} expressions in my @file{.emacs}
16939 file by hand: I make the changes in what appears to me to be a
16940 reasonable manner and have not had any problems. Others prefer to use
16941 the Customization command and let Emacs do the work for them.
16943 Another @code{custom-set-@dots{}} function is @code{custom-set-faces}.
16944 This function sets the various font faces. Over time, I have set a
16945 considerable number of faces. Some of the time, I re-set them using
16946 @code{customize}; other times, I simply edit the
16947 @code{custom-set-faces} expression in my @file{.emacs} file itself.
16949 The second way to customize your @code{text-mode-hook} is to set it
16950 yourself in your @file{.emacs} file using code that has nothing to do
16951 with the @code{custom-set-@dots{}} functions.
16954 When you do this, and later use @code{customize}, you will see a
16958 CHANGED outside Customize; operating on it here may be unreliable.
16962 This message is only a warning. If you click on the button to
16965 Save for Future Sessions
16969 Emacs will write a @code{custom-set-@dots{}} expression near the end
16970 of your @file{.emacs} file that will be evaluated after your
16971 hand-written expression. It will, therefore, overrule your
16972 hand-written expression. No harm will be done. When you do this,
16973 however, be careful to remember which expression is active; if you
16974 forget, you may confuse yourself.
16976 So long as you remember where the values are set, you will have no
16977 trouble. In any event, the values are always set in your
16978 initialization file, which is usually called @file{.emacs}.
16980 I myself use @code{customize} for hardly anything. Mostly, I write
16981 expressions myself.
16985 Incidentally, to be more complete concerning defines: @code{defsubst}
16986 defines an inline function. The syntax is just like that of
16987 @code{defun}. @code{defconst} defines a symbol as a constant. The
16988 intent is that neither programs nor users should ever change a value
16989 set by @code{defconst}. (You can change it; the value set is a
16990 variable; but please do not.)
16992 @node Beginning init File
16993 @section Beginning a @file{.emacs} File
16994 @cindex @file{.emacs} file, beginning of
16996 When you start Emacs, it loads your @file{.emacs} file unless you tell
16997 it not to by specifying @samp{-q} on the command line. (The
16998 @code{emacs -q} command gives you a plain, out-of-the-box Emacs.)
17000 A @file{.emacs} file contains Lisp expressions. Often, these are no
17001 more than expressions to set values; sometimes they are function
17004 @xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs
17005 Manual}, for a short description of initialization files.
17007 This chapter goes over some of the same ground, but is a walk among
17008 extracts from a complete, long-used @file{.emacs} file---my own.
17010 The first part of the file consists of comments: reminders to myself.
17011 By now, of course, I remember these things, but when I started, I did
17017 ;;;; Bob's .emacs file
17018 ; Robert J. Chassell
17019 ; 26 September 1985
17024 Look at that date! I started this file a long time ago. I have been
17025 adding to it ever since.
17029 ; Each section in this file is introduced by a
17030 ; line beginning with four semicolons; and each
17031 ; entry is introduced by a line beginning with
17032 ; three semicolons.
17037 This describes the usual conventions for comments in Emacs Lisp.
17038 Everything on a line that follows a semicolon is a comment. Two,
17039 three, and four semicolons are used as subsection and section markers.
17040 (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for
17041 more about comments.)
17046 ; Control-h is the help key;
17047 ; after typing control-h, type a letter to
17048 ; indicate the subject about which you want help.
17049 ; For an explanation of the help facility,
17050 ; type control-h two times in a row.
17055 Just remember: type @kbd{C-h} two times for help.
17059 ; To find out about any mode, type control-h m
17060 ; while in that mode. For example, to find out
17061 ; about mail mode, enter mail mode and then type
17067 ``Mode help'', as I call this, is very helpful. Usually, it tells you
17068 all you need to know.
17070 Of course, you don't need to include comments like these in your
17071 @file{.emacs} file. I included them in mine because I kept forgetting
17072 about Mode help or the conventions for comments---but I was able to
17073 remember to look here to remind myself.
17075 @node Text and Auto-fill
17076 @section Text and Auto Fill Mode
17078 Now we come to the part that turns on Text mode and
17083 ;;; Text mode and Auto Fill mode
17084 ;; The next two lines put Emacs into Text mode
17085 ;; and Auto Fill mode, and are for writers who
17086 ;; want to start writing prose rather than code.
17087 (setq-default major-mode 'text-mode)
17088 (add-hook 'text-mode-hook 'turn-on-auto-fill)
17092 Here is the first part of this @file{.emacs} file that does something
17093 besides remind a forgetful human!
17095 The first of the two lines in parentheses tells Emacs to turn on Text
17096 mode when you find a file, @emph{unless} that file should go into some
17097 other mode, such as C mode.
17099 @cindex Per-buffer, local variables list
17100 @cindex Local variables list, per-buffer,
17101 @cindex Automatic mode selection
17102 @cindex Mode selection, automatic
17103 When Emacs reads a file, it looks at the extension to the file name,
17104 if any. (The extension is the part that comes after a @samp{.}.) If
17105 the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns
17106 on C mode. Also, Emacs looks at first nonblank line of the file; if
17107 the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs
17108 possesses a list of extensions and specifications that it uses
17109 automatically. In addition, Emacs looks near the last page for a
17110 per-buffer, local variables list, if any.
17113 @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU
17116 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
17120 See sections ``How Major Modes are Chosen'' and ``Local Variables in
17121 Files'' in @cite{The GNU Emacs Manual}.
17124 Now, back to the @file{.emacs} file.
17127 Here is the line again; how does it work?
17129 @cindex Text Mode turned on
17131 (setq major-mode 'text-mode)
17135 This line is a short, but complete Emacs Lisp expression.
17137 We are already familiar with @code{setq}. It sets the following variable,
17138 @code{major-mode}, to the subsequent value, which is @code{text-mode}.
17139 The single quote mark before @code{text-mode} tells Emacs to deal directly
17140 with the @code{text-mode} symbol, not with whatever it might stand for.
17141 @xref{set & setq, , Setting the Value of a Variable},
17142 for a reminder of how @code{setq} works.
17143 The main point is that there is no difference between the procedure you
17144 use to set a value in your @file{.emacs} file and the procedure you use
17145 anywhere else in Emacs.
17148 Here is the next line:
17150 @cindex Auto Fill mode turned on
17153 (add-hook 'text-mode-hook 'turn-on-auto-fill)
17157 In this line, the @code{add-hook} command adds
17158 @code{turn-on-auto-fill} to the variable.
17160 @code{turn-on-auto-fill} is the name of a program, that, you guessed
17161 it!, turns on Auto Fill mode.
17163 Every time Emacs turns on Text mode, Emacs runs the commands hooked
17164 onto Text mode. So every time Emacs turns on Text mode, Emacs also
17165 turns on Auto Fill mode.
17167 In brief, the first line causes Emacs to enter Text mode when you edit a
17168 file, unless the file name extension, a first non-blank line, or local
17169 variables to tell Emacs otherwise.
17171 Text mode among other actions, sets the syntax table to work
17172 conveniently for writers. In Text mode, Emacs considers an apostrophe
17173 as part of a word like a letter; but Emacs does not consider a period
17174 or a space as part of a word. Thus, @kbd{M-f} moves you over
17175 @samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after
17176 the @samp{t} of @samp{it's}.
17178 The second line causes Emacs to turn on Auto Fill mode when it turns
17179 on Text mode. In Auto Fill mode, Emacs automatically breaks a line
17180 that is too wide and brings the excessively wide part of the line down
17181 to the next line. Emacs breaks lines between words, not within them.
17183 When Auto Fill mode is turned off, lines continue to the right as you
17184 type them. Depending on how you set the value of
17185 @code{truncate-lines}, the words you type either disappear off the
17186 right side of the screen, or else are shown, in a rather ugly and
17187 unreadable manner, as a continuation line on the screen.
17190 In addition, in this part of my @file{.emacs} file, I tell the Emacs
17191 fill commands to insert two spaces after a colon:
17194 (setq colon-double-space t)
17198 @section Mail Aliases
17200 Here is a @code{setq} that turns on mail aliases, along with more
17206 ; To enter mail mode, type 'C-x m'
17207 ; To enter RMAIL (for reading mail),
17209 (setq mail-aliases t)
17213 @cindex Mail aliases
17215 This @code{setq} command sets the value of the variable
17216 @code{mail-aliases} to @code{t}. Since @code{t} means true, the line
17217 says, in effect, ``Yes, use mail aliases.''
17219 Mail aliases are convenient short names for long email addresses or
17220 for lists of email addresses. The file where you keep your aliases
17221 is @file{~/.mailrc}. You write an alias like this:
17224 alias geo george@@foobar.wiz.edu
17228 When you write a message to George, address it to @samp{geo}; the
17229 mailer will automatically expand @samp{geo} to the full address.
17231 @node Indent Tabs Mode
17232 @section Indent Tabs Mode
17233 @cindex Tabs, preventing
17234 @findex indent-tabs-mode
17236 By default, Emacs inserts tabs in place of multiple spaces when it
17237 formats a region. (For example, you might indent many lines of text
17238 all at once with the @code{indent-region} command.) Tabs look fine on
17239 a terminal or with ordinary printing, but they produce badly indented
17240 output when you use @TeX{} or Texinfo since @TeX{} ignores tabs.
17243 The following turns off Indent Tabs mode:
17247 ;;; Prevent Extraneous Tabs
17248 (setq-default indent-tabs-mode nil)
17252 Note that this line uses @code{setq-default} rather than the
17253 @code{setq} command that we have seen before. The @code{setq-default}
17254 command sets values only in buffers that do not have their own local
17255 values for the variable.
17258 @xref{Just Spaces, , Tabs vs.@: Spaces, emacs, The GNU Emacs Manual}.
17260 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
17264 See sections ``Tabs vs.@: Spaces'' and ``Local Variables in
17265 Files'' in @cite{The GNU Emacs Manual}.
17270 @section Some Keybindings
17272 Now for some personal keybindings:
17276 ;;; Compare windows
17277 (global-set-key "\C-cw" 'compare-windows)
17281 @findex compare-windows
17282 @code{compare-windows} is a nifty command that compares the text in
17283 your current window with text in the next window. It makes the
17284 comparison by starting at point in each window, moving over text in
17285 each window as far as they match. I use this command all the time.
17287 This also shows how to set a key globally, for all modes.
17289 @cindex Setting a key globally
17290 @cindex Global set key
17291 @cindex Key setting globally
17292 @findex global-set-key
17293 The command is @code{global-set-key}. It is followed by the
17294 keybinding. In a @file{.emacs} file, the keybinding is written as
17295 shown: @code{\C-c} stands for Control-C, which means to press the
17296 control key and the @key{c} key at the same time. The @code{w} means
17297 to press the @key{w} key. The keybinding is surrounded by double
17298 quotation marks. In documentation, you would write this as
17299 @w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as
17300 @kbd{M-c}, rather than a @key{CTRL} key, you would write
17301 @w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, ,
17302 Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for
17305 The command invoked by the keys is @code{compare-windows}. Note that
17306 @code{compare-windows} is preceded by a single quote; otherwise, Emacs
17307 would first try to evaluate the symbol to determine its value.
17309 These three things, the double quotation marks, the backslash before
17310 the @samp{C}, and the single quote mark are necessary parts of
17311 keybinding that I tend to forget. Fortunately, I have come to
17312 remember that I should look at my existing @file{.emacs} file, and
17313 adapt what is there.
17315 As for the keybinding itself: @kbd{C-c w}. This combines the prefix
17316 key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This
17317 set of keys, @kbd{C-c} followed by a single character, is strictly
17318 reserved for individuals' own use. (I call these @dfn{own} keys, since
17319 these are for my own use.) You should always be able to create such a
17320 keybinding for your own use without stomping on someone else's
17321 keybinding. If you ever write an extension to Emacs, please avoid
17322 taking any of these keys for public use. Create a key like @kbd{C-c
17323 C-w} instead. Otherwise, we will run out of own keys.
17326 Here is another keybinding, with a comment:
17330 ;;; Keybinding for 'occur'
17331 ; I use occur a lot, so let's bind it to a key:
17332 (global-set-key "\C-co" 'occur)
17337 The @code{occur} command shows all the lines in the current buffer
17338 that contain a match for a regular expression. Matching lines are
17339 shown in a buffer called @file{*Occur*}. That buffer serves as a menu
17340 to jump to occurrences.
17342 @findex global-unset-key
17343 @cindex Unbinding key
17344 @cindex Key unbinding
17346 Here is how to unbind a key, so it does not
17352 (global-unset-key "\C-xf")
17356 There is a reason for this unbinding: I found I inadvertently typed
17357 @w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a
17358 file, as I intended, I accidentally set the width for filled text,
17359 almost always to a width I did not want. Since I hardly ever reset my
17360 default width, I simply unbound the key.
17362 @findex list-buffers, @r{rebound}
17363 @findex buffer-menu, @r{bound to key}
17365 The following rebinds an existing key:
17369 ;;; Rebind 'C-x C-b' for 'buffer-menu'
17370 (global-set-key "\C-x\C-b" 'buffer-menu)
17374 By default, @kbd{C-x C-b} runs the
17375 @code{list-buffers} command. This command lists
17376 your buffers in @emph{another} window. Since I
17377 almost always want to do something in that
17378 window, I prefer the @code{buffer-menu}
17379 command, which not only lists the buffers,
17380 but moves point into that window.
17385 @cindex Rebinding keys
17387 Emacs uses @dfn{keymaps} to record which keys call which commands.
17388 When you use @code{global-set-key} to set the keybinding for a single
17389 command in all parts of Emacs, you are specifying the keybinding in
17390 @code{current-global-map}.
17392 Specific modes, such as C mode or Text mode, have their own keymaps;
17393 the mode-specific keymaps override the global map that is shared by
17396 The @code{global-set-key} function binds, or rebinds, the global
17397 keymap. For example, the following binds the key @kbd{C-x C-b} to the
17398 function @code{buffer-menu}:
17401 (global-set-key "\C-x\C-b" 'buffer-menu)
17404 Mode-specific keymaps are bound using the @code{define-key} function,
17405 which takes a specific keymap as an argument, as well as the key and
17406 the command. For example, my @file{.emacs} file contains the
17407 following expression to bind the @code{texinfo-insert-@@group} command
17408 to @kbd{C-c C-c g}:
17412 (define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group)
17417 The @code{texinfo-insert-@@group} function itself is a little extension
17418 to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I
17419 use this command all the time and prefer to type the three strokes
17420 @kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}.
17421 (@samp{@@group} and its matching @samp{@@end group} are commands that
17422 keep all enclosed text together on one page; many multi-line examples
17423 in this book are surrounded by @samp{@@group @dots{} @@end group}.)
17426 Here is the @code{texinfo-insert-@@group} function definition:
17430 (defun texinfo-insert-@@group ()
17431 "Insert the string @@group in a Texinfo buffer."
17433 (beginning-of-line)
17434 (insert "@@group\n"))
17438 (Of course, I could have used Abbrev mode to save typing, rather than
17439 write a function to insert a word; but I prefer key strokes consistent
17440 with other Texinfo mode key bindings.)
17442 You will see numerous @code{define-key} expressions in
17443 @file{loaddefs.el} as well as in the various mode libraries, such as
17444 @file{cc-mode.el} and @file{lisp-mode.el}.
17446 @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs
17447 Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp
17448 Reference Manual}, for more information about keymaps.
17450 @node Loading Files
17451 @section Loading Files
17452 @cindex Loading files
17455 Many people in the GNU Emacs community have written extensions to
17456 Emacs. As time goes by, these extensions are often included in new
17457 releases. For example, the Calendar and Diary packages are now part
17458 of the standard GNU Emacs, as is Calc.
17460 You can use a @code{load} command to evaluate a complete file and
17461 thereby install all the functions and variables in the file into Emacs.
17464 @c (auto-compression-mode t)
17467 (load "~/emacs/slowsplit")
17470 This evaluates, i.e., loads, the @file{slowsplit.el} file or if it
17471 exists, the faster, byte compiled @file{slowsplit.elc} file from the
17472 @file{emacs} sub-directory of your home directory. The file contains
17473 the function @code{split-window-quietly}, which John Robinson wrote in
17476 The @code{split-window-quietly} function splits a window with the
17477 minimum of redisplay. I installed it in 1989 because it worked well
17478 with the slow 1200 baud terminals I was then using. Nowadays, I only
17479 occasionally come across such a slow connection, but I continue to use
17480 the function because I like the way it leaves the bottom half of a
17481 buffer in the lower of the new windows and the top half in the upper
17485 To replace the key binding for the default
17486 @code{split-window-vertically}, you must also unset that key and bind
17487 the keys to @code{split-window-quietly}, like this:
17491 (global-unset-key "\C-x2")
17492 (global-set-key "\C-x2" 'split-window-quietly)
17497 If you load many extensions, as I do, then instead of specifying the
17498 exact location of the extension file, as shown above, you can specify
17499 that directory as part of Emacs's @code{load-path}. Then, when Emacs
17500 loads a file, it will search that directory as well as its default
17501 list of directories. (The default list is specified in @file{paths.h}
17502 when Emacs is built.)
17505 The following command adds your @file{~/emacs} directory to the
17506 existing load path:
17510 ;;; Emacs Load Path
17511 (setq load-path (cons "~/emacs" load-path))
17515 Incidentally, @code{load-library} is an interactive interface to the
17516 @code{load} function. The complete function looks like this:
17518 @findex load-library
17521 (defun load-library (library)
17522 "Load the Emacs Lisp library named LIBRARY.
17523 This is an interface to the function `load'. LIBRARY is searched
17524 for in `load-path', both with and without `load-suffixes' (as
17525 well as `load-file-rep-suffixes').
17527 See Info node `(emacs)Lisp Libraries' for more details.
17528 See `load-file' for a different interface to `load'."
17530 (list (completing-read "Load library: "
17531 (apply-partially 'locate-file-completion-table
17533 (get-load-suffixes)))))
17538 The name of the function, @code{load-library}, comes from the use of
17539 ``library'' as a conventional synonym for ``file''. The source for the
17540 @code{load-library} command is in the @file{files.el} library.
17542 Another interactive command that does a slightly different job is
17543 @code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for
17544 Emacs, emacs, The GNU Emacs Manual}, for information on the
17545 distinction between @code{load-library} and this command.
17548 @section Autoloading
17551 Instead of installing a function by loading the file that contains it,
17552 or by evaluating the function definition, you can make the function
17553 available but not actually install it until it is first called. This
17554 is called @dfn{autoloading}.
17556 When you execute an autoloaded function, Emacs automatically evaluates
17557 the file that contains the definition, and then calls the function.
17559 Emacs starts quicker with autoloaded functions, since their libraries
17560 are not loaded right away; but you need to wait a moment when you
17561 first use such a function, while its containing file is evaluated.
17563 Rarely used functions are frequently autoloaded. The
17564 @file{loaddefs.el} library contains thousands of autoloaded functions,
17565 from @code{5x5} to @code{zone}. Of course, you may
17566 come to use a rare function frequently. When you do, you should
17567 load that function's file with a @code{load} expression in your
17568 @file{.emacs} file.
17570 In my @file{.emacs} file, I load 14 libraries that contain functions
17571 that would otherwise be autoloaded. (Actually, it would have been
17572 better to include these files in my dumped Emacs, but I forgot.
17573 @xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
17574 Reference Manual}, and the @file{INSTALL} file for more about
17577 You may also want to include autoloaded expressions in your @file{.emacs}
17578 file. @code{autoload} is a built-in function that takes up to five
17579 arguments, the final three of which are optional. The first argument
17580 is the name of the function to be autoloaded; the second is the name
17581 of the file to be loaded. The third argument is documentation for the
17582 function, and the fourth tells whether the function can be called
17583 interactively. The fifth argument tells what type of
17584 object---@code{autoload} can handle a keymap or macro as well as a
17585 function (the default is a function).
17588 Here is a typical example:
17592 (autoload 'html-helper-mode
17593 "html-helper-mode" "Edit HTML documents" t)
17598 (@code{html-helper-mode} is an older alternative to @code{html-mode},
17599 which is a standard part of the distribution.)
17602 This expression autoloads the @code{html-helper-mode} function. It
17603 takes it from the @file{html-helper-mode.el} file (or from the byte
17604 compiled version @file{html-helper-mode.elc}, if that exists.) The
17605 file must be located in a directory specified by @code{load-path}.
17606 The documentation says that this is a mode to help you edit documents
17607 written in the HyperText Markup Language. You can call this mode
17608 interactively by typing @kbd{M-x html-helper-mode}. (You need to
17609 duplicate the function's regular documentation in the autoload
17610 expression because the regular function is not yet loaded, so its
17611 documentation is not available.)
17613 @xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference
17614 Manual}, for more information.
17616 @node Simple Extension
17617 @section A Simple Extension: @code{line-to-top-of-window}
17618 @findex line-to-top-of-window
17619 @cindex Simple extension in @file{.emacs} file
17621 Here is a simple extension to Emacs that moves the line point is on to
17622 the top of the window. I use this all the time, to make text easier
17625 You can put the following code into a separate file and then load it
17626 from your @file{.emacs} file, or you can include it within your
17627 @file{.emacs} file.
17630 Here is the definition:
17634 ;;; Line to top of window;
17635 ;;; replace three keystroke sequence C-u 0 C-l
17636 (defun line-to-top-of-window ()
17637 "Move the line point is on to top of window."
17644 Now for the keybinding.
17646 Nowadays, function keys as well as mouse button events and
17647 non-@sc{ascii} characters are written within square brackets, without
17648 quotation marks. (In Emacs version 18 and before, you had to write
17649 different function key bindings for each different make of terminal.)
17651 I bind @code{line-to-top-of-window} to my @key{F6} function key like
17655 (global-set-key [f6] 'line-to-top-of-window)
17658 For more information, see @ref{Init Rebinding, , Rebinding Keys in
17659 Your Init File, emacs, The GNU Emacs Manual}.
17661 @cindex Conditional 'twixt two versions of Emacs
17662 @cindex Version of Emacs, choosing
17663 @cindex Emacs version, choosing
17664 If you run two versions of GNU Emacs, such as versions 22 and 23, and
17665 use one @file{.emacs} file, you can select which code to evaluate with
17666 the following conditional:
17671 ((= 22 emacs-major-version)
17672 ;; evaluate version 22 code
17674 ((= 23 emacs-major-version)
17675 ;; evaluate version 23 code
17680 For example, recent versions blink
17681 their cursors by default. I hate such blinking, as well as other
17682 features, so I placed the following in my @file{.emacs}
17683 file@footnote{When I start instances of Emacs that do not load my
17684 @file{.emacs} file or any site file, I also turn off blinking:
17687 emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
17689 @exdent Or nowadays, using an even more sophisticated set of options,
17697 (when (>= emacs-major-version 21)
17698 (blink-cursor-mode 0)
17699 ;; Insert newline when you press 'C-n' (next-line)
17700 ;; at the end of the buffer
17701 (setq next-line-add-newlines t)
17704 ;; Turn on image viewing
17705 (auto-image-file-mode t)
17708 ;; Turn on menu bar (this bar has text)
17709 ;; (Use numeric argument to turn on)
17713 ;; Turn off tool bar (this bar has icons)
17714 ;; (Use numeric argument to turn on)
17715 (tool-bar-mode nil)
17718 ;; Turn off tooltip mode for tool bar
17719 ;; (This mode causes icon explanations to pop up)
17720 ;; (Use numeric argument to turn on)
17722 ;; If tooltips turned on, make tips appear promptly
17723 (setq tooltip-delay 0.1) ; default is 0.7 second
17729 @section X11 Colors
17731 You can specify colors when you use Emacs with the MIT X Windowing
17734 I dislike the default colors and specify my own.
17737 Here are the expressions in my @file{.emacs}
17738 file that set values:
17742 ;; Set cursor color
17743 (set-cursor-color "white")
17746 (set-mouse-color "white")
17748 ;; Set foreground and background
17749 (set-foreground-color "white")
17750 (set-background-color "darkblue")
17754 ;;; Set highlighting colors for isearch and drag
17755 (set-face-foreground 'highlight "white")
17756 (set-face-background 'highlight "blue")
17760 (set-face-foreground 'region "cyan")
17761 (set-face-background 'region "blue")
17765 (set-face-foreground 'secondary-selection "skyblue")
17766 (set-face-background 'secondary-selection "darkblue")
17770 ;; Set calendar highlighting colors
17771 (add-hook 'calendar-load-hook
17773 (set-face-foreground 'diary-face "skyblue")
17774 (set-face-background 'holiday-face "slate blue")
17775 (set-face-foreground 'holiday-face "white")))
17779 The various shades of blue soothe my eye and prevent me from seeing
17780 the screen flicker.
17782 Alternatively, I could have set my specifications in various X
17783 initialization files. For example, I could set the foreground,
17784 background, cursor, and pointer (i.e., mouse) colors in my
17785 @file{~/.Xresources} file like this:
17789 Emacs*foreground: white
17790 Emacs*background: darkblue
17791 Emacs*cursorColor: white
17792 Emacs*pointerColor: white
17796 In any event, since it is not part of Emacs, I set the root color of
17797 my X window in my @file{~/.xinitrc} file, like this@footnote{I also
17798 run more modern window managers, such as Enlightenment, Gnome, or KDE;
17799 in those cases, I often specify an image rather than a plain color.}:
17802 xsetroot -solid Navy -fg white &
17806 @node Miscellaneous
17807 @section Miscellaneous Settings for a @file{.emacs} File
17810 Here are a few miscellaneous settings:
17815 Set the shape and color of the mouse cursor:
17819 ; Cursor shapes are defined in
17820 ; '/usr/include/X11/cursorfont.h';
17821 ; for example, the 'target' cursor is number 128;
17822 ; the 'top_left_arrow' cursor is number 132.
17826 (let ((mpointer (x-get-resource "*mpointer"
17827 "*emacs*mpointer")))
17828 ;; If you have not set your mouse pointer
17829 ;; then set it, otherwise leave as is:
17830 (if (eq mpointer nil)
17831 (setq mpointer "132")) ; top_left_arrow
17834 (setq x-pointer-shape (string-to-int mpointer))
17835 (set-mouse-color "white"))
17840 Or you can set the values of a variety of features in an alist, like
17846 default-frame-alist
17847 '((cursor-color . "white")
17848 (mouse-color . "white")
17849 (foreground-color . "white")
17850 (background-color . "DodgerBlue4")
17851 ;; (cursor-type . bar)
17852 (cursor-type . box)
17855 (tool-bar-lines . 0)
17856 (menu-bar-lines . 1)
17860 "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1")
17866 Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL}
17867 into @kbd{@key{CTRL}-h}.@*
17868 (Some older keyboards needed this, although I have not seen the
17873 ;; Translate 'C-h' to <DEL>.
17874 ; (keyboard-translate ?\C-h ?\C-?)
17876 ;; Translate <DEL> to 'C-h'.
17877 (keyboard-translate ?\C-? ?\C-h)
17881 @item Turn off a blinking cursor!
17885 (if (fboundp 'blink-cursor-mode)
17886 (blink-cursor-mode -1))
17891 or start GNU Emacs with the command @code{emacs -nbc}.
17894 @item When using @command{grep}@*
17895 @samp{-i}@w{ } Ignore case distinctions@*
17896 @samp{-n}@w{ } Prefix each line of output with line number@*
17897 @samp{-H}@w{ } Print the filename for each match.@*
17898 @samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-}
17901 (setq grep-command "grep -i -nH -e ")
17905 @c Evidently, no longer needed in GNU Emacs 22
17907 item Automatically uncompress compressed files when visiting them
17910 (load "uncompress")
17915 @item Find an existing buffer, even if it has a different name@*
17916 This avoids problems with symbolic links.
17919 (setq find-file-existing-other-name t)
17922 @item Set your language environment and default input method
17926 (set-language-environment "latin-1")
17927 ;; Remember you can enable or disable multilingual text input
17928 ;; with the @code{toggle-input-method'} (@kbd{C-\}) command
17929 (setq default-input-method "latin-1-prefix")
17933 If you want to write with Chinese GB characters, set this instead:
17937 (set-language-environment "Chinese-GB")
17938 (setq default-input-method "chinese-tonepy")
17943 @subsubheading Fixing Unpleasant Key Bindings
17944 @cindex Key bindings, fixing
17945 @cindex Bindings, key, fixing unpleasant
17947 Some systems bind keys unpleasantly. Sometimes, for example, the
17948 @key{CTRL} key appears in an awkward spot rather than at the far left
17951 Usually, when people fix these sorts of keybindings, they do not
17952 change their @file{~/.emacs} file. Instead, they bind the proper keys
17953 on their consoles with the @code{loadkeys} or @code{install-keymap}
17954 commands in their boot script and then include @code{xmodmap} commands
17955 in their @file{.xinitrc} or @file{.Xsession} file for X Windows.
17963 loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz
17965 install-keymap emacs2
17971 For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps
17972 Lock} key is at the far left of the home row:
17976 # Bind the key labeled 'Caps Lock' to 'Control'
17977 # (Such a broken user interface suggests that keyboard manufacturers
17978 # think that computers are typewriters from 1885.)
17980 xmodmap -e "clear Lock"
17981 xmodmap -e "add Control = Caps_Lock"
17987 In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT}
17988 key to a @key{META} key:
17992 # Some ill designed keyboards have a key labeled ALT and no Meta
17993 xmodmap -e "keysym Alt_L = Meta_L Alt_L"
17999 @section A Modified Mode Line
18000 @vindex mode-line-format
18001 @cindex Mode line format
18003 Finally, a feature I really like: a modified mode line.
18005 When I work over a network, I forget which machine I am using. Also,
18006 I tend to I lose track of where I am, and which line point is on.
18008 So I reset my mode line to look like this:
18011 -:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top
18014 I am visiting a file called @file{foo.texi}, on my machine
18015 @file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in
18016 Texinfo mode, and am at the top of the buffer.
18019 My @file{.emacs} file has a section that looks like this:
18023 ;; Set a Mode Line that tells me which machine, which directory,
18024 ;; and which line I am on, plus the other customary information.
18025 (setq-default mode-line-format
18029 "mouse-1: select window, mouse-2: delete others ..."))
18030 mode-line-mule-info
18032 mode-line-frame-identification
18036 mode-line-buffer-identification
18039 (system-name) 0 (string-match "\\..+" (system-name))))
18044 "mouse-1: select window, mouse-2: delete others ..."))
18045 (line-number-mode " Line %l ")
18051 "mouse-1: select window, mouse-2: delete others ..."))
18052 (:eval (mode-line-mode-name))
18055 #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
18064 Here, I redefine the default mode line. Most of the parts are from
18065 the original; but I make a few changes. I set the @emph{default} mode
18066 line format so as to permit various modes, such as Info, to override
18069 Many elements in the list are self-explanatory:
18070 @code{mode-line-modified} is a variable that tells whether the buffer
18071 has been modified, @code{mode-name} tells the name of the mode, and so
18072 on. However, the format looks complicated because of two features we
18073 have not discussed.
18075 @cindex Properties, in mode line example
18076 The first string in the mode line is a dash or hyphen, @samp{-}. In
18077 the old days, it would have been specified simply as @code{"-"}. But
18078 nowadays, Emacs can add properties to a string, such as highlighting
18079 or, as in this case, a help feature. If you place your mouse cursor
18080 over the hyphen, some help information appears (By default, you must
18081 wait seven-tenths of a second before the information appears. You can
18082 change that timing by changing the value of @code{tooltip-delay}.)
18085 The new string format has a special syntax:
18088 #("-" 0 1 (help-echo "mouse-1: select window, ..."))
18092 The @code{#(} begins a list. The first element of the list is the
18093 string itself, just one @samp{-}. The second and third
18094 elements specify the range over which the fourth element applies. A
18095 range starts @emph{after} a character, so a zero means the range
18096 starts just before the first character; a 1 means that the range ends
18097 just after the first character. The third element is the property for
18098 the range. It consists of a property list, a
18099 property name, in this case, @samp{help-echo}, followed by a value, in this
18100 case, a string. The second, third, and fourth elements of this new
18101 string format can be repeated.
18103 @xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp
18104 Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format,
18105 elisp, The GNU Emacs Lisp Reference Manual}, for more information.
18107 @code{mode-line-buffer-identification}
18108 displays the current buffer name. It is a list
18109 beginning @code{(#("%12b" 0 4 @dots{}}.
18110 The @code{#(} begins the list.
18112 The @samp{"%12b"} displays the current buffer name, using the
18113 @code{buffer-name} function with which we are familiar; the @samp{12}
18114 specifies the maximum number of characters that will be displayed.
18115 When a name has fewer characters, whitespace is added to fill out to
18116 this number. (Buffer names can and often should be longer than 12
18117 characters; this length works well in a typical 80 column wide
18120 @code{:eval} says to evaluate the following form and use the result as
18121 a string to display. In this case, the expression displays the first
18122 component of the full system name. The end of the first component is
18123 a @samp{.} (period), so I use the @code{string-match} function to
18124 tell me the length of the first component. The substring from the
18125 zeroth character to that length is the name of the machine.
18128 This is the expression:
18133 (system-name) 0 (string-match "\\..+" (system-name))))
18137 @samp{%[} and @samp{%]} cause a pair of square brackets
18138 to appear for each recursive editing level. @samp{%n} says ``Narrow''
18139 when narrowing is in effect. @samp{%P} tells you the percentage of
18140 the buffer that is above the bottom of the window, or ``Top'', ``Bottom'',
18141 or ``All''. (A lower case @samp{p} tell you the percentage above the
18142 @emph{top} of the window.) @samp{%-} inserts enough dashes to fill
18145 Remember, you don't have to like Emacs to like it---your own
18146 Emacs can have different colors, different commands, and different
18147 keys than a default Emacs.
18149 On the other hand, if you want to bring up a plain out-of-the-box
18150 Emacs, with no customization, type:
18157 This will start an Emacs that does @emph{not} load your
18158 @file{~/.emacs} initialization file. A plain, default Emacs. Nothing
18165 GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The
18166 first is built into the internals of Emacs and is always with you;
18167 the second requires that you instrument a function before you can use it.
18169 Both debuggers are described extensively in @ref{Debugging, ,
18170 Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}.
18171 In this chapter, I will walk through a short example of each.
18174 * debug:: How to use the built-in debugger.
18175 * debug-on-entry:: Start debugging when you call a function.
18176 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
18177 * edebug:: How to use Edebug, a source level debugger.
18178 * Debugging Exercises::
18182 @section @code{debug}
18185 Suppose you have written a function definition that is intended to
18186 return the sum of the numbers 1 through a given number. (This is the
18187 @code{triangle} function discussed earlier. @xref{Decrementing
18188 Example, , Example with Decrementing Counter}, for a discussion.)
18189 @c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.)
18191 However, your function definition has a bug. You have mistyped
18192 @samp{1=} for @samp{1-}. Here is the broken definition:
18194 @findex triangle-bugged
18197 (defun triangle-bugged (number)
18198 "Return sum of numbers 1 through NUMBER inclusive."
18200 (while (> number 0)
18201 (setq total (+ total number))
18202 (setq number (1= number))) ; @r{Error here.}
18207 If you are reading this in Info, you can evaluate this definition in
18208 the normal fashion. You will see @code{triangle-bugged} appear in the
18212 Now evaluate the @code{triangle-bugged} function with an
18216 (triangle-bugged 4)
18220 In a recent GNU Emacs, you will create and enter a @file{*Backtrace*}
18226 ---------- Buffer: *Backtrace* ----------
18227 Debugger entered--Lisp error: (void-function 1=)
18229 (setq number (1= number))
18230 (while (> number 0) (setq total (+ total number))
18231 (setq number (1= number)))
18232 (let ((total 0)) (while (> number 0) (setq total ...)
18233 (setq number ...)) total)
18237 eval((triangle-bugged 4))
18238 eval-last-sexp-1(nil)
18239 eval-last-sexp(nil)
18240 call-interactively(eval-last-sexp)
18241 ---------- Buffer: *Backtrace* ----------
18246 (I have reformatted this example slightly; the debugger does not fold
18247 long lines. As usual, you can quit the debugger by typing @kbd{q} in
18248 the @file{*Backtrace*} buffer.)
18250 In practice, for a bug as simple as this, the Lisp error line will
18251 tell you what you need to know to correct the definition. The
18252 function @code{1=} is void.
18256 In GNU Emacs 20 and before, you will see:
18259 Symbol's function definition is void:@: 1=
18263 which has the same meaning as the @file{*Backtrace*} buffer line in
18267 However, suppose you are not quite certain what is going on?
18268 You can read the complete backtrace.
18270 In this case, you need to run a recent GNU Emacs, which automatically
18271 starts the debugger that puts you in the @file{*Backtrace*} buffer; or
18272 else, you need to start the debugger manually as described below.
18274 Read the @file{*Backtrace*} buffer from the bottom up; it tells you
18275 what Emacs did that led to the error. Emacs made an interactive call
18276 to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation
18277 of the @code{triangle-bugged} expression. Each line above tells you
18278 what the Lisp interpreter evaluated next.
18281 The third line from the top of the buffer is
18284 (setq number (1= number))
18288 Emacs tried to evaluate this expression; in order to do so, it tried
18289 to evaluate the inner expression shown on the second line from the
18298 This is where the error occurred; as the top line says:
18301 Debugger entered--Lisp error: (void-function 1=)
18305 You can correct the mistake, re-evaluate the function definition, and
18306 then run your test again.
18308 @node debug-on-entry
18309 @section @code{debug-on-entry}
18310 @findex debug-on-entry
18312 A recent GNU Emacs starts the debugger automatically when your
18313 function has an error.
18316 GNU Emacs version 20 and before did not; it simply
18317 presented you with an error message. You had to start the debugger
18321 Incidentally, you can start the debugger manually for all versions of
18322 Emacs; the advantage is that the debugger runs even if you do not have
18323 a bug in your code. Sometimes your code will be free of bugs!
18325 You can enter the debugger when you call the function by calling
18326 @code{debug-on-entry}.
18333 M-x debug-on-entry RET triangle-bugged RET
18338 Now, evaluate the following:
18341 (triangle-bugged 5)
18345 All versions of Emacs will create a @file{*Backtrace*} buffer and tell
18346 you that it is beginning to evaluate the @code{triangle-bugged}
18351 ---------- Buffer: *Backtrace* ----------
18352 Debugger entered--entering a function:
18353 * triangle-bugged(5)
18354 eval((triangle-bugged 5))
18357 eval-last-sexp-1(nil)
18358 eval-last-sexp(nil)
18359 call-interactively(eval-last-sexp)
18360 ---------- Buffer: *Backtrace* ----------
18364 In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate
18365 the first expression in @code{triangle-bugged}; the buffer will look
18370 ---------- Buffer: *Backtrace* ----------
18371 Debugger entered--beginning evaluation of function call form:
18372 * (let ((total 0)) (while (> number 0) (setq total ...)
18373 (setq number ...)) total)
18374 * triangle-bugged(5)
18375 eval((triangle-bugged 5))
18378 eval-last-sexp-1(nil)
18379 eval-last-sexp(nil)
18380 call-interactively(eval-last-sexp)
18381 ---------- Buffer: *Backtrace* ----------
18386 Now, type @kbd{d} again, eight times, slowly. Each time you type
18387 @kbd{d}, Emacs will evaluate another expression in the function
18391 Eventually, the buffer will look like this:
18395 ---------- Buffer: *Backtrace* ----------
18396 Debugger entered--beginning evaluation of function call form:
18397 * (setq number (1= number))
18398 * (while (> number 0) (setq total (+ total number))
18399 (setq number (1= number)))
18402 * (let ((total 0)) (while (> number 0) (setq total ...)
18403 (setq number ...)) total)
18404 * triangle-bugged(5)
18405 eval((triangle-bugged 5))
18408 eval-last-sexp-1(nil)
18409 eval-last-sexp(nil)
18410 call-interactively(eval-last-sexp)
18411 ---------- Buffer: *Backtrace* ----------
18417 Finally, after you type @kbd{d} two more times, Emacs will reach the
18418 error, and the top two lines of the @file{*Backtrace*} buffer will look
18423 ---------- Buffer: *Backtrace* ----------
18424 Debugger entered--Lisp error: (void-function 1=)
18427 ---------- Buffer: *Backtrace* ----------
18431 By typing @kbd{d}, you were able to step through the function.
18433 You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this
18434 quits the trace, but does not cancel @code{debug-on-entry}.
18436 @findex cancel-debug-on-entry
18437 To cancel the effect of @code{debug-on-entry}, call
18438 @code{cancel-debug-on-entry} and the name of the function, like this:
18441 M-x cancel-debug-on-entry RET triangle-bugged RET
18445 (If you are reading this in Info, cancel @code{debug-on-entry} now.)
18447 @node debug-on-quit
18448 @section @code{debug-on-quit} and @code{(debug)}
18450 In addition to setting @code{debug-on-error} or calling @code{debug-on-entry},
18451 there are two other ways to start @code{debug}.
18453 @findex debug-on-quit
18454 You can start @code{debug} whenever you type @kbd{C-g}
18455 (@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to
18456 @code{t}. This is useful for debugging infinite loops.
18459 @cindex @code{(debug)} in code
18460 Or, you can insert a line that says @code{(debug)} into your code
18461 where you want the debugger to start, like this:
18465 (defun triangle-bugged (number)
18466 "Return sum of numbers 1 through NUMBER inclusive."
18468 (while (> number 0)
18469 (setq total (+ total number))
18470 (debug) ; @r{Start debugger.}
18471 (setq number (1= number))) ; @r{Error here.}
18476 The @code{debug} function is described in detail in @ref{Debugger, ,
18477 The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}.
18480 @section The @code{edebug} Source Level Debugger
18481 @cindex Source level debugger
18484 Edebug is a source level debugger. Edebug normally displays the
18485 source of the code you are debugging, with an arrow at the left that
18486 shows which line you are currently executing.
18488 You can walk through the execution of a function, line by line, or run
18489 quickly until reaching a @dfn{breakpoint} where execution stops.
18491 Edebug is described in @ref{Edebug, , , elisp, The GNU Emacs
18492 Lisp Reference Manual}.
18495 Here is a bugged function definition for @code{triangle-recursively}.
18496 @xref{Recursive triangle function, , Recursion in place of a counter},
18497 for a review of it.
18501 (defun triangle-recursively-bugged (number)
18502 "Return sum of numbers 1 through NUMBER inclusive.
18507 (triangle-recursively-bugged
18508 (1= number))))) ; @r{Error here.}
18513 Normally, you would install this definition by positioning your cursor
18514 after the function's closing parenthesis and typing @kbd{C-x C-e}
18515 (@code{eval-last-sexp}) or else by positioning your cursor within the
18516 definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default,
18517 the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp
18521 However, to prepare this function definition for Edebug, you must
18522 first @dfn{instrument} the code using a different command. You can do
18523 this by positioning your cursor within or just after the definition
18527 M-x edebug-defun RET
18531 This will cause Emacs to load Edebug automatically if it is not
18532 already loaded, and properly instrument the function.
18534 After instrumenting the function, place your cursor after the
18535 following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}):
18538 (triangle-recursively-bugged 3)
18542 You will be jumped back to the source for
18543 @code{triangle-recursively-bugged} and the cursor positioned at the
18544 beginning of the @code{if} line of the function. Also, you will see
18545 an arrowhead at the left hand side of that line. The arrowhead marks
18546 the line where the function is executing. (In the following examples,
18547 we show the arrowhead with @samp{=>}; in a windowing system, you may
18548 see the arrowhead as a solid triangle in the window fringe.)
18551 =>@point{}(if (= number 1)
18556 In the example, the location of point is displayed with a star,
18557 @samp{@point{}} (in Info, it is displayed as @samp{-!-}).
18560 In the example, the location of point is displayed as @samp{@point{}}
18561 (in a printed book, it is displayed with a five pointed star).
18564 If you now press @key{SPC}, point will move to the next expression to
18565 be executed; the line will look like this:
18568 =>(if @point{}(= number 1)
18572 As you continue to press @key{SPC}, point will move from expression to
18573 expression. At the same time, whenever an expression returns a value,
18574 that value will be displayed in the echo area. For example, after you
18575 move point past @code{number}, you will see the following:
18578 Result: 3 (#o3, #x3, ?\C-c)
18582 This means the value of @code{number} is 3, which is octal three,
18583 hexadecimal three, and @sc{ascii} Control-C (the third letter of the
18584 alphabet, in case you need to know this information).
18586 You can continue moving through the code until you reach the line with
18587 the error. Before evaluation, that line looks like this:
18590 => @point{}(1= number))))) ; @r{Error here.}
18595 When you press @key{SPC} once again, you will produce an error message
18599 Symbol's function definition is void:@: 1=
18605 Press @kbd{q} to quit Edebug.
18607 To remove instrumentation from a function definition, simply
18608 re-evaluate it with a command that does not instrument it.
18609 For example, you could place your cursor after the definition's
18610 closing parenthesis and type @kbd{C-x C-e}.
18612 Edebug does a great deal more than walk with you through a function.
18613 You can set it so it races through on its own, stopping only at an
18614 error or at specified stopping points; you can cause it to display the
18615 changing values of various expressions; you can find out how many
18616 times a function is called, and more.
18618 Edebug is described in @ref{Edebug, , , elisp, The GNU Emacs
18619 Lisp Reference Manual}.
18622 @node Debugging Exercises
18623 @section Debugging Exercises
18627 Install the @code{@value{COUNT-WORDS}} function and then cause it to
18628 enter the built-in debugger when you call it. Run the command on a
18629 region containing two words. You will need to press @kbd{d} a
18630 remarkable number of times. On your system, is a hook called after
18631 the command finishes? (For information on hooks, see @ref{Command
18632 Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference
18636 Copy @code{@value{COUNT-WORDS}} into the @file{*scratch*} buffer,
18637 instrument the function for Edebug, and walk through its execution.
18638 The function does not need to have a bug, although you can introduce
18639 one if you wish. If the function lacks a bug, the walk-through
18640 completes without problems.
18643 While running Edebug, type @kbd{?} to see a list of all the Edebug commands.
18644 (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.,
18645 @kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix
18646 for commands made outside of the Edebug debugging buffer.)
18649 In the Edebug debugging buffer, use the @kbd{p}
18650 (@code{edebug-bounce-point}) command to see where in the region the
18651 @code{@value{COUNT-WORDS}} is working.
18654 Move point to some spot further down the function and then type the
18655 @kbd{h} (@code{edebug-goto-here}) command to jump to that location.
18658 Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to
18659 walk through the function on its own; use an upper case @kbd{T} for
18660 @code{edebug-Trace-fast-mode}.
18663 Set a breakpoint, then run Edebug in Trace mode until it reaches the
18668 @chapter Conclusion
18670 We have now reached the end of this Introduction. You have now
18671 learned enough about programming in Emacs Lisp to set values, to write
18672 simple @file{.emacs} files for yourself and your friends, and write
18673 simple customizations and extensions to Emacs.
18675 This is a place to stop. Or, if you wish, you can now go onward, and
18678 You have learned some of the basic nuts and bolts of programming. But
18679 only some. There are a great many more brackets and hinges that are
18680 easy to use that we have not touched.
18682 A path you can follow right now lies among the sources to GNU Emacs
18685 @cite{The GNU Emacs Lisp Reference Manual}.
18688 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
18689 Emacs Lisp Reference Manual}.
18692 The Emacs Lisp sources are an adventure. When you read the sources and
18693 come across a function or expression that is unfamiliar, you need to
18694 figure out or find out what it does.
18696 Go to the Reference Manual. It is a thorough, complete, and fairly
18697 easy-to-read description of Emacs Lisp. It is written not only for
18698 experts, but for people who know what you know. (The @cite{Reference
18699 Manual} comes with the standard GNU Emacs distribution. Like this
18700 introduction, it comes as a Texinfo source file, so you can read it
18701 on your computer and as a typeset, printed book.)
18703 Go to the other built-in help that is part of GNU Emacs: the built-in
18704 documentation for all functions and variables, and @code{find-tag},
18705 the program that takes you to sources.
18707 Here is an example of how I explore the sources. Because of its name,
18708 @file{simple.el} is the file I looked at first, a long time ago. As
18709 it happens some of the functions in @file{simple.el} are complicated,
18710 or at least look complicated at first sight. The @code{open-line}
18711 function, for example, looks complicated.
18713 You may want to walk through this function slowly, as we did with the
18714 @code{forward-sentence} function. (@xref{forward-sentence, The
18715 @code{forward-sentence} function}.) Or you may want to skip that
18716 function and look at another, such as @code{split-line}. You don't
18717 need to read all the functions. According to
18718 @code{count-words-in-defun}, the @code{split-line} function contains
18719 102 words and symbols.
18721 Even though it is short, @code{split-line} contains expressions
18722 we have not studied: @code{skip-chars-forward}, @code{indent-to},
18723 @code{current-column} and @code{insert-and-inherit}.
18725 Consider the @code{skip-chars-forward} function. (It is part of the
18726 function definition for @code{back-to-indentation}, which is shown in
18727 @ref{Review, , Review}.)
18729 In GNU Emacs, you can find out more about @code{skip-chars-forward} by
18730 typing @kbd{C-h f} (@code{describe-function}) and the name of the
18731 function. This gives you the function documentation.
18733 You may be able to guess what is done by a well named function such as
18734 @code{indent-to}; or you can look it up, too. Incidentally, the
18735 @code{describe-function} function itself is in @file{help.el}; it is
18736 one of those long, but decipherable functions. You can look up
18737 @code{describe-function} using the @kbd{C-h f} command!
18739 In this instance, since the code is Lisp, the @file{*Help*} buffer
18740 contains the name of the library containing the function's source.
18741 You can put point over the name of the library and press the RET key,
18742 which in this situation is bound to @code{help-follow}, and be taken
18743 directly to the source, in the same way as @kbd{M-.}
18746 The definition for @code{describe-function} illustrates how to
18747 customize the @code{interactive} expression without using the standard
18748 character codes; and it shows how to create a temporary buffer.
18750 (The @code{indent-to} function is written in C rather than Emacs Lisp;
18751 it is a built-in function. @code{help-follow} takes you to its
18752 source as does @code{find-tag}, when properly set up.)
18754 You can look at a function's source using @code{find-tag}, which is
18755 bound to @kbd{M-.} Finally, you can find out what the Reference
18756 Manual has to say by visiting the manual in Info, and typing @kbd{i}
18757 (@code{Info-index}) and the name of the function, or by looking up the
18758 function in the index to a printed copy of the manual.
18760 Similarly, you can find out what is meant by
18761 @code{insert-and-inherit}.
18763 Other interesting source files include @file{paragraphs.el},
18764 @file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el}
18765 file includes short, easily understood functions as well as longer
18766 ones. The @file{loaddefs.el} file contains the many standard
18767 autoloads and many keymaps. I have never looked at it all; only at
18768 parts. @file{loadup.el} is the file that loads the standard parts of
18769 Emacs; it tells you a great deal about how Emacs is built.
18770 (@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
18771 Reference Manual}, for more about building.)
18773 As I said, you have learned some nuts and bolts; however, and very
18774 importantly, we have hardly touched major aspects of programming; I
18775 have said nothing about how to sort information, except to use the
18776 predefined @code{sort} function; I have said nothing about how to store
18777 information, except to use variables and lists; I have said nothing
18778 about how to write programs that write programs. These are topics for
18779 another, and different kind of book, a different kind of learning.
18781 What you have done is learn enough for much practical work with GNU
18782 Emacs. What you have done is get started. This is the end of a
18785 @c ================ Appendix ================
18788 @appendix The @code{the-the} Function
18790 @cindex Duplicated words function
18791 @cindex Words, duplicated
18793 Sometimes when you you write text, you duplicate words---as with ``you
18794 you'' near the beginning of this sentence. I find that most
18795 frequently, I duplicate ``the''; hence, I call the function for
18796 detecting duplicated words, @code{the-the}.
18799 As a first step, you could use the following regular expression to
18800 search for duplicates:
18803 \\(\\w+[ \t\n]+\\)\\1
18807 This regexp matches one or more word-constituent characters followed
18808 by one or more spaces, tabs, or newlines. However, it does not detect
18809 duplicated words on different lines, since the ending of the first
18810 word, the end of the line, is different from the ending of the second
18811 word, a space. (For more information about regular expressions, see
18812 @ref{Regexp Search, , Regular Expression Searches}, as well as
18813 @ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
18814 Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp,
18815 The GNU Emacs Lisp Reference Manual}.)
18817 You might try searching just for duplicated word-constituent
18818 characters but that does not work since the pattern detects doubles
18819 such as the two occurrences of ``th'' in ``with the''.
18821 Another possible regexp searches for word-constituent characters
18822 followed by non-word-constituent characters, reduplicated. Here,
18823 @w{@samp{\\w+}} matches one or more word-constituent characters and
18824 @w{@samp{\\W*}} matches zero or more non-word-constituent characters.
18827 \\(\\(\\w+\\)\\W*\\)\\1
18833 Here is the pattern that I use. It is not perfect, but good enough.
18834 @w{@samp{\\b}} matches the empty string, provided it is at the beginning
18835 or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of
18836 any characters that are @emph{not} an @@-sign, space, newline, or tab.
18839 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
18842 One can write more complicated expressions, but I found that this
18843 expression is good enough, so I use it.
18845 Here is the @code{the-the} function, as I include it in my
18846 @file{.emacs} file, along with a handy global key binding:
18851 "Search forward for for a duplicated word."
18853 (message "Searching for for duplicated words ...")
18857 ;; This regexp is not perfect
18858 ;; but is fairly good over all:
18859 (if (re-search-forward
18860 "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move)
18861 (message "Found duplicated word.")
18862 (message "End of buffer")))
18866 ;; Bind 'the-the' to C-c \
18867 (global-set-key "\C-c\\" 'the-the)
18876 one two two three four five
18881 You can substitute the other regular expressions shown above in the
18882 function definition and try each of them on this list.
18885 @appendix Handling the Kill Ring
18886 @cindex Kill ring handling
18887 @cindex Handling the kill ring
18888 @cindex Ring, making a list like a
18890 The kill ring is a list that is transformed into a ring by the
18891 workings of the @code{current-kill} function. The @code{yank} and
18892 @code{yank-pop} commands use the @code{current-kill} function.
18894 This appendix describes the @code{current-kill} function as well as
18895 both the @code{yank} and the @code{yank-pop} commands, but first,
18896 consider the workings of the kill ring.
18899 * What the Kill Ring Does::
18901 * yank:: Paste a copy of a clipped element.
18902 * yank-pop:: Insert element pointed to.
18907 @node What the Kill Ring Does
18908 @unnumberedsec What the Kill Ring Does
18912 The kill ring has a default maximum length of sixty items; this number
18913 is too large for an explanation. Instead, set it to four. Please
18914 evaluate the following:
18918 (setq old-kill-ring-max kill-ring-max)
18919 (setq kill-ring-max 4)
18924 Then, please copy each line of the following indented example into the
18925 kill ring. You may kill each line with @kbd{C-k} or mark it and copy
18929 (In a read-only buffer, such as the @file{*info*} buffer, the kill
18930 command, @kbd{C-k} (@code{kill-line}), will not remove the text,
18931 merely copy it to the kill ring. However, your machine may beep at
18932 you. Alternatively, for silence, you may copy the region of each line
18933 with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark
18934 each line for this command to succeed, but it does not matter at which
18935 end you put point or mark.)
18939 Please invoke the calls in order, so that five elements attempt to
18940 fill the kill ring:
18945 second piece of text
18947 fourth line of text
18954 Then find the value of @code{kill-ring} by evaluating
18966 ("fifth bit of text" "fourth line of text"
18967 "third line" "second piece of text")
18972 The first element, @samp{first some text}, was dropped.
18975 To return to the old value for the length of the kill ring, evaluate:
18978 (setq kill-ring-max old-kill-ring-max)
18982 @appendixsec The @code{current-kill} Function
18983 @findex current-kill
18985 The @code{current-kill} function changes the element in the kill ring
18986 to which @code{kill-ring-yank-pointer} points. (Also, the
18987 @code{kill-new} function sets @code{kill-ring-yank-pointer} to point
18988 to the latest element of the kill ring. The @code{kill-new}
18989 function is used directly or indirectly by @code{kill-append},
18990 @code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line},
18991 and @code{kill-region}.)
18994 * Code for current-kill::
18995 * Understanding current-kill::
18999 @node Code for current-kill
19000 @unnumberedsubsec The code for @code{current-kill}
19005 The @code{current-kill} function is used by @code{yank} and by
19006 @code{yank-pop}. Here is the code for @code{current-kill}:
19010 (defun current-kill (n &optional do-not-move)
19011 "Rotate the yanking point by N places, and then return that kill.
19012 If N is zero and `interprogram-paste-function' is set to a
19013 function that returns a string or a list of strings, and if that
19014 function doesn't return nil, then that string (or list) is added
19015 to the front of the kill ring and the string (or first string in
19016 the list) is returned as the latest kill.
19019 If N is not zero, and if `yank-pop-change-selection' is
19020 non-nil, use `interprogram-cut-function' to transfer the
19021 kill at the new yank point into the window system selection.
19024 If optional arg DO-NOT-MOVE is non-nil, then don't actually
19025 move the yanking point; just return the Nth kill forward."
19027 (let ((interprogram-paste (and (= n 0)
19028 interprogram-paste-function
19029 (funcall interprogram-paste-function))))
19032 (if interprogram-paste
19034 ;; Disable the interprogram cut function when we add the new
19035 ;; text to the kill ring, so Emacs doesn't try to own the
19036 ;; selection, with identical text.
19037 (let ((interprogram-cut-function nil))
19038 (if (listp interprogram-paste)
19039 (mapc 'kill-new (nreverse interprogram-paste))
19040 (kill-new interprogram-paste)))
19044 (or kill-ring (error "Kill ring is empty"))
19045 (let ((ARGth-kill-element
19046 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19047 (length kill-ring))
19049 (unless do-not-move
19050 (setq kill-ring-yank-pointer ARGth-kill-element)
19051 (when (and yank-pop-change-selection
19053 interprogram-cut-function)
19054 (funcall interprogram-cut-function (car ARGth-kill-element))))
19055 (car ARGth-kill-element)))))
19059 Remember also that the @code{kill-new} function sets
19060 @code{kill-ring-yank-pointer} to the latest element of the kill
19061 ring, which means that all the functions that call it set the value
19062 indirectly: @code{kill-append}, @code{copy-region-as-kill},
19063 @code{kill-ring-save}, @code{kill-line}, and @code{kill-region}.
19066 Here is the line in @code{kill-new}, which is explained in
19067 @ref{kill-new function, , The @code{kill-new} function}.
19070 (setq kill-ring-yank-pointer kill-ring)
19074 @node Understanding current-kill
19075 @unnumberedsubsec @code{current-kill} in Outline
19078 The @code{current-kill} function looks complex, but as usual, it can
19079 be understood by taking it apart piece by piece. First look at it in
19084 (defun current-kill (n &optional do-not-move)
19085 "Rotate the yanking point by N places, and then return that kill."
19091 This function takes two arguments, one of which is optional. It has a
19092 documentation string. It is @emph{not} interactive.
19095 * Body of current-kill::
19096 * Digression concerning error:: How to mislead humans, but not computers.
19097 * Determining the Element::
19101 @node Body of current-kill
19102 @unnumberedsubsubsec The Body of @code{current-kill}
19105 The body of the function definition is a @code{let} expression, which
19106 itself has a body as well as a @var{varlist}.
19108 The @code{let} expression declares a variable that will be only usable
19109 within the bounds of this function. This variable is called
19110 @code{interprogram-paste} and is for copying to another program. It
19111 is not for copying within this instance of GNU Emacs. Most window
19112 systems provide a facility for interprogram pasting. Sadly, that
19113 facility usually provides only for the last element. Most windowing
19114 systems have not adopted a ring of many possibilities, even though
19115 Emacs has provided it for decades.
19117 The @code{if} expression has two parts, one if there exists
19118 @code{interprogram-paste} and one if not.
19121 Let us consider the else-part of the @code{current-kill}
19122 function. (The then-part uses the @code{kill-new} function, which
19123 we have already described. @xref{kill-new function, , The
19124 @code{kill-new} function}.)
19128 (or kill-ring (error "Kill ring is empty"))
19129 (let ((ARGth-kill-element
19130 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19131 (length kill-ring))
19134 (setq kill-ring-yank-pointer ARGth-kill-element))
19135 (car ARGth-kill-element))
19140 The code first checks whether the kill ring has content; otherwise it
19144 Note that the @code{or} expression is very similar to testing length
19151 (if (zerop (length kill-ring)) ; @r{if-part}
19152 (error "Kill ring is empty")) ; @r{then-part}
19158 If there is not anything in the kill ring, its length must be zero and
19159 an error message sent to the user: @samp{Kill ring is empty}. The
19160 @code{current-kill} function uses an @code{or} expression which is
19161 simpler. But an @code{if} expression reminds us what goes on.
19163 This @code{if} expression uses the function @code{zerop} which returns
19164 true if the value it is testing is zero. When @code{zerop} tests
19165 true, the then-part of the @code{if} is evaluated. The then-part is a
19166 list starting with the function @code{error}, which is a function that
19167 is similar to the @code{message} function
19168 (@pxref{message, , The @code{message} Function}) in that
19169 it prints a one-line message in the echo area. However, in addition
19170 to printing a message, @code{error} also stops evaluation of the
19171 function within which it is embedded. This means that the rest of the
19172 function will not be evaluated if the length of the kill ring is zero.
19174 Then the @code{current-kill} function selects the element to return.
19175 The selection depends on the number of places that @code{current-kill}
19176 rotates and on where @code{kill-ring-yank-pointer} points.
19178 Next, either the optional @code{do-not-move} argument is true or the
19179 current value of @code{kill-ring-yank-pointer} is set to point to the
19180 list. Finally, another expression returns the first element of the
19181 list even if the @code{do-not-move} argument is true.
19184 @node Digression concerning error
19185 @unnumberedsubsubsec Digression about the word ``error''
19188 In my opinion, it is slightly misleading, at least to humans, to use
19189 the term ``error'' as the name of the @code{error} function. A better
19190 term would be ``cancel''. Strictly speaking, of course, you cannot
19191 point to, much less rotate a pointer to a list that has no length, so
19192 from the point of view of the computer, the word ``error'' is correct.
19193 But a human expects to attempt this sort of thing, if only to find out
19194 whether the kill ring is full or empty. This is an act of
19197 From the human point of view, the act of exploration and discovery is
19198 not necessarily an error, and therefore should not be labeled as one,
19199 even in the bowels of a computer. As it is, the code in Emacs implies
19200 that a human who is acting virtuously, by exploring his or her
19201 environment, is making an error. This is bad. Even though the computer
19202 takes the same steps as it does when there is an error, a term such as
19203 ``cancel'' would have a clearer connotation.
19206 @node Determining the Element
19207 @unnumberedsubsubsec Determining the Element
19210 Among other actions, the else-part of the @code{if} expression sets
19211 the value of @code{kill-ring-yank-pointer} to
19212 @code{ARGth-kill-element} when the kill ring has something in it and
19213 the value of @code{do-not-move} is @code{nil}.
19216 The code looks like this:
19220 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19221 (length kill-ring))
19226 This needs some examination. Unless it is not supposed to move the
19227 pointer, the @code{current-kill} function changes where
19228 @code{kill-ring-yank-pointer} points.
19230 @w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}}
19231 expression does. Also, clearly, @code{ARGth-kill-element} is being
19232 set to be equal to some @sc{cdr} of the kill ring, using the
19233 @code{nthcdr} function that is described in an earlier section.
19234 (@xref{copy-region-as-kill}.) How does it do this?
19236 As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function
19237 works by repeatedly taking the @sc{cdr} of a list---it takes the
19238 @sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{}
19241 The two following expressions produce the same result:
19245 (setq kill-ring-yank-pointer (cdr kill-ring))
19247 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
19251 However, the @code{nthcdr} expression is more complicated. It uses
19252 the @code{mod} function to determine which @sc{cdr} to select.
19254 (You will remember to look at inner functions first; indeed, we will
19255 have to go inside the @code{mod}.)
19257 The @code{mod} function returns the value of its first argument modulo
19258 the second; that is to say, it returns the remainder after dividing
19259 the first argument by the second. The value returned has the same
19260 sign as the second argument.
19268 @result{} 0 ;; @r{because there is no remainder}
19275 In this case, the first argument is often smaller than the second.
19287 We can guess what the @code{-} function does. It is like @code{+} but
19288 subtracts instead of adds; the @code{-} function subtracts its second
19289 argument from its first. Also, we already know what the @code{length}
19290 function does (@pxref{length}). It returns the length of a list.
19292 And @code{n} is the name of the required argument to the
19293 @code{current-kill} function.
19296 So when the first argument to @code{nthcdr} is zero, the @code{nthcdr}
19297 expression returns the whole list, as you can see by evaluating the
19302 ;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four}
19303 ;; @r{and} (mod (- 0 4) 4) @result{} 0
19304 (nthcdr (mod (- 0 4) 4)
19305 '("fourth line of text"
19307 "second piece of text"
19308 "first some text"))
19313 When the first argument to the @code{current-kill} function is one,
19314 the @code{nthcdr} expression returns the list without its first
19319 (nthcdr (mod (- 1 4) 4)
19320 '("fourth line of text"
19322 "second piece of text"
19323 "first some text"))
19327 @cindex @samp{global variable} defined
19328 @cindex @samp{variable, global}, defined
19329 Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer}
19330 are @dfn{global variables}. That means that any expression in Emacs
19331 Lisp can access them. They are not like the local variables set by
19332 @code{let} or like the symbols in an argument list.
19333 Local variables can only be accessed
19334 within the @code{let} that defines them or the function that specifies
19335 them in an argument list (and within expressions called by them).
19338 @c texi2dvi fails when the name of the section is within ifnottex ...
19339 (@xref{Prevent confusion, , @code{let} Prevents Confusion}, and
19340 @ref{defun, , The @code{defun} Macro}.)
19344 @appendixsec @code{yank}
19347 After learning about @code{current-kill}, the code for the
19348 @code{yank} function is almost easy.
19350 The @code{yank} function does not use the
19351 @code{kill-ring-yank-pointer} variable directly. It calls
19352 @code{insert-for-yank} which calls @code{current-kill} which sets the
19353 @code{kill-ring-yank-pointer} variable.
19356 The code looks like this:
19361 (defun yank (&optional arg)
19362 "Reinsert (\"paste\") the last stretch of killed text.
19363 More precisely, reinsert the stretch of killed text most recently
19364 killed OR yanked. Put point at end, and set mark at beginning.
19365 With just \\[universal-argument] as argument, same but put point at beginning (and mark at end).
19366 With argument N, reinsert the Nth most recently killed stretch of killed
19369 When this command inserts killed text into the buffer, it honors
19370 `yank-excluded-properties' and `yank-handler' as described in the
19371 doc string for `insert-for-yank-1', which see.
19373 See also the command `yank-pop' (\\[yank-pop])."
19377 (setq yank-window-start (window-start))
19378 ;; If we don't get all the way thru, make last-command indicate that
19379 ;; for the following command.
19380 (setq this-command t)
19381 (push-mark (point))
19384 (insert-for-yank (current-kill (cond
19389 ;; This is like exchange-point-and-mark, but doesn't activate the mark.
19390 ;; It is cleaner to avoid activation, even though the command
19391 ;; loop would deactivate the mark because we inserted text.
19392 (goto-char (prog1 (mark t)
19393 (set-marker (mark-marker) (point) (current-buffer)))))
19396 ;; If we do get all the way thru, make this-command indicate that.
19397 (if (eq this-command t)
19398 (setq this-command 'yank))
19403 The key expression is @code{insert-for-yank}, which inserts the string
19404 returned by @code{current-kill}, but removes some text properties from
19407 However, before getting to that expression, the function sets the value
19408 of @code{yank-window-start} to the position returned by the
19409 @code{(window-start)} expression, the position at which the display
19410 currently starts. The @code{yank} function also sets
19411 @code{this-command} and pushes the mark.
19413 After it yanks the appropriate element, if the optional argument is a
19414 @sc{cons} rather than a number or nothing, it puts point at beginning
19415 of the yanked text and mark at its end.
19417 (The @code{prog1} function is like @code{progn} but returns the value
19418 of its first argument rather than the value of its last argument. Its
19419 first argument is forced to return the buffer's mark as an integer.
19420 You can see the documentation for these functions by placing point
19421 over them in this buffer and then typing @kbd{C-h f}
19422 (@code{describe-function}) followed by a @kbd{RET}; the default is the
19425 The last part of the function tells what to do when it succeeds.
19428 @appendixsec @code{yank-pop}
19431 After understanding @code{yank} and @code{current-kill}, you know how
19432 to approach the @code{yank-pop} function. Leaving out the
19433 documentation to save space, it looks like this:
19438 (defun yank-pop (&optional arg)
19441 (if (not (eq last-command 'yank))
19442 (error "Previous command was not a yank"))
19445 (setq this-command 'yank)
19446 (unless arg (setq arg 1))
19447 (let ((inhibit-read-only t)
19448 (before (< (point) (mark t))))
19452 (funcall (or yank-undo-function 'delete-region) (point) (mark t))
19453 (funcall (or yank-undo-function 'delete-region) (mark t) (point)))
19454 (setq yank-undo-function nil)
19457 (set-marker (mark-marker) (point) (current-buffer))
19458 (insert-for-yank (current-kill arg))
19459 ;; Set the window start back where it was in the yank command,
19461 (set-window-start (selected-window) yank-window-start t)
19465 ;; This is like exchange-point-and-mark,
19466 ;; but doesn't activate the mark.
19467 ;; It is cleaner to avoid activation, even though the command
19468 ;; loop would deactivate the mark because we inserted text.
19469 (goto-char (prog1 (mark t)
19470 (set-marker (mark-marker)
19472 (current-buffer))))))
19477 The function is interactive with a small @samp{p} so the prefix
19478 argument is processed and passed to the function. The command can
19479 only be used after a previous yank; otherwise an error message is
19480 sent. This check uses the variable @code{last-command} which is set
19481 by @code{yank} and is discussed elsewhere.
19482 (@xref{copy-region-as-kill}.)
19484 The @code{let} clause sets the variable @code{before} to true or false
19485 depending whether point is before or after mark and then the region
19486 between point and mark is deleted. This is the region that was just
19487 inserted by the previous yank and it is this text that will be
19490 @code{funcall} calls its first argument as a function, passing
19491 remaining arguments to it. The first argument is whatever the
19492 @code{or} expression returns. The two remaining arguments are the
19493 positions of point and mark set by the preceding @code{yank} command.
19495 There is more, but that is the hardest part.
19498 @appendixsec The @file{ring.el} File
19499 @cindex @file{ring.el} file
19501 Interestingly, GNU Emacs posses a file called @file{ring.el} that
19502 provides many of the features we just discussed. But functions such
19503 as @code{kill-ring-yank-pointer} do not use this library, possibly
19504 because they were written earlier.
19507 @appendix A Graph with Labeled Axes
19509 Printed axes help you understand a graph. They convey scale. In an
19510 earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we
19511 wrote the code to print the body of a graph. Here we write the code
19512 for printing and labeling vertical and horizontal axes, along with the
19516 * Labeled Example::
19517 * print-graph Varlist:: @code{let} expression in @code{print-graph}.
19518 * print-Y-axis:: Print a label for the vertical axis.
19519 * print-X-axis:: Print a horizontal label.
19520 * Print Whole Graph:: The function to print a complete graph.
19524 @node Labeled Example
19525 @unnumberedsec Labeled Example Graph
19528 Since insertions fill a buffer to the right and below point, the new
19529 graph printing function should first print the Y or vertical axis,
19530 then the body of the graph, and finally the X or horizontal axis.
19531 This sequence lays out for us the contents of the function:
19541 Print body of graph.
19548 Here is an example of how a finished graph should look:
19561 1 - ****************
19568 In this graph, both the vertical and the horizontal axes are labeled
19569 with numbers. However, in some graphs, the horizontal axis is time
19570 and would be better labeled with months, like this:
19584 Indeed, with a little thought, we can easily come up with a variety of
19585 vertical and horizontal labeling schemes. Our task could become
19586 complicated. But complications breed confusion. Rather than permit
19587 this, it is better choose a simple labeling scheme for our first
19588 effort, and to modify or replace it later.
19591 These considerations suggest the following outline for the
19592 @code{print-graph} function:
19596 (defun print-graph (numbers-list)
19597 "@var{documentation}@dots{}"
19598 (let ((height @dots{}
19602 (print-Y-axis height @dots{} )
19603 (graph-body-print numbers-list)
19604 (print-X-axis @dots{} )))
19608 We can work on each part of the @code{print-graph} function definition
19611 @node print-graph Varlist
19612 @appendixsec The @code{print-graph} Varlist
19613 @cindex @code{print-graph} varlist
19615 In writing the @code{print-graph} function, the first task is to write
19616 the varlist in the @code{let} expression. (We will leave aside for the
19617 moment any thoughts about making the function interactive or about the
19618 contents of its documentation string.)
19620 The varlist should set several values. Clearly, the top of the label
19621 for the vertical axis must be at least the height of the graph, which
19622 means that we must obtain this information here. Note that the
19623 @code{print-graph-body} function also requires this information. There
19624 is no reason to calculate the height of the graph in two different
19625 places, so we should change @code{print-graph-body} from the way we
19626 defined it earlier to take advantage of the calculation.
19628 Similarly, both the function for printing the X axis labels and the
19629 @code{print-graph-body} function need to learn the value of the width of
19630 each symbol. We can perform the calculation here and change the
19631 definition for @code{print-graph-body} from the way we defined it in the
19634 The length of the label for the horizontal axis must be at least as long
19635 as the graph. However, this information is used only in the function
19636 that prints the horizontal axis, so it does not need to be calculated here.
19638 These thoughts lead us directly to the following form for the varlist
19639 in the @code{let} for @code{print-graph}:
19643 (let ((height (apply 'max numbers-list)) ; @r{First version.}
19644 (symbol-width (length graph-blank)))
19649 As we shall see, this expression is not quite right.
19653 @appendixsec The @code{print-Y-axis} Function
19654 @cindex Axis, print vertical
19655 @cindex Y axis printing
19656 @cindex Vertical axis printing
19657 @cindex Print vertical axis
19659 The job of the @code{print-Y-axis} function is to print a label for
19660 the vertical axis that looks like this:
19678 The function should be passed the height of the graph, and then should
19679 construct and insert the appropriate numbers and marks.
19682 * print-Y-axis in Detail::
19683 * Height of label:: What height for the Y axis?
19684 * Compute a Remainder:: How to compute the remainder of a division.
19685 * Y Axis Element:: Construct a line for the Y axis.
19686 * Y-axis-column:: Generate a list of Y axis labels.
19687 * print-Y-axis Penultimate:: A not quite final version.
19691 @node print-Y-axis in Detail
19692 @unnumberedsubsec The @code{print-Y-axis} Function in Detail
19695 It is easy enough to see in the figure what the Y axis label should
19696 look like; but to say in words, and then to write a function
19697 definition to do the job is another matter. It is not quite true to
19698 say that we want a number and a tic every five lines: there are only
19699 three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4),
19700 but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8,
19701 and 9). It is better to say that we want a number and a tic mark on
19702 the base line (number 1) and then that we want a number and a tic on
19703 the fifth line from the bottom and on every line that is a multiple of
19707 @node Height of label
19708 @unnumberedsubsec What height should the label be?
19711 The next issue is what height the label should be? Suppose the maximum
19712 height of tallest column of the graph is seven. Should the highest
19713 label on the Y axis be @samp{5 -}, and should the graph stick up above
19714 the label? Or should the highest label be @samp{7 -}, and mark the peak
19715 of the graph? Or should the highest label be @code{10 -}, which is a
19716 multiple of five, and be higher than the topmost value of the graph?
19718 The latter form is preferred. Most graphs are drawn within rectangles
19719 whose sides are an integral number of steps long---5, 10, 15, and so
19720 on for a step distance of five. But as soon as we decide to use a
19721 step height for the vertical axis, we discover that the simple
19722 expression in the varlist for computing the height is wrong. The
19723 expression is @code{(apply 'max numbers-list)}. This returns the
19724 precise height, not the maximum height plus whatever is necessary to
19725 round up to the nearest multiple of five. A more complex expression
19728 As usual in cases like this, a complex problem becomes simpler if it is
19729 divided into several smaller problems.
19731 First, consider the case when the highest value of the graph is an
19732 integral multiple of five---when it is 5, 10, 15, or some higher
19733 multiple of five. We can use this value as the Y axis height.
19735 A fairly simply way to determine whether a number is a multiple of
19736 five is to divide it by five and see if the division results in a
19737 remainder. If there is no remainder, the number is a multiple of
19738 five. Thus, seven divided by five has a remainder of two, and seven
19739 is not an integral multiple of five. Put in slightly different
19740 language, more reminiscent of the classroom, five goes into seven
19741 once, with a remainder of two. However, five goes into ten twice,
19742 with no remainder: ten is an integral multiple of five.
19744 @node Compute a Remainder
19745 @appendixsubsec Side Trip: Compute a Remainder
19747 @findex % @r{(remainder function)}
19748 @cindex Remainder function, @code{%}
19749 In Lisp, the function for computing a remainder is @code{%}. The
19750 function returns the remainder of its first argument divided by its
19751 second argument. As it happens, @code{%} is a function in Emacs Lisp
19752 that you cannot discover using @code{apropos}: you find nothing if you
19753 type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to
19754 learn of the existence of @code{%} is to read about it in a book such
19755 as this or in the Emacs Lisp sources.
19757 You can try the @code{%} function by evaluating the following two
19769 The first expression returns 2 and the second expression returns 0.
19771 To test whether the returned value is zero or some other number, we
19772 can use the @code{zerop} function. This function returns @code{t} if
19773 its argument, which must be a number, is zero.
19785 Thus, the following expression will return @code{t} if the height
19786 of the graph is evenly divisible by five:
19789 (zerop (% height 5))
19793 (The value of @code{height}, of course, can be found from @code{(apply
19794 'max numbers-list)}.)
19796 On the other hand, if the value of @code{height} is not a multiple of
19797 five, we want to reset the value to the next higher multiple of five.
19798 This is straightforward arithmetic using functions with which we are
19799 already familiar. First, we divide the value of @code{height} by five
19800 to determine how many times five goes into the number. Thus, five
19801 goes into twelve twice. If we add one to this quotient and multiply by
19802 five, we will obtain the value of the next multiple of five that is
19803 larger than the height. Five goes into twelve twice. Add one to two,
19804 and multiply by five; the result is fifteen, which is the next multiple
19805 of five that is higher than twelve. The Lisp expression for this is:
19808 (* (1+ (/ height 5)) 5)
19812 For example, if you evaluate the following, the result is 15:
19815 (* (1+ (/ 12 5)) 5)
19818 All through this discussion, we have been using 5 as the value
19819 for spacing labels on the Y axis; but we may want to use some other
19820 value. For generality, we should replace 5 with a variable to
19821 which we can assign a value. The best name I can think of for this
19822 variable is @code{Y-axis-label-spacing}.
19825 Using this term, and an @code{if} expression, we produce the
19830 (if (zerop (% height Y-axis-label-spacing))
19833 (* (1+ (/ height Y-axis-label-spacing))
19834 Y-axis-label-spacing))
19839 This expression returns the value of @code{height} itself if the height
19840 is an even multiple of the value of the @code{Y-axis-label-spacing} or
19841 else it computes and returns a value of @code{height} that is equal to
19842 the next higher multiple of the value of the @code{Y-axis-label-spacing}.
19844 We can now include this expression in the @code{let} expression of the
19845 @code{print-graph} function (after first setting the value of
19846 @code{Y-axis-label-spacing}):
19847 @vindex Y-axis-label-spacing
19851 (defvar Y-axis-label-spacing 5
19852 "Number of lines from one Y axis label to next.")
19857 (let* ((height (apply 'max numbers-list))
19858 (height-of-top-line
19859 (if (zerop (% height Y-axis-label-spacing))
19864 (* (1+ (/ height Y-axis-label-spacing))
19865 Y-axis-label-spacing)))
19866 (symbol-width (length graph-blank))))
19872 (Note use of the @code{let*} function: the initial value of height is
19873 computed once by the @code{(apply 'max numbers-list)} expression and
19874 then the resulting value of @code{height} is used to compute its
19875 final value. @xref{fwd-para let, , The @code{let*} expression}, for
19876 more about @code{let*}.)
19878 @node Y Axis Element
19879 @appendixsubsec Construct a Y Axis Element
19881 When we print the vertical axis, we want to insert strings such as
19882 @w{@samp{5 -}} and @w{@samp{10 - }} every five lines.
19883 Moreover, we want the numbers and dashes to line up, so shorter
19884 numbers must be padded with leading spaces. If some of the strings
19885 use two digit numbers, the strings with single digit numbers must
19886 include a leading blank space before the number.
19888 @findex number-to-string
19889 To figure out the length of the number, the @code{length} function is
19890 used. But the @code{length} function works only with a string, not with
19891 a number. So the number has to be converted from being a number to
19892 being a string. This is done with the @code{number-to-string} function.
19897 (length (number-to-string 35))
19900 (length (number-to-string 100))
19906 (@code{number-to-string} is also called @code{int-to-string}; you will
19907 see this alternative name in various sources.)
19909 In addition, in each label, each number is followed by a string such
19910 as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker.
19911 This variable is defined with @code{defvar}:
19916 (defvar Y-axis-tic " - "
19917 "String that follows number in a Y axis label.")
19921 The length of the Y label is the sum of the length of the Y axis tic
19922 mark and the length of the number of the top of the graph.
19925 (length (concat (number-to-string height) Y-axis-tic)))
19928 This value will be calculated by the @code{print-graph} function in
19929 its varlist as @code{full-Y-label-width} and passed on. (Note that we
19930 did not think to include this in the varlist when we first proposed it.)
19932 To make a complete vertical axis label, a tic mark is concatenated
19933 with a number; and the two together may be preceded by one or more
19934 spaces depending on how long the number is. The label consists of
19935 three parts: the (optional) leading spaces, the number, and the tic
19936 mark. The function is passed the value of the number for the specific
19937 row, and the value of the width of the top line, which is calculated
19938 (just once) by @code{print-graph}.
19942 (defun Y-axis-element (number full-Y-label-width)
19943 "Construct a NUMBERed label element.
19944 A numbered element looks like this ` 5 - ',
19945 and is padded as needed so all line up with
19946 the element for the largest number."
19949 (let* ((leading-spaces
19950 (- full-Y-label-width
19952 (concat (number-to-string number)
19957 (make-string leading-spaces ? )
19958 (number-to-string number)
19963 The @code{Y-axis-element} function concatenates together the leading
19964 spaces, if any; the number, as a string; and the tic mark.
19966 To figure out how many leading spaces the label will need, the
19967 function subtracts the actual length of the label---the length of the
19968 number plus the length of the tic mark---from the desired label width.
19970 @findex make-string
19971 Blank spaces are inserted using the @code{make-string} function. This
19972 function takes two arguments: the first tells it how long the string
19973 will be and the second is a symbol for the character to insert, in a
19974 special format. The format is a question mark followed by a blank
19975 space, like this, @samp{? }. @xref{Character Type, , Character Type,
19976 elisp, The GNU Emacs Lisp Reference Manual}, for a description of the
19977 syntax for characters. (Of course, you might want to replace the
19978 blank space by some other character @dots{} You know what to do.)
19980 The @code{number-to-string} function is used in the concatenation
19981 expression, to convert the number to a string that is concatenated
19982 with the leading spaces and the tic mark.
19984 @node Y-axis-column
19985 @appendixsubsec Create a Y Axis Column
19987 The preceding functions provide all the tools needed to construct a
19988 function that generates a list of numbered and blank strings to insert
19989 as the label for the vertical axis:
19991 @findex Y-axis-column
19994 (defun Y-axis-column (height width-of-label)
19995 "Construct list of Y axis labels and blank strings.
19996 For HEIGHT of line above base and WIDTH-OF-LABEL."
20000 (while (> height 1)
20001 (if (zerop (% height Y-axis-label-spacing))
20002 ;; @r{Insert label.}
20005 (Y-axis-element height width-of-label)
20009 ;; @r{Else, insert blanks.}
20012 (make-string width-of-label ? )
20014 (setq height (1- height)))
20015 ;; @r{Insert base line.}
20017 (cons (Y-axis-element 1 width-of-label) Y-axis))
20018 (nreverse Y-axis)))
20022 In this function, we start with the value of @code{height} and
20023 repetitively subtract one from its value. After each subtraction, we
20024 test to see whether the value is an integral multiple of the
20025 @code{Y-axis-label-spacing}. If it is, we construct a numbered label
20026 using the @code{Y-axis-element} function; if not, we construct a
20027 blank label using the @code{make-string} function. The base line
20028 consists of the number one followed by a tic mark.
20031 @node print-Y-axis Penultimate
20032 @appendixsubsec The Not Quite Final Version of @code{print-Y-axis}
20034 The list constructed by the @code{Y-axis-column} function is passed to
20035 the @code{print-Y-axis} function, which inserts the list as a column.
20037 @findex print-Y-axis
20040 (defun print-Y-axis (height full-Y-label-width)
20041 "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH.
20042 Height must be the maximum height of the graph.
20043 Full width is the width of the highest label element."
20044 ;; Value of height and full-Y-label-width
20045 ;; are passed by print-graph.
20048 (let ((start (point)))
20050 (Y-axis-column height full-Y-label-width))
20051 ;; @r{Place point ready for inserting graph.}
20053 ;; @r{Move point forward by value of} full-Y-label-width
20054 (forward-char full-Y-label-width)))
20058 The @code{print-Y-axis} uses the @code{insert-rectangle} function to
20059 insert the Y axis labels created by the @code{Y-axis-column} function.
20060 In addition, it places point at the correct position for printing the body of
20063 You can test @code{print-Y-axis}:
20071 Y-axis-label-spacing
20080 Copy the following expression:
20083 (print-Y-axis 12 5)
20087 Switch to the @file{*scratch*} buffer and place the cursor where you
20088 want the axis labels to start.
20091 Type @kbd{M-:} (@code{eval-expression}).
20094 Yank the @code{graph-body-print} expression into the minibuffer
20095 with @kbd{C-y} (@code{yank)}.
20098 Press @key{RET} to evaluate the expression.
20101 Emacs will print labels vertically, the top one being @w{@samp{10 -@w{
20102 }}}. (The @code{print-graph} function will pass the value of
20103 @code{height-of-top-line}, which in this case will end up as 15,
20104 thereby getting rid of what might appear as a bug.)
20108 @appendixsec The @code{print-X-axis} Function
20109 @cindex Axis, print horizontal
20110 @cindex X axis printing
20111 @cindex Print horizontal axis
20112 @cindex Horizontal axis printing
20114 X axis labels are much like Y axis labels, except that the ticks are on a
20115 line above the numbers. Labels should look like this:
20124 The first tic is under the first column of the graph and is preceded by
20125 several blank spaces. These spaces provide room in rows above for the Y
20126 axis labels. The second, third, fourth, and subsequent ticks are all
20127 spaced equally, according to the value of @code{X-axis-label-spacing}.
20129 The second row of the X axis consists of numbers, preceded by several
20130 blank spaces and also separated according to the value of the variable
20131 @code{X-axis-label-spacing}.
20133 The value of the variable @code{X-axis-label-spacing} should itself be
20134 measured in units of @code{symbol-width}, since you may want to change
20135 the width of the symbols that you are using to print the body of the
20136 graph without changing the ways the graph is labeled.
20139 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
20140 * X Axis Tic Marks:: Create tic marks for the horizontal axis.
20144 @node Similarities differences
20145 @unnumberedsubsec Similarities and differences
20148 The @code{print-X-axis} function is constructed in more or less the
20149 same fashion as the @code{print-Y-axis} function except that it has
20150 two lines: the line of tic marks and the numbers. We will write a
20151 separate function to print each line and then combine them within the
20152 @code{print-X-axis} function.
20154 This is a three step process:
20158 Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}.
20161 Write a function to print the X numbers, @code{print-X-axis-numbered-line}.
20164 Write a function to print both lines, the @code{print-X-axis} function,
20165 using @code{print-X-axis-tic-line} and
20166 @code{print-X-axis-numbered-line}.
20169 @node X Axis Tic Marks
20170 @appendixsubsec X Axis Tic Marks
20172 The first function should print the X axis tic marks. We must specify
20173 the tic marks themselves and their spacing:
20177 (defvar X-axis-label-spacing
20178 (if (boundp 'graph-blank)
20179 (* 5 (length graph-blank)) 5)
20180 "Number of units from one X axis label to next.")
20185 (Note that the value of @code{graph-blank} is set by another
20186 @code{defvar}. The @code{boundp} predicate checks whether it has
20187 already been set; @code{boundp} returns @code{nil} if it has not. If
20188 @code{graph-blank} were unbound and we did not use this conditional
20189 construction, in a recent GNU Emacs, we would enter the debugger and
20190 see an error message saying @samp{@w{Debugger entered--Lisp error:}
20191 @w{(void-variable graph-blank)}}.)
20194 Here is the @code{defvar} for @code{X-axis-tic-symbol}:
20198 (defvar X-axis-tic-symbol "|"
20199 "String to insert to point to a column in X axis.")
20204 The goal is to make a line that looks like this:
20210 The first tic is indented so that it is under the first column, which is
20211 indented to provide space for the Y axis labels.
20213 A tic element consists of the blank spaces that stretch from one tic to
20214 the next plus a tic symbol. The number of blanks is determined by the
20215 width of the tic symbol and the @code{X-axis-label-spacing}.
20218 The code looks like this:
20222 ;;; X-axis-tic-element
20226 ;; @r{Make a string of blanks.}
20227 (- (* symbol-width X-axis-label-spacing)
20228 (length X-axis-tic-symbol))
20230 ;; @r{Concatenate blanks with tic symbol.}
20236 Next, we determine how many blanks are needed to indent the first tic
20237 mark to the first column of the graph. This uses the value of
20238 @code{full-Y-label-width} passed it by the @code{print-graph} function.
20241 The code to make @code{X-axis-leading-spaces}
20246 ;; X-axis-leading-spaces
20248 (make-string full-Y-label-width ? )
20253 We also need to determine the length of the horizontal axis, which is
20254 the length of the numbers list, and the number of ticks in the horizontal
20261 (length numbers-list)
20267 (* symbol-width X-axis-label-spacing)
20271 ;; number-of-X-ticks
20272 (if (zerop (% (X-length tic-width)))
20273 (/ (X-length tic-width))
20274 (1+ (/ (X-length tic-width))))
20279 All this leads us directly to the function for printing the X axis tic line:
20281 @findex print-X-axis-tic-line
20284 (defun print-X-axis-tic-line
20285 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
20286 "Print ticks for X axis."
20287 (insert X-axis-leading-spaces)
20288 (insert X-axis-tic-symbol) ; @r{Under first column.}
20291 ;; @r{Insert second tic in the right spot.}
20294 (- (* symbol-width X-axis-label-spacing)
20295 ;; @r{Insert white space up to second tic symbol.}
20296 (* 2 (length X-axis-tic-symbol)))
20298 X-axis-tic-symbol))
20301 ;; @r{Insert remaining ticks.}
20302 (while (> number-of-X-tics 1)
20303 (insert X-axis-tic-element)
20304 (setq number-of-X-tics (1- number-of-X-tics))))
20308 The line of numbers is equally straightforward:
20311 First, we create a numbered element with blank spaces before each number:
20313 @findex X-axis-element
20316 (defun X-axis-element (number)
20317 "Construct a numbered X axis element."
20318 (let ((leading-spaces
20319 (- (* symbol-width X-axis-label-spacing)
20320 (length (number-to-string number)))))
20321 (concat (make-string leading-spaces ? )
20322 (number-to-string number))))
20326 Next, we create the function to print the numbered line, starting with
20327 the number 1 under the first column:
20329 @findex print-X-axis-numbered-line
20332 (defun print-X-axis-numbered-line
20333 (number-of-X-tics X-axis-leading-spaces)
20334 "Print line of X-axis numbers"
20335 (let ((number X-axis-label-spacing))
20336 (insert X-axis-leading-spaces)
20342 ;; @r{Insert white space up to next number.}
20343 (- (* symbol-width X-axis-label-spacing) 2)
20345 (number-to-string number)))
20348 ;; @r{Insert remaining numbers.}
20349 (setq number (+ number X-axis-label-spacing))
20350 (while (> number-of-X-tics 1)
20351 (insert (X-axis-element number))
20352 (setq number (+ number X-axis-label-spacing))
20353 (setq number-of-X-tics (1- number-of-X-tics)))))
20357 Finally, we need to write the @code{print-X-axis} that uses
20358 @code{print-X-axis-tic-line} and
20359 @code{print-X-axis-numbered-line}.
20361 The function must determine the local values of the variables used by both
20362 @code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and
20363 then it must call them. Also, it must print the carriage return that
20364 separates the two lines.
20366 The function consists of a varlist that specifies five local variables,
20367 and calls to each of the two line printing functions:
20369 @findex print-X-axis
20372 (defun print-X-axis (numbers-list)
20373 "Print X axis labels to length of NUMBERS-LIST."
20374 (let* ((leading-spaces
20375 (make-string full-Y-label-width ? ))
20378 ;; symbol-width @r{is provided by} graph-body-print
20379 (tic-width (* symbol-width X-axis-label-spacing))
20380 (X-length (length numbers-list))
20388 ;; @r{Make a string of blanks.}
20389 (- (* symbol-width X-axis-label-spacing)
20390 (length X-axis-tic-symbol))
20394 ;; @r{Concatenate blanks with tic symbol.}
20395 X-axis-tic-symbol))
20399 (if (zerop (% X-length tic-width))
20400 (/ X-length tic-width)
20401 (1+ (/ X-length tic-width)))))
20404 (print-X-axis-tic-line tic-number leading-spaces X-tic)
20406 (print-X-axis-numbered-line tic-number leading-spaces)))
20411 You can test @code{print-X-axis}:
20415 Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing},
20416 @code{print-X-axis-tic-line}, as well as @code{X-axis-element},
20417 @code{print-X-axis-numbered-line}, and @code{print-X-axis}.
20420 Copy the following expression:
20425 (let ((full-Y-label-width 5)
20428 '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16))))
20433 Switch to the @file{*scratch*} buffer and place the cursor where you
20434 want the axis labels to start.
20437 Type @kbd{M-:} (@code{eval-expression}).
20440 Yank the test expression into the minibuffer
20441 with @kbd{C-y} (@code{yank)}.
20444 Press @key{RET} to evaluate the expression.
20448 Emacs will print the horizontal axis like this:
20458 @node Print Whole Graph
20459 @appendixsec Printing the Whole Graph
20460 @cindex Printing the whole graph
20461 @cindex Whole graph printing
20462 @cindex Graph, printing all
20464 Now we are nearly ready to print the whole graph.
20466 The function to print the graph with the proper labels follows the
20467 outline we created earlier (@pxref{Full Graph, , A Graph with Labeled
20468 Axes}), but with additions.
20471 Here is the outline:
20475 (defun print-graph (numbers-list)
20476 "@var{documentation}@dots{}"
20477 (let ((height @dots{}
20481 (print-Y-axis height @dots{} )
20482 (graph-body-print numbers-list)
20483 (print-X-axis @dots{} )))
20488 * The final version:: A few changes.
20489 * Test print-graph:: Run a short test.
20490 * Graphing words in defuns:: Executing the final code.
20491 * lambda:: How to write an anonymous function.
20492 * mapcar:: Apply a function to elements of a list.
20493 * Another Bug:: Yet another bug @dots{} most insidious.
20494 * Final printed graph:: The graph itself!
20498 @node The final version
20499 @unnumberedsubsec Changes for the Final Version
20502 The final version is different from what we planned in two ways:
20503 first, it contains additional values calculated once in the varlist;
20504 second, it carries an option to specify the labels' increment per row.
20505 This latter feature turns out to be essential; otherwise, a graph may
20506 have more rows than fit on a display or on a sheet of paper.
20509 This new feature requires a change to the @code{Y-axis-column}
20510 function, to add @code{vertical-step} to it. The function looks like
20513 @findex Y-axis-column @r{Final version.}
20516 ;;; @r{Final version.}
20517 (defun Y-axis-column
20518 (height width-of-label &optional vertical-step)
20519 "Construct list of labels for Y axis.
20520 HEIGHT is maximum height of graph.
20521 WIDTH-OF-LABEL is maximum width of label.
20522 VERTICAL-STEP, an option, is a positive integer
20523 that specifies how much a Y axis label increments
20524 for each line. For example, a step of 5 means
20525 that each line is five units of the graph."
20529 (number-per-line (or vertical-step 1)))
20530 (while (> height 1)
20531 (if (zerop (% height Y-axis-label-spacing))
20534 ;; @r{Insert label.}
20538 (* height number-per-line)
20543 ;; @r{Else, insert blanks.}
20546 (make-string width-of-label ? )
20548 (setq height (1- height)))
20551 ;; @r{Insert base line.}
20552 (setq Y-axis (cons (Y-axis-element
20553 (or vertical-step 1)
20556 (nreverse Y-axis)))
20560 The values for the maximum height of graph and the width of a symbol
20561 are computed by @code{print-graph} in its @code{let} expression; so
20562 @code{graph-body-print} must be changed to accept them.
20564 @findex graph-body-print @r{Final version.}
20567 ;;; @r{Final version.}
20568 (defun graph-body-print (numbers-list height symbol-width)
20569 "Print a bar graph of the NUMBERS-LIST.
20570 The numbers-list consists of the Y-axis values.
20571 HEIGHT is maximum height of graph.
20572 SYMBOL-WIDTH is number of each column."
20575 (let (from-position)
20576 (while numbers-list
20577 (setq from-position (point))
20579 (column-of-graph height (car numbers-list)))
20580 (goto-char from-position)
20581 (forward-char symbol-width)
20584 ;; @r{Draw graph column by column.}
20586 (setq numbers-list (cdr numbers-list)))
20587 ;; @r{Place point for X axis labels.}
20588 (forward-line height)
20594 Finally, the code for the @code{print-graph} function:
20596 @findex print-graph @r{Final version.}
20599 ;;; @r{Final version.}
20601 (numbers-list &optional vertical-step)
20602 "Print labeled 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."
20613 (let* ((symbol-width (length graph-blank))
20614 ;; @code{height} @r{is both the largest number}
20615 ;; @r{and the number with the most digits.}
20616 (height (apply 'max numbers-list))
20619 (height-of-top-line
20620 (if (zerop (% height Y-axis-label-spacing))
20623 (* (1+ (/ height Y-axis-label-spacing))
20624 Y-axis-label-spacing)))
20627 (vertical-step (or vertical-step 1))
20628 (full-Y-label-width
20634 (* height-of-top-line vertical-step))
20640 height-of-top-line full-Y-label-width vertical-step)
20644 numbers-list height-of-top-line symbol-width)
20645 (print-X-axis numbers-list)))
20649 @node Test print-graph
20650 @appendixsubsec Testing @code{print-graph}
20653 We can test the @code{print-graph} function with a short list of numbers:
20657 Install the final versions of @code{Y-axis-column},
20658 @code{graph-body-print}, and @code{print-graph} (in addition to the
20662 Copy the following expression:
20665 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1))
20669 Switch to the @file{*scratch*} buffer and place the cursor where you
20670 want the axis labels to start.
20673 Type @kbd{M-:} (@code{eval-expression}).
20676 Yank the test expression into the minibuffer
20677 with @kbd{C-y} (@code{yank)}.
20680 Press @key{RET} to evaluate the expression.
20684 Emacs will print a graph that looks like this:
20705 On the other hand, if you pass @code{print-graph} a
20706 @code{vertical-step} value of 2, by evaluating this expression:
20709 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2)
20714 The graph looks like this:
20735 (A question: is the @samp{2} on the bottom of the vertical axis a bug or a
20736 feature? If you think it is a bug, and should be a @samp{1} instead, (or
20737 even a @samp{0}), you can modify the sources.)
20739 @node Graphing words in defuns
20740 @appendixsubsec Graphing Numbers of Words and Symbols
20742 Now for the graph for which all this code was written: a graph that
20743 shows how many function definitions contain fewer than 10 words and
20744 symbols, how many contain between 10 and 19 words and symbols, how
20745 many contain between 20 and 29 words and symbols, and so on.
20747 This is a multi-step process. First make sure you have loaded all the
20751 It is a good idea to reset the value of @code{top-of-ranges} in case
20752 you have set it to some different value. You can evaluate the
20757 (setq top-of-ranges
20760 110 120 130 140 150
20761 160 170 180 190 200
20762 210 220 230 240 250
20763 260 270 280 290 300)
20768 Next create a list of the number of words and symbols in each range.
20772 Evaluate the following:
20776 (setq list-for-graph
20779 (recursive-lengths-list-many-files
20780 (directory-files "/usr/local/emacs/lisp"
20788 On my old machine, this took about an hour. It looked though 303 Lisp
20789 files in my copy of Emacs version 19.23. After all that computing,
20790 the @code{list-for-graph} had this value:
20794 (537 1027 955 785 594 483 349 292 224 199 166 120 116 99
20795 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220)
20800 This means that my copy of Emacs had 537 function definitions with
20801 fewer than 10 words or symbols in them, 1,027 function definitions
20802 with 10 to 19 words or symbols in them, 955 function definitions with
20803 20 to 29 words or symbols in them, and so on.
20805 Clearly, just by looking at this list we can see that most function
20806 definitions contain ten to thirty words and symbols.
20808 Now for printing. We do @emph{not} want to print a graph that is
20809 1,030 lines high @dots{} Instead, we should print a graph that is
20810 fewer than twenty-five lines high. A graph that height can be
20811 displayed on almost any monitor, and easily printed on a sheet of paper.
20813 This means that each value in @code{list-for-graph} must be reduced to
20814 one-fiftieth its present value.
20816 Here is a short function to do just that, using two functions we have
20817 not yet seen, @code{mapcar} and @code{lambda}.
20821 (defun one-fiftieth (full-range)
20822 "Return list, each number one-fiftieth of previous."
20823 (mapcar (lambda (arg) (/ arg 50)) full-range))
20828 @appendixsubsec A @code{lambda} Expression: Useful Anonymity
20829 @cindex Anonymous function
20832 @code{lambda} is the symbol for an anonymous function, a function
20833 without a name. Every time you use an anonymous function, you need to
20834 include its whole body.
20841 (lambda (arg) (/ arg 50))
20845 is a function that returns the value resulting from
20846 dividing whatever is passed to it as @code{arg} by 50.
20849 Earlier, for example, we had a function @code{multiply-by-seven}; it
20850 multiplied its argument by 7. This function is similar, except it
20851 divides its argument by 50; and, it has no name. The anonymous
20852 equivalent of @code{multiply-by-seven} is:
20855 (lambda (number) (* 7 number))
20859 (@xref{defun, , The @code{defun} Macro}.)
20863 If we want to multiply 3 by 7, we can write:
20865 @c clear print-postscript-figures
20866 @c lambda example diagram #1
20870 (multiply-by-seven 3)
20871 \_______________/ ^
20877 @ifset print-postscript-figures
20880 @center @image{lambda-1}
20884 @ifclear print-postscript-figures
20888 (multiply-by-seven 3)
20889 \_______________/ ^
20898 This expression returns 21.
20902 Similarly, we can write:
20904 @c lambda example diagram #2
20908 ((lambda (number) (* 7 number)) 3)
20909 \____________________________/ ^
20911 anonymous function argument
20915 @ifset print-postscript-figures
20918 @center @image{lambda-2}
20922 @ifclear print-postscript-figures
20926 ((lambda (number) (* 7 number)) 3)
20927 \____________________________/ ^
20929 anonymous function argument
20937 If we want to divide 100 by 50, we can write:
20939 @c lambda example diagram #3
20943 ((lambda (arg) (/ arg 50)) 100)
20944 \______________________/ \_/
20946 anonymous function argument
20950 @ifset print-postscript-figures
20953 @center @image{lambda-3}
20957 @ifclear print-postscript-figures
20961 ((lambda (arg) (/ arg 50)) 100)
20962 \______________________/ \_/
20964 anonymous function argument
20971 This expression returns 2. The 100 is passed to the function, which
20972 divides that number by 50.
20974 @xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs
20975 Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda
20976 expressions derive from the Lambda Calculus.
20979 @appendixsubsec The @code{mapcar} Function
20982 @code{mapcar} is a function that calls its first argument with each
20983 element of its second argument, in turn. The second argument must be
20986 The @samp{map} part of the name comes from the mathematical phrase,
20987 ``mapping over a domain'', meaning to apply a function to each of the
20988 elements in a domain. The mathematical phrase is based on the
20989 metaphor of a surveyor walking, one step at a time, over an area he is
20990 mapping. And @samp{car}, of course, comes from the Lisp notion of the
20999 (mapcar '1+ '(2 4 6))
21005 The function @code{1+} which adds one to its argument, is executed on
21006 @emph{each} element of the list, and a new list is returned.
21008 Contrast this with @code{apply}, which applies its first argument to
21010 (@xref{Readying a Graph, , Readying a Graph}, for a explanation of
21014 In the definition of @code{one-fiftieth}, the first argument is the
21015 anonymous function:
21018 (lambda (arg) (/ arg 50))
21022 and the second argument is @code{full-range}, which will be bound to
21023 @code{list-for-graph}.
21026 The whole expression looks like this:
21029 (mapcar (lambda (arg) (/ arg 50)) full-range))
21032 @xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs
21033 Lisp Reference Manual}, for more about @code{mapcar}.
21035 Using the @code{one-fiftieth} function, we can generate a list in
21036 which each element is one-fiftieth the size of the corresponding
21037 element in @code{list-for-graph}.
21041 (setq fiftieth-list-for-graph
21042 (one-fiftieth list-for-graph))
21047 The resulting list looks like this:
21051 (10 20 19 15 11 9 6 5 4 3 3 2 2
21052 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4)
21057 This, we are almost ready to print! (We also notice the loss of
21058 information: many of the higher ranges are 0, meaning that fewer than
21059 50 defuns had that many words or symbols---but not necessarily meaning
21060 that none had that many words or symbols.)
21063 @appendixsubsec Another Bug @dots{} Most Insidious
21064 @cindex Bug, most insidious type
21065 @cindex Insidious type of bug
21067 I said ``almost ready to print''! Of course, there is a bug in the
21068 @code{print-graph} function @dots{} It has a @code{vertical-step}
21069 option, but not a @code{horizontal-step} option. The
21070 @code{top-of-range} scale goes from 10 to 300 by tens. But the
21071 @code{print-graph} function will print only by ones.
21073 This is a classic example of what some consider the most insidious
21074 type of bug, the bug of omission. This is not the kind of bug you can
21075 find by studying the code, for it is not in the code; it is an omitted
21076 feature. Your best actions are to try your program early and often;
21077 and try to arrange, as much as you can, to write code that is easy to
21078 understand and easy to change. Try to be aware, whenever you can,
21079 that whatever you have written, @emph{will} be rewritten, if not soon,
21080 eventually. A hard maxim to follow.
21082 It is the @code{print-X-axis-numbered-line} function that needs the
21083 work; and then the @code{print-X-axis} and the @code{print-graph}
21084 functions need to be adapted. Not much needs to be done; there is one
21085 nicety: the numbers ought to line up under the tic marks. This takes
21089 Here is the corrected @code{print-X-axis-numbered-line}:
21093 (defun print-X-axis-numbered-line
21094 (number-of-X-tics X-axis-leading-spaces
21095 &optional horizontal-step)
21096 "Print line of X-axis numbers"
21097 (let ((number X-axis-label-spacing)
21098 (horizontal-step (or horizontal-step 1)))
21101 (insert X-axis-leading-spaces)
21102 ;; @r{Delete extra leading spaces.}
21105 (length (number-to-string horizontal-step)))))
21110 ;; @r{Insert white space.}
21112 X-axis-label-spacing)
21115 (number-to-string horizontal-step)))
21119 (* number horizontal-step))))
21122 ;; @r{Insert remaining numbers.}
21123 (setq number (+ number X-axis-label-spacing))
21124 (while (> number-of-X-tics 1)
21125 (insert (X-axis-element
21126 (* number horizontal-step)))
21127 (setq number (+ number X-axis-label-spacing))
21128 (setq number-of-X-tics (1- number-of-X-tics)))))
21133 If you are reading this in Info, you can see the new versions of
21134 @code{print-X-axis} @code{print-graph} and evaluate them. If you are
21135 reading this in a printed book, you can see the changed lines here
21136 (the full text is too much to print).
21141 (defun print-X-axis (numbers-list horizontal-step)
21143 (print-X-axis-numbered-line
21144 tic-number leading-spaces horizontal-step))
21152 &optional vertical-step horizontal-step)
21154 (print-X-axis numbers-list horizontal-step))
21162 (defun print-X-axis (numbers-list horizontal-step)
21163 "Print X axis labels to length of NUMBERS-LIST.
21164 Optionally, HORIZONTAL-STEP, a positive integer,
21165 specifies how much an X axis label increments for
21169 ;; Value of symbol-width and full-Y-label-width
21170 ;; are passed by print-graph.
21171 (let* ((leading-spaces
21172 (make-string full-Y-label-width ? ))
21173 ;; symbol-width @r{is provided by} graph-body-print
21174 (tic-width (* symbol-width X-axis-label-spacing))
21175 (X-length (length numbers-list))
21181 ;; @r{Make a string of blanks.}
21182 (- (* symbol-width X-axis-label-spacing)
21183 (length X-axis-tic-symbol))
21187 ;; @r{Concatenate blanks with tic symbol.}
21188 X-axis-tic-symbol))
21190 (if (zerop (% X-length tic-width))
21191 (/ X-length tic-width)
21192 (1+ (/ X-length tic-width)))))
21196 (print-X-axis-tic-line
21197 tic-number leading-spaces X-tic)
21199 (print-X-axis-numbered-line
21200 tic-number leading-spaces horizontal-step)))
21207 (numbers-list &optional vertical-step horizontal-step)
21208 "Print labeled bar graph of the NUMBERS-LIST.
21209 The numbers-list consists of the Y-axis values.
21213 Optionally, VERTICAL-STEP, a positive integer,
21214 specifies how much a Y axis label increments for
21215 each line. For example, a step of 5 means that
21216 each row is five units.
21220 Optionally, HORIZONTAL-STEP, a positive integer,
21221 specifies how much an X axis label increments for
21223 (let* ((symbol-width (length graph-blank))
21224 ;; @code{height} @r{is both the largest number}
21225 ;; @r{and the number with the most digits.}
21226 (height (apply 'max numbers-list))
21229 (height-of-top-line
21230 (if (zerop (% height Y-axis-label-spacing))
21233 (* (1+ (/ height Y-axis-label-spacing))
21234 Y-axis-label-spacing)))
21237 (vertical-step (or vertical-step 1))
21238 (full-Y-label-width
21242 (* height-of-top-line vertical-step))
21247 height-of-top-line full-Y-label-width vertical-step)
21249 numbers-list height-of-top-line symbol-width)
21250 (print-X-axis numbers-list horizontal-step)))
21257 Graphing Definitions Re-listed
21260 Here are all the graphing definitions in their final form:
21264 (defvar top-of-ranges
21267 110 120 130 140 150
21268 160 170 180 190 200
21269 210 220 230 240 250)
21270 "List specifying ranges for `defuns-per-range'.")
21274 (defvar graph-symbol "*"
21275 "String used as symbol in graph, usually an asterisk.")
21279 (defvar graph-blank " "
21280 "String used as blank in graph, usually a blank space.
21281 graph-blank must be the same number of columns wide
21286 (defvar Y-axis-tic " - "
21287 "String that follows number in a Y axis label.")
21291 (defvar Y-axis-label-spacing 5
21292 "Number of lines from one Y axis label to next.")
21296 (defvar X-axis-tic-symbol "|"
21297 "String to insert to point to a column in X axis.")
21301 (defvar X-axis-label-spacing
21302 (if (boundp 'graph-blank)
21303 (* 5 (length graph-blank)) 5)
21304 "Number of units from one X axis label to next.")
21310 (defun count-words-in-defun ()
21311 "Return the number of words and symbols in a defun."
21312 (beginning-of-defun)
21314 (end (save-excursion (end-of-defun) (point))))
21319 (and (< (point) end)
21321 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
21323 (setq count (1+ count)))
21330 (defun lengths-list-file (filename)
21331 "Return list of definitions' lengths within FILE.
21332 The returned list is a list of numbers.
21333 Each number is the number of words or
21334 symbols in one function definition."
21338 (message "Working on `%s' ... " filename)
21340 (let ((buffer (find-file-noselect filename))
21342 (set-buffer buffer)
21343 (setq buffer-read-only t)
21345 (goto-char (point-min))
21349 (while (re-search-forward "^(defun" nil t)
21351 (cons (count-words-in-defun) lengths-list)))
21352 (kill-buffer buffer)
21359 (defun lengths-list-many-files (list-of-files)
21360 "Return list of lengths of defuns in LIST-OF-FILES."
21361 (let (lengths-list)
21362 ;;; @r{true-or-false-test}
21363 (while list-of-files
21369 ;;; @r{Generate a lengths' list.}
21371 (expand-file-name (car list-of-files)))))
21372 ;;; @r{Make files' list shorter.}
21373 (setq list-of-files (cdr list-of-files)))
21374 ;;; @r{Return final value of lengths' list.}
21381 (defun defuns-per-range (sorted-lengths top-of-ranges)
21382 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
21383 (let ((top-of-range (car top-of-ranges))
21384 (number-within-range 0)
21385 defuns-per-range-list)
21390 (while top-of-ranges
21394 ;; @r{Need number for numeric test.}
21395 (car sorted-lengths)
21396 (< (car sorted-lengths) top-of-range))
21398 ;; @r{Count number of definitions within current range.}
21399 (setq number-within-range (1+ number-within-range))
21400 (setq sorted-lengths (cdr sorted-lengths)))
21404 ;; @r{Exit inner loop but remain within outer loop.}
21406 (setq defuns-per-range-list
21407 (cons number-within-range defuns-per-range-list))
21408 (setq number-within-range 0) ; @r{Reset count to zero.}
21410 ;; @r{Move to next range.}
21411 (setq top-of-ranges (cdr top-of-ranges))
21412 ;; @r{Specify next top of range value.}
21413 (setq top-of-range (car top-of-ranges)))
21417 ;; @r{Exit outer loop and count the number of defuns larger than}
21418 ;; @r{ the largest top-of-range value.}
21419 (setq defuns-per-range-list
21421 (length sorted-lengths)
21422 defuns-per-range-list))
21424 ;; @r{Return a list of the number of definitions within each range,}
21425 ;; @r{ smallest to largest.}
21426 (nreverse defuns-per-range-list)))
21432 (defun column-of-graph (max-graph-height actual-height)
21433 "Return list of MAX-GRAPH-HEIGHT strings;
21434 ACTUAL-HEIGHT are graph-symbols.
21435 The graph-symbols are contiguous entries at the end
21437 The list will be inserted as one column of a graph.
21438 The strings are either graph-blank or graph-symbol."
21442 (let ((insert-list nil)
21443 (number-of-top-blanks
21444 (- max-graph-height actual-height)))
21446 ;; @r{Fill in @code{graph-symbols}.}
21447 (while (> actual-height 0)
21448 (setq insert-list (cons graph-symbol insert-list))
21449 (setq actual-height (1- actual-height)))
21453 ;; @r{Fill in @code{graph-blanks}.}
21454 (while (> number-of-top-blanks 0)
21455 (setq insert-list (cons graph-blank insert-list))
21456 (setq number-of-top-blanks
21457 (1- number-of-top-blanks)))
21459 ;; @r{Return whole list.}
21466 (defun Y-axis-element (number full-Y-label-width)
21467 "Construct a NUMBERed label element.
21468 A numbered element looks like this ` 5 - ',
21469 and is padded as needed so all line up with
21470 the element for the largest number."
21473 (let* ((leading-spaces
21474 (- full-Y-label-width
21476 (concat (number-to-string number)
21481 (make-string leading-spaces ? )
21482 (number-to-string number)
21489 (defun print-Y-axis
21490 (height full-Y-label-width &optional vertical-step)
21491 "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH.
21492 Height must be the maximum height of the graph.
21493 Full width is the width of the highest label element.
21494 Optionally, print according to VERTICAL-STEP."
21497 ;; Value of height and full-Y-label-width
21498 ;; are passed by 'print-graph'.
21499 (let ((start (point)))
21501 (Y-axis-column height full-Y-label-width vertical-step))
21504 ;; @r{Place point ready for inserting graph.}
21506 ;; @r{Move point forward by value of} full-Y-label-width
21507 (forward-char full-Y-label-width)))
21513 (defun print-X-axis-tic-line
21514 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
21515 "Print ticks for X axis."
21516 (insert X-axis-leading-spaces)
21517 (insert X-axis-tic-symbol) ; @r{Under first column.}
21520 ;; @r{Insert second tic in the right spot.}
21523 (- (* symbol-width X-axis-label-spacing)
21524 ;; @r{Insert white space up to second tic symbol.}
21525 (* 2 (length X-axis-tic-symbol)))
21527 X-axis-tic-symbol))
21530 ;; @r{Insert remaining ticks.}
21531 (while (> number-of-X-tics 1)
21532 (insert X-axis-tic-element)
21533 (setq number-of-X-tics (1- number-of-X-tics))))
21539 (defun X-axis-element (number)
21540 "Construct a numbered X axis element."
21541 (let ((leading-spaces
21542 (- (* symbol-width X-axis-label-spacing)
21543 (length (number-to-string number)))))
21544 (concat (make-string leading-spaces ? )
21545 (number-to-string number))))
21551 (defun graph-body-print (numbers-list height symbol-width)
21552 "Print a bar graph of the NUMBERS-LIST.
21553 The numbers-list consists of the Y-axis values.
21554 HEIGHT is maximum height of graph.
21555 SYMBOL-WIDTH is number of each column."
21558 (let (from-position)
21559 (while numbers-list
21560 (setq from-position (point))
21562 (column-of-graph height (car numbers-list)))
21563 (goto-char from-position)
21564 (forward-char symbol-width)
21567 ;; @r{Draw graph column by column.}
21569 (setq numbers-list (cdr numbers-list)))
21570 ;; @r{Place point for X axis labels.}
21571 (forward-line height)
21578 (defun Y-axis-column
21579 (height width-of-label &optional vertical-step)
21580 "Construct list of labels for Y axis.
21581 HEIGHT is maximum height of graph.
21582 WIDTH-OF-LABEL is maximum width of label.
21585 VERTICAL-STEP, an option, is a positive integer
21586 that specifies how much a Y axis label increments
21587 for each line. For example, a step of 5 means
21588 that each line is five units of the graph."
21590 (number-per-line (or vertical-step 1)))
21593 (while (> height 1)
21594 (if (zerop (% height Y-axis-label-spacing))
21595 ;; @r{Insert label.}
21599 (* height number-per-line)
21604 ;; @r{Else, insert blanks.}
21607 (make-string width-of-label ? )
21609 (setq height (1- height)))
21612 ;; @r{Insert base line.}
21613 (setq Y-axis (cons (Y-axis-element
21614 (or vertical-step 1)
21617 (nreverse Y-axis)))
21623 (defun print-X-axis-numbered-line
21624 (number-of-X-tics X-axis-leading-spaces
21625 &optional horizontal-step)
21626 "Print line of X-axis numbers"
21627 (let ((number X-axis-label-spacing)
21628 (horizontal-step (or horizontal-step 1)))
21631 (insert X-axis-leading-spaces)
21633 (delete-char (- (1- (length (number-to-string horizontal-step)))))
21636 ;; @r{Insert white space up to next number.}
21637 (- (* symbol-width X-axis-label-spacing)
21638 (1- (length (number-to-string horizontal-step)))
21641 (number-to-string (* number horizontal-step))))
21644 ;; @r{Insert remaining numbers.}
21645 (setq number (+ number X-axis-label-spacing))
21646 (while (> number-of-X-tics 1)
21647 (insert (X-axis-element (* number horizontal-step)))
21648 (setq number (+ number X-axis-label-spacing))
21649 (setq number-of-X-tics (1- number-of-X-tics)))))
21655 (defun print-X-axis (numbers-list horizontal-step)
21656 "Print X axis labels to length of NUMBERS-LIST.
21657 Optionally, HORIZONTAL-STEP, a positive integer,
21658 specifies how much an X axis label increments for
21662 ;; Value of symbol-width and full-Y-label-width
21663 ;; are passed by 'print-graph'.
21664 (let* ((leading-spaces
21665 (make-string full-Y-label-width ? ))
21666 ;; symbol-width @r{is provided by} graph-body-print
21667 (tic-width (* symbol-width X-axis-label-spacing))
21668 (X-length (length numbers-list))
21674 ;; @r{Make a string of blanks.}
21675 (- (* symbol-width X-axis-label-spacing)
21676 (length X-axis-tic-symbol))
21680 ;; @r{Concatenate blanks with tic symbol.}
21681 X-axis-tic-symbol))
21683 (if (zerop (% X-length tic-width))
21684 (/ X-length tic-width)
21685 (1+ (/ X-length tic-width)))))
21689 (print-X-axis-tic-line
21690 tic-number leading-spaces X-tic)
21692 (print-X-axis-numbered-line
21693 tic-number leading-spaces horizontal-step)))
21699 (defun one-fiftieth (full-range)
21700 "Return list, each number of which is 1/50th previous."
21701 (mapcar (lambda (arg) (/ arg 50)) full-range))
21708 (numbers-list &optional vertical-step horizontal-step)
21709 "Print labeled bar graph of the NUMBERS-LIST.
21710 The numbers-list consists of the Y-axis values.
21714 Optionally, VERTICAL-STEP, a positive integer,
21715 specifies how much a Y axis label increments for
21716 each line. For example, a step of 5 means that
21717 each row is five units.
21721 Optionally, HORIZONTAL-STEP, a positive integer,
21722 specifies how much an X axis label increments for
21724 (let* ((symbol-width (length graph-blank))
21725 ;; @code{height} @r{is both the largest number}
21726 ;; @r{and the number with the most digits.}
21727 (height (apply 'max numbers-list))
21730 (height-of-top-line
21731 (if (zerop (% height Y-axis-label-spacing))
21734 (* (1+ (/ height Y-axis-label-spacing))
21735 Y-axis-label-spacing)))
21738 (vertical-step (or vertical-step 1))
21739 (full-Y-label-width
21743 (* height-of-top-line vertical-step))
21749 height-of-top-line full-Y-label-width vertical-step)
21751 numbers-list height-of-top-line symbol-width)
21752 (print-X-axis numbers-list horizontal-step)))
21759 @node Final printed graph
21760 @appendixsubsec The Printed Graph
21762 When made and installed, you can call the @code{print-graph} command
21768 (print-graph fiftieth-list-for-graph 50 10)
21798 50 - ***************** * *
21800 10 50 100 150 200 250 300 350
21807 The largest group of functions contain 10--19 words and symbols each.
21809 @node Free Software and Free Manuals
21810 @appendix Free Software and Free Manuals
21812 @strong{by Richard M. Stallman}
21815 The biggest deficiency in free operating systems is not in the
21816 software---it is the lack of good free manuals that we can include in
21817 these systems. Many of our most important programs do not come with
21818 full manuals. Documentation is an essential part of any software
21819 package; when an important free software package does not come with a
21820 free manual, that is a major gap. We have many such gaps today.
21822 Once upon a time, many years ago, I thought I would learn Perl. I got
21823 a copy of a free manual, but I found it hard to read. When I asked
21824 Perl users about alternatives, they told me that there were better
21825 introductory manuals---but those were not free.
21827 Why was this? The authors of the good manuals had written them for
21828 O'Reilly Associates, which published them with restrictive terms---no
21829 copying, no modification, source files not available---which exclude
21830 them from the free software community.
21832 That wasn't the first time this sort of thing has happened, and (to
21833 our community's great loss) it was far from the last. Proprietary
21834 manual publishers have enticed a great many authors to restrict their
21835 manuals since then. Many times I have heard a GNU user eagerly tell me
21836 about a manual that he is writing, with which he expects to help the
21837 GNU project---and then had my hopes dashed, as he proceeded to explain
21838 that he had signed a contract with a publisher that would restrict it
21839 so that we cannot use it.
21841 Given that writing good English is a rare skill among programmers, we
21842 can ill afford to lose manuals this way.
21844 Free documentation, like free software, is a matter of freedom, not
21845 price. The problem with these manuals was not that O'Reilly Associates
21846 charged a price for printed copies---that in itself is fine. The Free
21847 Software Foundation @uref{http://shop.fsf.org, sells printed copies} of
21848 free @uref{http://www.gnu.org/doc/doc.html, GNU manuals}, too.
21849 But GNU manuals are available in source code form, while these manuals
21850 are available only on paper. GNU manuals come with permission to copy
21851 and modify; the Perl manuals do not. These restrictions are the
21854 The criterion for a free manual is pretty much the same as for free
21855 software: it is a matter of giving all users certain
21856 freedoms. Redistribution (including commercial redistribution) must be
21857 permitted, so that the manual can accompany every copy of the program,
21858 on-line or on paper. Permission for modification is crucial too.
21860 As a general rule, I don't believe that it is essential for people to
21861 have permission to modify all sorts of articles and books. The issues
21862 for writings are not necessarily the same as those for software. For
21863 example, I don't think you or I are obliged to give permission to
21864 modify articles like this one, which describe our actions and our
21867 But there is a particular reason why the freedom to modify is crucial
21868 for documentation for free software. When people exercise their right
21869 to modify the software, and add or change its features, if they are
21870 conscientious they will change the manual too---so they can provide
21871 accurate and usable documentation with the modified program. A manual
21872 which forbids programmers to be conscientious and finish the job, or
21873 more precisely requires them to write a new manual from scratch if
21874 they change the program, does not fill our community's needs.
21876 While a blanket prohibition on modification is unacceptable, some
21877 kinds of limits on the method of modification pose no problem. For
21878 example, requirements to preserve the original author's copyright
21879 notice, the distribution terms, or the list of authors, are ok. It is
21880 also no problem to require modified versions to include notice that
21881 they were modified, even to have entire sections that may not be
21882 deleted or changed, as long as these sections deal with nontechnical
21883 topics. (Some GNU manuals have them.)
21885 These kinds of restrictions are not a problem because, as a practical
21886 matter, they don't stop the conscientious programmer from adapting the
21887 manual to fit the modified program. In other words, they don't block
21888 the free software community from making full use of the manual.
21890 However, it must be possible to modify all the technical content of
21891 the manual, and then distribute the result in all the usual media,
21892 through all the usual channels; otherwise, the restrictions do block
21893 the community, the manual is not free, and so we need another manual.
21895 Unfortunately, it is often hard to find someone to write another
21896 manual when a proprietary manual exists. The obstacle is that many
21897 users think that a proprietary manual is good enough---so they don't
21898 see the need to write a free manual. They do not see that the free
21899 operating system has a gap that needs filling.
21901 Why do users think that proprietary manuals are good enough? Some have
21902 not considered the issue. I hope this article will do something to
21905 Other users consider proprietary manuals acceptable for the same
21906 reason so many people consider proprietary software acceptable: they
21907 judge in purely practical terms, not using freedom as a
21908 criterion. These people are entitled to their opinions, but since
21909 those opinions spring from values which do not include freedom, they
21910 are no guide for those of us who do value freedom.
21912 Please spread the word about this issue. We continue to lose manuals
21913 to proprietary publishing. If we spread the word that proprietary
21914 manuals are not sufficient, perhaps the next person who wants to help
21915 GNU by writing documentation will realize, before it is too late, that
21916 he must above all make it free.
21918 We can also encourage commercial publishers to sell free, copylefted
21919 manuals instead of proprietary ones. One way you can help this is to
21920 check the distribution terms of a manual before you buy it, and prefer
21921 copylefted manuals to non-copylefted ones.
21925 Note: The Free Software Foundation maintains a page on its Web site
21926 that lists free books available from other publishers:@*
21927 @uref{http://www.gnu.org/doc/other-free-books.html}
21929 @node GNU Free Documentation License
21930 @appendix GNU Free Documentation License
21932 @cindex FDL, GNU Free Documentation License
21933 @include doclicense.texi
21939 MENU ENTRY: NODE NAME.
21945 @c Place biographical information on right-hand (verso) page
21948 \par\vfill\supereject
21950 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
21951 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
21954 % \par\vfill\supereject
21955 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
21956 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
21957 %\page\hbox{}%\page
21958 %\page\hbox{}%\page
21965 @c ================ Biographical information ================
21969 @center About the Author
21974 @node About the Author
21975 @unnumbered About the Author
21979 Robert J. Chassell has worked with GNU Emacs since 1985. He writes
21980 and edits, teaches Emacs and Emacs Lisp, and speaks throughout the
21981 world on software freedom. Chassell was a founding Director and
21982 Treasurer of the Free Software Foundation, Inc. He is co-author of
21983 the @cite{Texinfo} manual, and has edited more than a dozen other
21984 books. He graduated from Cambridge University, in England. He has an
21985 abiding interest in social and economic history and flies his own
21992 @c @c Prevent page number on blank verso, so eject it first.
21994 @c \par\vfill\supereject
21999 @c @evenheading @thispage @| @| @thistitle
22000 @c @oddheading @| @| @thispage