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--2016 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 an apostrophe @samp{'},
1008 called a @dfn{single-quote} in Lisp.@footnote{A single-quote is an
1009 abbreviation for the special form @code{quote}; you need not think
1010 about special forms now. @xref{Complications}.} Lists are the basis
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-quote @samp{'} tells the Lisp interpreter that it should
2494 return the following expression as written, and not evaluate it as it
2495 would if the quote were not there.
2498 Arguments are the information passed to a function. The arguments to a
2499 function are computed by evaluating the rest of the elements of the list
2500 of which the function is the first element.
2503 A function always returns a value when it is evaluated (unless it gets
2504 an error); in addition, it may also carry out some action that is a
2505 side effect. In many cases, a function's primary purpose is to
2506 create a side effect.
2509 @node Error Message Exercises
2512 A few simple exercises:
2516 Generate an error message by evaluating an appropriate symbol that is
2517 not within parentheses.
2520 Generate an error message by evaluating an appropriate symbol that is
2521 between parentheses.
2524 Create a counter that increments by two rather than one.
2527 Write an expression that prints a message in the echo area when
2531 @node Practicing Evaluation
2532 @chapter Practicing Evaluation
2533 @cindex Practicing evaluation
2534 @cindex Evaluation practice
2536 Before learning how to write a function definition in Emacs Lisp, it is
2537 useful to spend a little time evaluating various expressions that have
2538 already been written. These expressions will be lists with the
2539 functions as their first (and often only) element. Since some of the
2540 functions associated with buffers are both simple and interesting, we
2541 will start with those. In this section, we will evaluate a few of
2542 these. In another section, we will study the code of several other
2543 buffer-related functions, to see how they were written.
2546 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
2548 * Buffer Names:: Buffers and files are different.
2549 * Getting Buffers:: Getting a buffer itself, not merely its name.
2550 * Switching Buffers:: How to change to another buffer.
2551 * Buffer Size & Locations:: Where point is located and the size of
2553 * Evaluation Exercise::
2557 @node How to Evaluate
2558 @unnumberedsec How to Evaluate
2561 @i{Whenever you give an editing command} to Emacs Lisp, such as the
2562 command to move the cursor or to scroll the screen, @i{you are evaluating
2563 an expression,} the first element of which is a function. @i{This is
2566 @cindex @samp{interactive function} defined
2567 @cindex @samp{command} defined
2568 When you type keys, you cause the Lisp interpreter to evaluate an
2569 expression and that is how you get your results. Even typing plain text
2570 involves evaluating an Emacs Lisp function, in this case, one that uses
2571 @code{self-insert-command}, which simply inserts the character you
2572 typed. The functions you evaluate by typing keystrokes are called
2573 @dfn{interactive} functions, or @dfn{commands}; how you make a function
2574 interactive will be illustrated in the chapter on how to write function
2575 definitions. @xref{Interactive, , Making a Function Interactive}.
2577 In addition to typing keyboard commands, we have seen a second way to
2578 evaluate an expression: by positioning the cursor after a list and
2579 typing @kbd{C-x C-e}. This is what we will do in the rest of this
2580 section. There are other ways to evaluate an expression as well; these
2581 will be described as we come to them.
2583 Besides being used for practicing evaluation, the functions shown in the
2584 next few sections are important in their own right. A study of these
2585 functions makes clear the distinction between buffers and files, how to
2586 switch to a buffer, and how to determine a location within it.
2589 @section Buffer Names
2591 @findex buffer-file-name
2593 The two functions, @code{buffer-name} and @code{buffer-file-name}, show
2594 the difference between a file and a buffer. When you evaluate the
2595 following expression, @code{(buffer-name)}, the name of the buffer
2596 appears in the echo area. When you evaluate @code{(buffer-file-name)},
2597 the name of the file to which the buffer refers appears in the echo
2598 area. Usually, the name returned by @code{(buffer-name)} is the same as
2599 the name of the file to which it refers, and the name returned by
2600 @code{(buffer-file-name)} is the full path-name of the file.
2602 A file and a buffer are two different entities. A file is information
2603 recorded permanently in the computer (unless you delete it). A buffer,
2604 on the other hand, is information inside of Emacs that will vanish at
2605 the end of the editing session (or when you kill the buffer). Usually,
2606 a buffer contains information that you have copied from a file; we say
2607 the buffer is @dfn{visiting} that file. This copy is what you work on
2608 and modify. Changes to the buffer do not change the file, until you
2609 save the buffer. When you save the buffer, the buffer is copied to the file
2610 and is thus saved permanently.
2613 If you are reading this in Info inside of GNU Emacs, you can evaluate
2614 each of the following expressions by positioning the cursor after it and
2615 typing @kbd{C-x C-e}.
2626 When I do this in Info, the value returned by evaluating
2627 @code{(buffer-name)} is @file{"*info*"}, and the value returned by
2628 evaluating @code{(buffer-file-name)} is @file{nil}.
2630 On the other hand, while I am writing this document, the value
2631 returned by evaluating @code{(buffer-name)} is
2632 @file{"introduction.texinfo"}, and the value returned by evaluating
2633 @code{(buffer-file-name)} is
2634 @file{"/gnu/work/intro/introduction.texinfo"}.
2636 @cindex @code{nil}, history of word
2637 The former is the name of the buffer and the latter is the name of the
2638 file. In Info, the buffer name is @file{"*info*"}. Info does not
2639 point to any file, so the result of evaluating
2640 @code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is
2641 from the Latin word for ``nothing''; in this case, it means that the
2642 buffer is not associated with any file. (In Lisp, @code{nil} is also
2643 used to mean ``false'' and is a synonym for the empty list, @code{()}.)
2645 When I am writing, the name of my buffer is
2646 @file{"introduction.texinfo"}. The name of the file to which it
2647 points is @file{"/gnu/work/intro/introduction.texinfo"}.
2649 (In the expressions, the parentheses tell the Lisp interpreter to
2650 treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as
2651 functions; without the parentheses, the interpreter would attempt to
2652 evaluate the symbols as variables. @xref{Variables}.)
2654 In spite of the distinction between files and buffers, you will often
2655 find that people refer to a file when they mean a buffer and vice versa.
2656 Indeed, most people say, ``I am editing a file,'' rather than saying,
2657 ``I am editing a buffer which I will soon save to a file.'' It is
2658 almost always clear from context what people mean. When dealing with
2659 computer programs, however, it is important to keep the distinction in mind,
2660 since the computer is not as smart as a person.
2662 @cindex Buffer, history of word
2663 The word ``buffer'', by the way, comes from the meaning of the word as a
2664 cushion that deadens the force of a collision. In early computers, a
2665 buffer cushioned the interaction between files and the computer's
2666 central processing unit. The drums or tapes that held a file and the
2667 central processing unit were pieces of equipment that were very
2668 different from each other, working at their own speeds, in spurts. The
2669 buffer made it possible for them to work together effectively.
2670 Eventually, the buffer grew from being an intermediary, a temporary
2671 holding place, to being the place where work is done. This
2672 transformation is rather like that of a small seaport that grew into a
2673 great city: once it was merely the place where cargo was warehoused
2674 temporarily before being loaded onto ships; then it became a business
2675 and cultural center in its own right.
2677 Not all buffers are associated with files. For example, a
2678 @file{*scratch*} buffer does not visit any file. Similarly, a
2679 @file{*Help*} buffer is not associated with any file.
2681 In the old days, when you lacked a @file{~/.emacs} file and started an
2682 Emacs session by typing the command @code{emacs} alone, without naming
2683 any files, Emacs started with the @file{*scratch*} buffer visible.
2684 Nowadays, you will see a splash screen. You can follow one of the
2685 commands suggested on the splash screen, visit a file, or press the
2686 spacebar to reach the @file{*scratch*} buffer.
2688 If you switch to the @file{*scratch*} buffer, type
2689 @code{(buffer-name)}, position the cursor after it, and then type
2690 @kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"}
2691 will be returned and will appear in the echo area. @code{"*scratch*"}
2692 is the name of the buffer. When you type @code{(buffer-file-name)} in
2693 the @file{*scratch*} buffer and evaluate that, @code{nil} will appear
2694 in the echo area, just as it does when you evaluate
2695 @code{(buffer-file-name)} in Info.
2697 Incidentally, if you are in the @file{*scratch*} buffer and want the
2698 value returned by an expression to appear in the @file{*scratch*}
2699 buffer itself rather than in the echo area, type @kbd{C-u C-x C-e}
2700 instead of @kbd{C-x C-e}. This causes the value returned to appear
2701 after the expression. The buffer will look like this:
2704 (buffer-name)"*scratch*"
2708 You cannot do this in Info since Info is read-only and it will not allow
2709 you to change the contents of the buffer. But you can do this in any
2710 buffer you can edit; and when you write code or documentation (such as
2711 this book), this feature is very useful.
2713 @node Getting Buffers
2714 @section Getting Buffers
2715 @findex current-buffer
2716 @findex other-buffer
2717 @cindex Getting a buffer
2719 The @code{buffer-name} function returns the @emph{name} of the buffer;
2720 to get the buffer @emph{itself}, a different function is needed: the
2721 @code{current-buffer} function. If you use this function in code, what
2722 you get is the buffer itself.
2724 A name and the object or entity to which the name refers are different
2725 from each other. You are not your name. You are a person to whom
2726 others refer by name. If you ask to speak to George and someone hands you
2727 a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r},
2728 @samp{g}, and @samp{e} written on it, you might be amused, but you would
2729 not be satisfied. You do not want to speak to the name, but to the
2730 person to whom the name refers. A buffer is similar: the name of the
2731 scratch buffer is @file{*scratch*}, but the name is not the buffer. To
2732 get a buffer itself, you need to use a function such as
2733 @code{current-buffer}.
2735 However, there is a slight complication: if you evaluate
2736 @code{current-buffer} in an expression on its own, as we will do here,
2737 what you see is a printed representation of the name of the buffer
2738 without the contents of the buffer. Emacs works this way for two
2739 reasons: the buffer may be thousands of lines long---too long to be
2740 conveniently displayed; and, another buffer may have the same contents
2741 but a different name, and it is important to distinguish between them.
2744 Here is an expression containing the function:
2751 If you evaluate this expression in Info in Emacs in the usual way,
2752 @file{#<buffer *info*>} will appear in the echo area. The special
2753 format indicates that the buffer itself is being returned, rather than
2756 Incidentally, while you can type a number or symbol into a program, you
2757 cannot do that with the printed representation of a buffer: the only way
2758 to get a buffer itself is with a function such as @code{current-buffer}.
2760 A related function is @code{other-buffer}. This returns the most
2761 recently selected buffer other than the one you are in currently, not
2762 a printed representation of its name. If you have recently switched
2763 back and forth from the @file{*scratch*} buffer, @code{other-buffer}
2764 will return that buffer.
2767 You can see this by evaluating the expression:
2774 You should see @file{#<buffer *scratch*>} appear in the echo area, or
2775 the name of whatever other buffer you switched back from most
2776 recently@footnote{Actually, by default, if the buffer from which you
2777 just switched is visible to you in another window, @code{other-buffer}
2778 will choose the most recent buffer that you cannot see; this is a
2779 subtlety that I often forget.}.
2781 @node Switching Buffers
2782 @section Switching Buffers
2783 @findex switch-to-buffer
2785 @cindex Switching to a buffer
2787 The @code{other-buffer} function actually provides a buffer when it is
2788 used as an argument to a function that requires one. We can see this
2789 by using @code{other-buffer} and @code{switch-to-buffer} to switch to a
2792 But first, a brief introduction to the @code{switch-to-buffer}
2793 function. When you switched back and forth from Info to the
2794 @file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most
2795 likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or
2796 rather, to save typing, you probably only typed @kbd{RET} if the
2797 default buffer was @file{*scratch*}, or if it was different, then you
2798 typed just part of the name, such as @code{*sc}, pressed your
2799 @kbd{TAB} key to cause it to expand to the full name, and then typed
2800 @kbd{RET}.} when prompted in the minibuffer for the name of
2801 the buffer to which you wanted to switch. The keystrokes, @kbd{C-x
2802 b}, cause the Lisp interpreter to evaluate the interactive function
2803 @code{switch-to-buffer}. As we said before, this is how Emacs works:
2804 different keystrokes call or run different functions. For example,
2805 @kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls
2806 @code{forward-sentence}, and so on.
2808 By writing @code{switch-to-buffer} in an expression, and giving it a
2809 buffer to switch to, we can switch buffers just the way @kbd{C-x b}
2813 (switch-to-buffer (other-buffer))
2817 The symbol @code{switch-to-buffer} is the first element of the list,
2818 so the Lisp interpreter will treat it as a function and carry out the
2819 instructions that are attached to it. But before doing that, the
2820 interpreter will note that @code{other-buffer} is inside parentheses
2821 and work on that symbol first. @code{other-buffer} is the first (and
2822 in this case, the only) element of this list, so the Lisp interpreter
2823 calls or runs the function. It returns another buffer. Next, the
2824 interpreter runs @code{switch-to-buffer}, passing to it, as an
2825 argument, the other buffer, which is what Emacs will switch to. If
2826 you are reading this in Info, try this now. Evaluate the expression.
2827 (To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this
2828 expression will move you to your most recent other buffer that you
2829 cannot see. If you really want to go to your most recently selected
2830 buffer, even if you can still see it, you need to evaluate the
2831 following more complex expression:
2834 (switch-to-buffer (other-buffer (current-buffer) t))
2838 In this case, the first argument to @code{other-buffer} tells it which
2839 buffer to skip---the current one---and the second argument tells
2840 @code{other-buffer} it is OK to switch to a visible buffer. In
2841 regular use, @code{switch-to-buffer} takes you to a buffer not visible
2842 in windows since you would most likely use @kbd{C-x o}
2843 (@code{other-window}) to go to another visible buffer.}
2845 In the programming examples in later sections of this document, you will
2846 see the function @code{set-buffer} more often than
2847 @code{switch-to-buffer}. This is because of a difference between
2848 computer programs and humans: humans have eyes and expect to see the
2849 buffer on which they are working on their computer terminals. This is
2850 so obvious, it almost goes without saying. However, programs do not
2851 have eyes. When a computer program works on a buffer, that buffer does
2852 not need to be visible on the screen.
2854 @code{switch-to-buffer} is designed for humans and does two different
2855 things: it switches the buffer to which Emacs's attention is directed; and
2856 it switches the buffer displayed in the window to the new buffer.
2857 @code{set-buffer}, on the other hand, does only one thing: it switches
2858 the attention of the computer program to a different buffer. The buffer
2859 on the screen remains unchanged (of course, normally nothing happens
2860 there until the command finishes running).
2862 @cindex @samp{call} defined
2863 Also, we have just introduced another jargon term, the word @dfn{call}.
2864 When you evaluate a list in which the first symbol is a function, you
2865 are calling that function. The use of the term comes from the notion of
2866 the function as an entity that can do something for you if you call
2867 it---just as a plumber is an entity who can fix a leak if you call him
2870 @node Buffer Size & Locations
2871 @section Buffer Size and the Location of Point
2872 @cindex Size of buffer
2874 @cindex Point location
2875 @cindex Location of point
2877 Finally, let's look at several rather simple functions,
2878 @code{buffer-size}, @code{point}, @code{point-min}, and
2879 @code{point-max}. These give information about the size of a buffer and
2880 the location of point within it.
2882 The function @code{buffer-size} tells you the size of the current
2883 buffer; that is, the function returns a count of the number of
2884 characters in the buffer.
2891 You can evaluate this in the usual way, by positioning the
2892 cursor after the expression and typing @kbd{C-x C-e}.
2894 @cindex @samp{point} defined
2895 In Emacs, the current position of the cursor is called @dfn{point}.
2896 The expression @code{(point)} returns a number that tells you where the
2897 cursor is located as a count of the number of characters from the
2898 beginning of the buffer up to point.
2901 You can see the character count for point in this buffer by evaluating
2902 the following expression in the usual way:
2909 As I write this, the value of point is 65724. The @code{point}
2910 function is frequently used in some of the examples later in this
2914 The value of point depends, of course, on its location within the
2915 buffer. If you evaluate point in this spot, the number will be larger:
2922 For me, the value of point in this location is 66043, which means that
2923 there are 319 characters (including spaces) between the two
2924 expressions. (Doubtless, you will see different numbers, since I will
2925 have edited this since I first evaluated point.)
2927 @cindex @samp{narrowing} defined
2928 The function @code{point-min} is somewhat similar to @code{point}, but
2929 it returns the value of the minimum permissible value of point in the
2930 current buffer. This is the number 1 unless @dfn{narrowing} is in
2931 effect. (Narrowing is a mechanism whereby you can restrict yourself,
2932 or a program, to operations on just a part of a buffer.
2933 @xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the
2934 function @code{point-max} returns the value of the maximum permissible
2935 value of point in the current buffer.
2937 @node Evaluation Exercise
2940 Find a file with which you are working and move towards its middle.
2941 Find its buffer name, file name, length, and your position in the file.
2943 @node Writing Defuns
2944 @chapter How To Write Function Definitions
2945 @cindex Definition writing
2946 @cindex Function definition writing
2947 @cindex Writing a function definition
2949 When the Lisp interpreter evaluates a list, it looks to see whether the
2950 first symbol on the list has a function definition attached to it; or,
2951 put another way, whether the symbol points to a function definition. If
2952 it does, the computer carries out the instructions in the definition. A
2953 symbol that has a function definition is called, simply, a function
2954 (although, properly speaking, the definition is the function and the
2955 symbol refers to it.)
2958 * Primitive Functions::
2959 * defun:: The @code{defun} macro.
2960 * Install:: Install a function definition.
2961 * Interactive:: Making a function interactive.
2962 * Interactive Options:: Different options for @code{interactive}.
2963 * Permanent Installation:: Installing code permanently.
2964 * let:: Creating and initializing local variables.
2966 * else:: If--then--else expressions.
2967 * Truth & Falsehood:: What Lisp considers false and true.
2968 * save-excursion:: Keeping track of point and buffer.
2974 @node Primitive Functions
2975 @unnumberedsec An Aside about Primitive Functions
2977 @cindex Primitive functions
2978 @cindex Functions, primitive
2980 @cindex C language primitives
2981 @cindex Primitives written in C
2982 All functions are defined in terms of other functions, except for a few
2983 @dfn{primitive} functions that are written in the C programming
2984 language. When you write functions' definitions, you will write them in
2985 Emacs Lisp and use other functions as your building blocks. Some of the
2986 functions you will use will themselves be written in Emacs Lisp (perhaps
2987 by you) and some will be primitives written in C@. The primitive
2988 functions are used exactly like those written in Emacs Lisp and behave
2989 like them. They are written in C so we can easily run GNU Emacs on any
2990 computer that has sufficient power and can run C.
2992 Let me re-emphasize this: when you write code in Emacs Lisp, you do not
2993 distinguish between the use of functions written in C and the use of
2994 functions written in Emacs Lisp. The difference is irrelevant. I
2995 mention the distinction only because it is interesting to know. Indeed,
2996 unless you investigate, you won't know whether an already-written
2997 function is written in Emacs Lisp or C.
3000 @section The @code{defun} Macro
3003 @cindex @samp{function definition} defined
3004 In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to
3005 it that tells the computer what to do when the function is called.
3006 This code is called the @dfn{function definition} and is created by
3007 evaluating a Lisp expression that starts with the symbol @code{defun}
3008 (which is an abbreviation for @emph{define function}).
3010 In subsequent sections, we will look at function definitions from the
3011 Emacs source code, such as @code{mark-whole-buffer}. In this section,
3012 we will describe a simple function definition so you can see how it
3013 looks. This function definition uses arithmetic because it makes for a
3014 simple example. Some people dislike examples using arithmetic; however,
3015 if you are such a person, do not despair. Hardly any of the code we
3016 will study in the remainder of this introduction involves arithmetic or
3017 mathematics. The examples mostly involve text in one way or another.
3019 A function definition has up to five parts following the word
3024 The name of the symbol to which the function definition should be
3028 A list of the arguments that will be passed to the function. If no
3029 arguments will be passed to the function, this is an empty list,
3033 Documentation describing the function. (Technically optional, but
3034 strongly recommended.)
3037 Optionally, an expression to make the function interactive so you can
3038 use it by typing @kbd{M-x} and then the name of the function; or by
3039 typing an appropriate key or keychord.
3041 @cindex @samp{body} defined
3043 The code that instructs the computer what to do: the @dfn{body} of the
3044 function definition.
3047 It is helpful to think of the five parts of a function definition as
3048 being organized in a template, with slots for each part:
3052 (defun @var{function-name} (@var{arguments}@dots{})
3053 "@var{optional-documentation}@dots{}"
3054 (interactive @var{argument-passing-info}) ; @r{optional}
3059 As an example, here is the code for a function that multiplies its
3060 argument by 7. (This example is not interactive. @xref{Interactive,
3061 , Making a Function Interactive}, for that information.)
3065 (defun multiply-by-seven (number)
3066 "Multiply NUMBER by seven."
3071 This definition begins with a parenthesis and the symbol @code{defun},
3072 followed by the name of the function.
3074 @cindex @samp{argument list} defined
3075 The name of the function is followed by a list that contains the
3076 arguments that will be passed to the function. This list is called
3077 the @dfn{argument list}. In this example, the list has only one
3078 element, the symbol, @code{number}. When the function is used, the
3079 symbol will be bound to the value that is used as the argument to the
3082 Instead of choosing the word @code{number} for the name of the argument,
3083 I could have picked any other name. For example, I could have chosen
3084 the word @code{multiplicand}. I picked the word ``number'' because it
3085 tells what kind of value is intended for this slot; but I could just as
3086 well have chosen the word ``multiplicand'' to indicate the role that the
3087 value placed in this slot will play in the workings of the function. I
3088 could have called it @code{foogle}, but that would have been a bad
3089 choice because it would not tell humans what it means. The choice of
3090 name is up to the programmer and should be chosen to make the meaning of
3093 Indeed, you can choose any name you wish for a symbol in an argument
3094 list, even the name of a symbol used in some other function: the name
3095 you use in an argument list is private to that particular definition.
3096 In that definition, the name refers to a different entity than any use
3097 of the same name outside the function definition. Suppose you have a
3098 nick-name ``Shorty'' in your family; when your family members refer to
3099 ``Shorty'', they mean you. But outside your family, in a movie, for
3100 example, the name ``Shorty'' refers to someone else. Because a name in an
3101 argument list is private to the function definition, you can change the
3102 value of such a symbol inside the body of a function without changing
3103 its value outside the function. The effect is similar to that produced
3104 by a @code{let} expression. (@xref{let, , @code{let}}.)
3107 Note also that we discuss the word ``number'' in two different ways: as a
3108 symbol that appears in the code, and as the name of something that will
3109 be replaced by a something else during the evaluation of the function.
3110 In the first case, @code{number} is a symbol, not a number; it happens
3111 that within the function, it is a variable who value is the number in
3112 question, but our primary interest in it is as a symbol. On the other
3113 hand, when we are talking about the function, our interest is that we
3114 will substitute a number for the word @var{number}. To keep this
3115 distinction clear, we use different typography for the two
3116 circumstances. When we talk about this function, or about how it works,
3117 we refer to this number by writing @var{number}. In the function
3118 itself, we refer to it by writing @code{number}.
3121 The argument list is followed by the documentation string that
3122 describes the function. This is what you see when you type
3123 @w{@kbd{C-h f}} and the name of a function. Incidentally, when you
3124 write a documentation string like this, you should make the first line
3125 a complete sentence since some commands, such as @code{apropos}, print
3126 only the first line of a multi-line documentation string. Also, you
3127 should not indent the second line of a documentation string, if you
3128 have one, because that looks odd when you use @kbd{C-h f}
3129 (@code{describe-function}). The documentation string is optional, but
3130 it is so useful, it should be included in almost every function you
3133 @findex * @r{(multiplication)}
3134 The third line of the example consists of the body of the function
3135 definition. (Most functions' definitions, of course, are longer than
3136 this.) In this function, the body is the list, @code{(* 7 number)}, which
3137 says to multiply the value of @var{number} by 7. (In Emacs Lisp,
3138 @code{*} is the function for multiplication, just as @code{+} is the
3139 function for addition.)
3141 When you use the @code{multiply-by-seven} function, the argument
3142 @code{number} evaluates to the actual number you want used. Here is an
3143 example that shows how @code{multiply-by-seven} is used; but don't try
3144 to evaluate this yet!
3147 (multiply-by-seven 3)
3151 The symbol @code{number}, specified in the function definition in the
3152 next section, is bound to the value 3 in the actual use of
3153 the function. Note that although @code{number} was inside parentheses
3154 in the function definition, the argument passed to the
3155 @code{multiply-by-seven} function is not in parentheses. The
3156 parentheses are written in the function definition so the computer can
3157 figure out where the argument list ends and the rest of the function
3160 If you evaluate this example, you are likely to get an error message.
3161 (Go ahead, try it!) This is because we have written the function
3162 definition, but not yet told the computer about the definition---we have
3163 not yet loaded the function definition in Emacs.
3164 Installing a function is the process that tells the Lisp interpreter the
3165 definition of the function. Installation is described in the next
3169 @section Install a Function Definition
3170 @cindex Install a Function Definition
3171 @cindex Definition installation
3172 @cindex Function definition installation
3174 If you are reading this inside of Info in Emacs, you can try out the
3175 @code{multiply-by-seven} function by first evaluating the function
3176 definition and then evaluating @code{(multiply-by-seven 3)}. A copy of
3177 the function definition follows. Place the cursor after the last
3178 parenthesis of the function definition and type @kbd{C-x C-e}. When you
3179 do this, @code{multiply-by-seven} will appear in the echo area. (What
3180 this means is that when a function definition is evaluated, the value it
3181 returns is the name of the defined function.) At the same time, this
3182 action installs the function definition.
3186 (defun multiply-by-seven (number)
3187 "Multiply NUMBER by seven."
3193 By evaluating this @code{defun}, you have just installed
3194 @code{multiply-by-seven} in Emacs. The function is now just as much a
3195 part of Emacs as @code{forward-word} or any other editing function you
3196 use. (@code{multiply-by-seven} will stay installed until you quit
3197 Emacs. To reload code automatically whenever you start Emacs, see
3198 @ref{Permanent Installation, , Installing Code Permanently}.)
3201 * Effect of installation::
3202 * Change a defun:: How to change a function definition.
3206 @node Effect of installation
3207 @unnumberedsubsec The effect of installation
3210 You can see the effect of installing @code{multiply-by-seven} by
3211 evaluating the following sample. Place the cursor after the following
3212 expression and type @kbd{C-x C-e}. The number 21 will appear in the
3216 (multiply-by-seven 3)
3219 If you wish, you can read the documentation for the function by typing
3220 @kbd{C-h f} (@code{describe-function}) and then the name of the
3221 function, @code{multiply-by-seven}. When you do this, a
3222 @file{*Help*} window will appear on your screen that says:
3226 multiply-by-seven is a Lisp function.
3228 (multiply-by-seven NUMBER)
3230 Multiply NUMBER by seven.
3235 (To return to a single window on your screen, type @kbd{C-x 1}.)
3237 @node Change a defun
3238 @subsection Change a Function Definition
3239 @cindex Changing a function definition
3240 @cindex Function definition, how to change
3241 @cindex Definition, how to change
3243 If you want to change the code in @code{multiply-by-seven}, just rewrite
3244 it. To install the new version in place of the old one, evaluate the
3245 function definition again. This is how you modify code in Emacs. It is
3248 As an example, you can change the @code{multiply-by-seven} function to
3249 add the number to itself seven times instead of multiplying the number
3250 by seven. It produces the same answer, but by a different path. At
3251 the same time, we will add a comment to the code; a comment is text
3252 that the Lisp interpreter ignores, but that a human reader may find
3253 useful or enlightening. The comment is that this is the second
3258 (defun multiply-by-seven (number) ; @r{Second version.}
3259 "Multiply NUMBER by seven."
3260 (+ number number number number number number number))
3264 @cindex Comments in Lisp code
3265 The comment follows a semicolon, @samp{;}. In Lisp, everything on a
3266 line that follows a semicolon is a comment. The end of the line is the
3267 end of the comment. To stretch a comment over two or more lines, begin
3268 each line with a semicolon.
3270 @xref{Beginning init File, , Beginning a @file{.emacs}
3271 File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp
3272 Reference Manual}, for more about comments.
3274 You can install this version of the @code{multiply-by-seven} function by
3275 evaluating it in the same way you evaluated the first function: place
3276 the cursor after the last parenthesis and type @kbd{C-x C-e}.
3278 In summary, this is how you write code in Emacs Lisp: you write a
3279 function; install it; test it; and then make fixes or enhancements and
3283 @section Make a Function Interactive
3284 @cindex Interactive functions
3287 You make a function interactive by placing a list that begins with
3288 the special form @code{interactive} immediately after the
3289 documentation. A user can invoke an interactive function by typing
3290 @kbd{M-x} and then the name of the function; or by typing the keys to
3291 which it is bound, for example, by typing @kbd{C-n} for
3292 @code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}.
3294 Interestingly, when you call an interactive function interactively,
3295 the value returned is not automatically displayed in the echo area.
3296 This is because you often call an interactive function for its side
3297 effects, such as moving forward by a word or line, and not for the
3298 value returned. If the returned value were displayed in the echo area
3299 each time you typed a key, it would be very distracting.
3302 * Interactive multiply-by-seven:: An overview.
3303 * multiply-by-seven in detail:: The interactive version.
3307 @node Interactive multiply-by-seven
3308 @unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview
3311 Both the use of the special form @code{interactive} and one way to
3312 display a value in the echo area can be illustrated by creating an
3313 interactive version of @code{multiply-by-seven}.
3320 (defun multiply-by-seven (number) ; @r{Interactive version.}
3321 "Multiply NUMBER by seven."
3323 (message "The result is %d" (* 7 number)))
3328 You can install this code by placing your cursor after it and typing
3329 @kbd{C-x C-e}. The name of the function will appear in your echo area.
3330 Then, you can use this code by typing @kbd{C-u} and a number and then
3331 typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase
3332 @samp{The result is @dots{}} followed by the product will appear in the
3335 Speaking more generally, you invoke a function like this in either of two
3340 By typing a prefix argument that contains the number to be passed, and
3341 then typing @kbd{M-x} and the name of the function, as with
3342 @kbd{C-u 3 M-x forward-sentence}; or,
3345 By typing whatever key or keychord the function is bound to, as with
3350 Both the examples just mentioned work identically to move point forward
3351 three sentences. (Since @code{multiply-by-seven} is not bound to a key,
3352 it could not be used as an example of key binding.)
3354 (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command
3357 A @dfn{prefix argument} is passed to an interactive function by typing the
3358 @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by
3359 typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you
3360 type @kbd{C-u} without a number, it defaults to 4).
3362 @node multiply-by-seven in detail
3363 @subsection An Interactive @code{multiply-by-seven}
3365 Let's look at the use of the special form @code{interactive} and then at
3366 the function @code{message} in the interactive version of
3367 @code{multiply-by-seven}. You will recall that the function definition
3372 (defun multiply-by-seven (number) ; @r{Interactive version.}
3373 "Multiply NUMBER by seven."
3375 (message "The result is %d" (* 7 number)))
3379 In this function, the expression, @code{(interactive "p")}, is a list of
3380 two elements. The @code{"p"} tells Emacs to pass the prefix argument to
3381 the function and use its value for the argument of the function.
3384 The argument will be a number. This means that the symbol
3385 @code{number} will be bound to a number in the line:
3388 (message "The result is %d" (* 7 number))
3393 For example, if your prefix argument is 5, the Lisp interpreter will
3394 evaluate the line as if it were:
3397 (message "The result is %d" (* 7 5))
3401 (If you are reading this in GNU Emacs, you can evaluate this expression
3402 yourself.) First, the interpreter will evaluate the inner list, which
3403 is @code{(* 7 5)}. This returns a value of 35. Next, it
3404 will evaluate the outer list, passing the values of the second and
3405 subsequent elements of the list to the function @code{message}.
3407 As we have seen, @code{message} is an Emacs Lisp function especially
3408 designed for sending a one line message to a user. (@xref{message, ,
3409 The @code{message} function}.) In summary, the @code{message}
3410 function prints its first argument in the echo area as is, except for
3411 occurrences of @samp{%d} or @samp{%s} (and various other %-sequences
3412 which we have not mentioned). When it sees a control sequence, the
3413 function looks to the second or subsequent arguments and prints the
3414 value of the argument in the location in the string where the control
3415 sequence is located.
3417 In the interactive @code{multiply-by-seven} function, the control string
3418 is @samp{%d}, which requires a number, and the value returned by
3419 evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35
3420 is printed in place of the @samp{%d} and the message is @samp{The result
3423 (Note that when you call the function @code{multiply-by-seven}, the
3424 message is printed without quotes, but when you call @code{message}, the
3425 text is printed in double quotes. This is because the value returned by
3426 @code{message} is what appears in the echo area when you evaluate an
3427 expression whose first element is @code{message}; but when embedded in a
3428 function, @code{message} prints the text as a side effect without
3431 @node Interactive Options
3432 @section Different Options for @code{interactive}
3433 @cindex Options for @code{interactive}
3434 @cindex Interactive options
3436 In the example, @code{multiply-by-seven} used @code{"p"} as the
3437 argument to @code{interactive}. This argument told Emacs to interpret
3438 your typing either @kbd{C-u} followed by a number or @key{META}
3439 followed by a number as a command to pass that number to the function
3440 as its argument. Emacs has more than twenty characters predefined for
3441 use with @code{interactive}. In almost every case, one of these
3442 options will enable you to pass the right information interactively to
3443 a function. (@xref{Interactive Codes, , Code Characters for
3444 @code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.)
3447 Consider the function @code{zap-to-char}. Its interactive expression
3450 @c FIXME: the interactive expression of zap-to-char has been changed
3454 (interactive "p\ncZap to char: ")
3457 The first part of the argument to @code{interactive} is @samp{p}, with
3458 which you are already familiar. This argument tells Emacs to
3459 interpret a prefix, as a number to be passed to the function. You
3460 can specify a prefix either by typing @kbd{C-u} followed by a number
3461 or by typing @key{META} followed by a number. The prefix is the
3462 number of specified characters. Thus, if your prefix is three and the
3463 specified character is @samp{x}, then you will delete all the text up
3464 to and including the third next @samp{x}. If you do not set a prefix,
3465 then you delete all the text up to and including the specified
3466 character, but no more.
3468 The @samp{c} tells the function the name of the character to which to delete.
3470 More formally, a function with two or more arguments can have
3471 information passed to each argument by adding parts to the string that
3472 follows @code{interactive}. When you do this, the information is
3473 passed to each argument in the same order it is specified in the
3474 @code{interactive} list. In the string, each part is separated from
3475 the next part by a @samp{\n}, which is a newline. For example, you
3476 can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }.
3477 This causes Emacs to pass the value of the prefix argument (if there
3478 is one) and the character.
3480 In this case, the function definition looks like the following, where
3481 @code{arg} and @code{char} are the symbols to which @code{interactive}
3482 binds the prefix argument and the specified character:
3486 (defun @var{name-of-function} (arg char)
3487 "@var{documentation}@dots{}"
3488 (interactive "p\ncZap to char: ")
3489 @var{body-of-function}@dots{})
3494 (The space after the colon in the prompt makes it look better when you
3495 are prompted. @xref{copy-to-buffer, , The Definition of
3496 @code{copy-to-buffer}}, for an example.)
3498 When a function does not take arguments, @code{interactive} does not
3499 require any. Such a function contains the simple expression
3500 @code{(interactive)}. The @code{mark-whole-buffer} function is like
3503 Alternatively, if the special letter-codes are not right for your
3504 application, you can pass your own arguments to @code{interactive} as
3507 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}},
3508 for an example. @xref{Using Interactive, , Using @code{Interactive},
3509 elisp, The GNU Emacs Lisp Reference Manual}, for a more complete
3510 explanation about this technique.
3512 @node Permanent Installation
3513 @section Install Code Permanently
3514 @cindex Install code permanently
3515 @cindex Permanent code installation
3516 @cindex Code installation
3518 When you install a function definition by evaluating it, it will stay
3519 installed until you quit Emacs. The next time you start a new session
3520 of Emacs, the function will not be installed unless you evaluate the
3521 function definition again.
3523 At some point, you may want to have code installed automatically
3524 whenever you start a new session of Emacs. There are several ways of
3529 If you have code that is just for yourself, you can put the code for the
3530 function definition in your @file{.emacs} initialization file. When you
3531 start Emacs, your @file{.emacs} file is automatically evaluated and all
3532 the function definitions within it are installed.
3533 @xref{Emacs Initialization, , Your @file{.emacs} File}.
3536 Alternatively, you can put the function definitions that you want
3537 installed in one or more files of their own and use the @code{load}
3538 function to cause Emacs to evaluate and thereby install each of the
3539 functions in the files.
3540 @xref{Loading Files, , Loading Files}.
3543 Thirdly, if you have code that your whole site will use, it is usual
3544 to put it in a file called @file{site-init.el} that is loaded when
3545 Emacs is built. This makes the code available to everyone who uses
3546 your machine. (See the @file{INSTALL} file that is part of the Emacs
3550 Finally, if you have code that everyone who uses Emacs may want, you
3551 can post it on a computer network or send a copy to the Free Software
3552 Foundation. (When you do this, please license the code and its
3553 documentation under a license that permits other people to run, copy,
3554 study, modify, and redistribute the code and which protects you from
3555 having your work taken from you.) If you send a copy of your code to
3556 the Free Software Foundation, and properly protect yourself and
3557 others, it may be included in the next release of Emacs. In large
3558 part, this is how Emacs has grown over the past years, by donations.
3564 The @code{let} expression is a special form in Lisp that you will need
3565 to use in most function definitions.
3567 @code{let} is used to attach or bind a symbol to a value in such a way
3568 that the Lisp interpreter will not confuse the variable with a
3569 variable of the same name that is not part of the function.
3571 To understand why the @code{let} special form is necessary, consider
3572 the situation in which you own a home that you generally refer to as
3573 ``the house'', as in the sentence, ``The house needs painting.'' If you
3574 are visiting a friend and your host refers to ``the house'', he is
3575 likely to be referring to @emph{his} house, not yours, that is, to a
3578 If your friend is referring to his house and you think he is referring
3579 to your house, you may be in for some confusion. The same thing could
3580 happen in Lisp if a variable that is used inside of one function has
3581 the same name as a variable that is used inside of another function,
3582 and the two are not intended to refer to the same value. The
3583 @code{let} special form prevents this kind of confusion.
3586 * Prevent confusion::
3587 * Parts of let Expression::
3588 * Sample let Expression::
3589 * Uninitialized let Variables::
3593 @node Prevent confusion
3594 @unnumberedsubsec @code{let} Prevents Confusion
3597 @cindex @samp{local variable} defined
3598 @cindex @samp{variable, local}, defined
3599 The @code{let} special form prevents confusion. @code{let} creates a
3600 name for a @dfn{local variable} that overshadows any use of the same
3601 name outside the @code{let} expression. This is like understanding
3602 that whenever your host refers to ``the house'', he means his house, not
3603 yours. (Symbols used in argument lists work the same way.
3604 @xref{defun, , The @code{defun} Macro}.)
3606 Local variables created by a @code{let} expression retain their value
3607 @emph{only} within the @code{let} expression itself (and within
3608 expressions called within the @code{let} expression); the local
3609 variables have no effect outside the @code{let} expression.
3611 Another way to think about @code{let} is that it is like a @code{setq}
3612 that is temporary and local. The values set by @code{let} are
3613 automatically undone when the @code{let} is finished. The setting
3614 only affects expressions that are inside the bounds of the @code{let}
3615 expression. In computer science jargon, we would say the binding of
3616 a symbol is visible only in functions called in the @code{let} form;
3617 in Emacs Lisp, scoping is dynamic, not lexical.
3619 @code{let} can create more than one variable at once. Also,
3620 @code{let} gives each variable it creates an initial value, either a
3621 value specified by you, or @code{nil}. (In the jargon, this is
3622 binding the variable to the value.) After @code{let} has created
3623 and bound the variables, it executes the code in the body of the
3624 @code{let}, and returns the value of the last expression in the body,
3625 as the value of the whole @code{let} expression. (``Execute'' is a jargon
3626 term that means to evaluate a list; it comes from the use of the word
3627 meaning ``to give practical effect to'' (@cite{Oxford English
3628 Dictionary}). Since you evaluate an expression to perform an action,
3629 ``execute'' has evolved as a synonym to ``evaluate''.)
3631 @node Parts of let Expression
3632 @subsection The Parts of a @code{let} Expression
3633 @cindex @code{let} expression, parts of
3634 @cindex Parts of @code{let} expression
3636 @cindex @samp{varlist} defined
3637 A @code{let} expression is a list of three parts. The first part is
3638 the symbol @code{let}. The second part is a list, called a
3639 @dfn{varlist}, each element of which is either a symbol by itself or a
3640 two-element list, the first element of which is a symbol. The third
3641 part of the @code{let} expression is the body of the @code{let}. The
3642 body usually consists of one or more lists.
3645 A template for a @code{let} expression looks like this:
3648 (let @var{varlist} @var{body}@dots{})
3652 The symbols in the varlist are the variables that are given initial
3653 values by the @code{let} special form. Symbols by themselves are given
3654 the initial value of @code{nil}; and each symbol that is the first
3655 element of a two-element list is bound to the value that is returned
3656 when the Lisp interpreter evaluates the second element.
3658 Thus, a varlist might look like this: @code{(thread (needles 3))}. In
3659 this case, in a @code{let} expression, Emacs binds the symbol
3660 @code{thread} to an initial value of @code{nil}, and binds the symbol
3661 @code{needles} to an initial value of 3.
3663 When you write a @code{let} expression, what you do is put the
3664 appropriate expressions in the slots of the @code{let} expression
3667 If the varlist is composed of two-element lists, as is often the case,
3668 the template for the @code{let} expression looks like this:
3672 (let ((@var{variable} @var{value})
3673 (@var{variable} @var{value})
3679 @node Sample let Expression
3680 @subsection Sample @code{let} Expression
3681 @cindex Sample @code{let} expression
3682 @cindex @code{let} expression sample
3684 The following expression creates and gives initial values
3685 to the two variables @code{zebra} and @code{tiger}. The body of the
3686 @code{let} expression is a list which calls the @code{message} function.
3690 (let ((zebra "stripes")
3692 (message "One kind of animal has %s and another is %s."
3697 Here, the varlist is @code{((zebra "stripes") (tiger "fierce"))}.
3699 The two variables are @code{zebra} and @code{tiger}. Each variable is
3700 the first element of a two-element list and each value is the second
3701 element of its two-element list. In the varlist, Emacs binds the
3702 variable @code{zebra} to the value @code{"stripes"}@footnote{According
3703 to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras
3704 become impossibly dangerous as they grow older'' but the claim here is
3705 that they do not become fierce like a tiger. (1997, W. W. Norton and
3706 Co., ISBN 0-393-03894-2, page 171)}, and binds the
3707 variable @code{tiger} to the value @code{"fierce"}. In this example,
3708 both values are strings. The values could just as well have been
3709 another list or a symbol. The body of the @code{let}
3710 follows after the list holding the variables. In this example, the
3711 body is a list that uses the @code{message} function to print a string
3715 You may evaluate the example in the usual fashion, by placing the
3716 cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do
3717 this, the following will appear in the echo area:
3720 "One kind of animal has stripes and another is fierce."
3723 As we have seen before, the @code{message} function prints its first
3724 argument, except for @samp{%s}. In this example, the value of the variable
3725 @code{zebra} is printed at the location of the first @samp{%s} and the
3726 value of the variable @code{tiger} is printed at the location of the
3729 @node Uninitialized let Variables
3730 @subsection Uninitialized Variables in a @code{let} Statement
3731 @cindex Uninitialized @code{let} variables
3732 @cindex @code{let} variables uninitialized
3734 If you do not bind the variables in a @code{let} statement to specific
3735 initial values, they will automatically be bound to an initial value of
3736 @code{nil}, as in the following expression:
3745 "Here are %d variables with %s, %s, and %s value."
3746 birch pine fir oak))
3751 Here, the varlist is @code{((birch 3) pine fir (oak 'some))}.
3754 If you evaluate this expression in the usual way, the following will
3755 appear in your echo area:
3758 "Here are 3 variables with nil, nil, and some value."
3762 In this example, Emacs binds the symbol @code{birch} to the number 3,
3763 binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds
3764 the symbol @code{oak} to the value @code{some}.
3766 Note that in the first part of the @code{let}, the variables @code{pine}
3767 and @code{fir} stand alone as atoms that are not surrounded by
3768 parentheses; this is because they are being bound to @code{nil}, the
3769 empty list. But @code{oak} is bound to @code{some} and so is a part of
3770 the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the
3771 number 3 and so is in a list with that number. (Since a number
3772 evaluates to itself, the number does not need to be quoted. Also, the
3773 number is printed in the message using a @samp{%d} rather than a
3774 @samp{%s}.) The four variables as a group are put into a list to
3775 delimit them from the body of the @code{let}.
3778 @section The @code{if} Special Form
3780 @cindex Conditional with @code{if}
3782 A third special form, in addition to @code{defun} and @code{let}, is the
3783 conditional @code{if}. This form is used to instruct the computer to
3784 make decisions. You can write function definitions without using
3785 @code{if}, but it is used often enough, and is important enough, to be
3786 included here. It is used, for example, in the code for the
3787 function @code{beginning-of-buffer}.
3789 The basic idea behind an @code{if}, is that @emph{if} a test is true,
3790 @emph{then} an expression is evaluated. If the test is not true, the
3791 expression is not evaluated. For example, you might make a decision
3792 such as, ``if it is warm and sunny, then go to the beach!''
3795 * if in more detail::
3796 * type-of-animal in detail:: An example of an @code{if} expression.
3800 @node if in more detail
3801 @unnumberedsubsec @code{if} in more detail
3804 @cindex @samp{if-part} defined
3805 @cindex @samp{then-part} defined
3806 An @code{if} expression written in Lisp does not use the word ``then'';
3807 the test and the action are the second and third elements of the list
3808 whose first element is @code{if}. Nonetheless, the test part of an
3809 @code{if} expression is often called the @dfn{if-part} and the second
3810 argument is often called the @dfn{then-part}.
3812 Also, when an @code{if} expression is written, the true-or-false-test
3813 is usually written on the same line as the symbol @code{if}, but the
3814 action to carry out if the test is true, the then-part, is written
3815 on the second and subsequent lines. This makes the @code{if}
3816 expression easier to read.
3820 (if @var{true-or-false-test}
3821 @var{action-to-carry-out-if-test-is-true})
3826 The true-or-false-test will be an expression that
3827 is evaluated by the Lisp interpreter.
3829 Here is an example that you can evaluate in the usual manner. The test
3830 is whether the number 5 is greater than the number 4. Since it is, the
3831 message @samp{5 is greater than 4!} will be printed.
3835 (if (> 5 4) ; @r{if-part}
3836 (message "5 is greater than 4!")) ; @r{then-part}
3841 (The function @code{>} tests whether its first argument is greater than
3842 its second argument and returns true if it is.)
3843 @findex > (greater than)
3845 Of course, in actual use, the test in an @code{if} expression will not
3846 be fixed for all time as it is by the expression @code{(> 5 4)}.
3847 Instead, at least one of the variables used in the test will be bound to
3848 a value that is not known ahead of time. (If the value were known ahead
3849 of time, we would not need to run the test!)
3851 For example, the value may be bound to an argument of a function
3852 definition. In the following function definition, the character of the
3853 animal is a value that is passed to the function. If the value bound to
3854 @code{characteristic} is @code{"fierce"}, then the message, @samp{It is a
3855 tiger!} will be printed; otherwise, @code{nil} will be returned.
3859 (defun type-of-animal (characteristic)
3860 "Print message in echo area depending on CHARACTERISTIC.
3861 If the CHARACTERISTIC is the string \"fierce\",
3862 then warn of a tiger."
3863 (if (equal characteristic "fierce")
3864 (message "It is a tiger!")))
3870 If you are reading this inside of GNU Emacs, you can evaluate the
3871 function definition in the usual way to install it in Emacs, and then you
3872 can evaluate the following two expressions to see the results:
3876 (type-of-animal "fierce")
3878 (type-of-animal "striped")
3883 @c Following sentences rewritten to prevent overfull hbox.
3885 When you evaluate @code{(type-of-animal "fierce")}, you will see the
3886 following message printed in the echo area: @code{"It is a tiger!"}; and
3887 when you evaluate @code{(type-of-animal "striped")} you will see @code{nil}
3888 printed in the echo area.
3890 @node type-of-animal in detail
3891 @subsection The @code{type-of-animal} Function in Detail
3893 Let's look at the @code{type-of-animal} function in detail.
3895 The function definition for @code{type-of-animal} was written by filling
3896 the slots of two templates, one for a function definition as a whole, and
3897 a second for an @code{if} expression.
3900 The template for every function that is not interactive is:
3904 (defun @var{name-of-function} (@var{argument-list})
3905 "@var{documentation}@dots{}"
3911 The parts of the function that match this template look like this:
3915 (defun type-of-animal (characteristic)
3916 "Print message in echo area depending on CHARACTERISTIC.
3917 If the CHARACTERISTIC is the string \"fierce\",
3918 then warn of a tiger."
3919 @var{body: the} @code{if} @var{expression})
3923 The name of function is @code{type-of-animal}; it is passed the value
3924 of one argument. The argument list is followed by a multi-line
3925 documentation string. The documentation string is included in the
3926 example because it is a good habit to write documentation string for
3927 every function definition. The body of the function definition
3928 consists of the @code{if} expression.
3931 The template for an @code{if} expression looks like this:
3935 (if @var{true-or-false-test}
3936 @var{action-to-carry-out-if-the-test-returns-true})
3941 In the @code{type-of-animal} function, the code for the @code{if}
3946 (if (equal characteristic "fierce")
3947 (message "It is a tiger!")))
3952 Here, the true-or-false-test is the expression:
3955 (equal characteristic "fierce")
3959 In Lisp, @code{equal} is a function that determines whether its first
3960 argument is equal to its second argument. The second argument is the
3961 string @code{"fierce"} and the first argument is the value of the
3962 symbol @code{characteristic}---in other words, the argument passed to
3965 In the first exercise of @code{type-of-animal}, the argument
3966 @code{"fierce"} is passed to @code{type-of-animal}. Since @code{"fierce"}
3967 is equal to @code{"fierce"}, the expression, @code{(equal characteristic
3968 "fierce")}, returns a value of true. When this happens, the @code{if}
3969 evaluates the second argument or then-part of the @code{if}:
3970 @code{(message "It is a tiger!")}.
3972 On the other hand, in the second exercise of @code{type-of-animal}, the
3973 argument @code{"striped"} is passed to @code{type-of-animal}. @code{"striped"}
3974 is not equal to @code{"fierce"}, so the then-part is not evaluated and
3975 @code{nil} is returned by the @code{if} expression.
3978 @section If--then--else Expressions
3981 An @code{if} expression may have an optional third argument, called
3982 the @dfn{else-part}, for the case when the true-or-false-test returns
3983 false. When this happens, the second argument or then-part of the
3984 overall @code{if} expression is @emph{not} evaluated, but the third or
3985 else-part @emph{is} evaluated. You might think of this as the cloudy
3986 day alternative for the decision ``if it is warm and sunny, then go to
3987 the beach, else read a book!''.
3989 The word ``else'' is not written in the Lisp code; the else-part of an
3990 @code{if} expression comes after the then-part. In the written Lisp, the
3991 else-part is usually written to start on a line of its own and is
3992 indented less than the then-part:
3996 (if @var{true-or-false-test}
3997 @var{action-to-carry-out-if-the-test-returns-true}
3998 @var{action-to-carry-out-if-the-test-returns-false})
4002 For example, the following @code{if} expression prints the message @samp{4
4003 is not greater than 5!} when you evaluate it in the usual way:
4007 (if (> 4 5) ; @r{if-part}
4008 (message "4 falsely greater than 5!") ; @r{then-part}
4009 (message "4 is not greater than 5!")) ; @r{else-part}
4014 Note that the different levels of indentation make it easy to
4015 distinguish the then-part from the else-part. (GNU Emacs has several
4016 commands that automatically indent @code{if} expressions correctly.
4017 @xref{Typing Lists, , GNU Emacs Helps You Type Lists}.)
4019 We can extend the @code{type-of-animal} function to include an
4020 else-part by simply incorporating an additional part to the @code{if}
4024 You can see the consequences of doing this if you evaluate the following
4025 version of the @code{type-of-animal} function definition to install it
4026 and then evaluate the two subsequent expressions to pass different
4027 arguments to the function.
4031 (defun type-of-animal (characteristic) ; @r{Second version.}
4032 "Print message in echo area depending on CHARACTERISTIC.
4033 If the CHARACTERISTIC is the string \"fierce\",
4034 then warn of a tiger; else say it is not fierce."
4035 (if (equal characteristic "fierce")
4036 (message "It is a tiger!")
4037 (message "It is not fierce!")))
4044 (type-of-animal "fierce")
4046 (type-of-animal "striped")
4051 @c Following sentence rewritten to prevent overfull hbox.
4053 When you evaluate @code{(type-of-animal "fierce")}, you will see the
4054 following message printed in the echo area: @code{"It is a tiger!"}; but
4055 when you evaluate @code{(type-of-animal "striped")}, you will see
4056 @code{"It is not fierce!"}.
4058 (Of course, if the @var{characteristic} were @code{"ferocious"}, the
4059 message @code{"It is not fierce!"} would be printed; and it would be
4060 misleading! When you write code, you need to take into account the
4061 possibility that some such argument will be tested by the @code{if}
4062 and write your program accordingly.)
4064 @node Truth & Falsehood
4065 @section Truth and Falsehood in Emacs Lisp
4066 @cindex Truth and falsehood in Emacs Lisp
4067 @cindex Falsehood and truth in Emacs Lisp
4070 There is an important aspect to the truth test in an @code{if}
4071 expression. So far, we have spoken of ``true'' and ``false'' as values of
4072 predicates as if they were new kinds of Emacs Lisp objects. In fact,
4073 ``false'' is just our old friend @code{nil}. Anything else---anything
4074 at all---is ``true''.
4076 The expression that tests for truth is interpreted as @dfn{true}
4077 if the result of evaluating it is a value that is not @code{nil}. In
4078 other words, the result of the test is considered true if the value
4079 returned is a number such as 47, a string such as @code{"hello"}, or a
4080 symbol (other than @code{nil}) such as @code{flowers}, or a list (so
4081 long as it is not empty), or even a buffer!
4084 * nil explained:: @code{nil} has two meanings.
4089 @unnumberedsubsec An explanation of @code{nil}
4092 Before illustrating a test for truth, we need an explanation of @code{nil}.
4094 In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the
4095 empty list. Second, it means false and is the value returned when a
4096 true-or-false-test tests false. @code{nil} can be written as an empty
4097 list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is
4098 concerned, @code{()} and @code{nil} are the same. Humans, however, tend
4099 to use @code{nil} for false and @code{()} for the empty list.
4101 In Emacs Lisp, any value that is not @code{nil}---is not the empty
4102 list---is considered true. This means that if an evaluation returns
4103 something that is not an empty list, an @code{if} expression will test
4104 true. For example, if a number is put in the slot for the test, it
4105 will be evaluated and will return itself, since that is what numbers
4106 do when evaluated. In this conditional, the @code{if} expression will
4107 test true. The expression tests false only when @code{nil}, an empty
4108 list, is returned by evaluating the expression.
4110 You can see this by evaluating the two expressions in the following examples.
4112 In the first example, the number 4 is evaluated as the test in the
4113 @code{if} expression and returns itself; consequently, the then-part
4114 of the expression is evaluated and returned: @samp{true} appears in
4115 the echo area. In the second example, the @code{nil} indicates false;
4116 consequently, the else-part of the expression is evaluated and
4117 returned: @samp{false} appears in the echo area.
4134 Incidentally, if some other useful value is not available for a test that
4135 returns true, then the Lisp interpreter will return the symbol @code{t}
4136 for true. For example, the expression @code{(> 5 4)} returns @code{t}
4137 when evaluated, as you can see by evaluating it in the usual way:
4145 On the other hand, this function returns @code{nil} if the test is false.
4151 @node save-excursion
4152 @section @code{save-excursion}
4153 @findex save-excursion
4154 @cindex Region, what it is
4155 @cindex Preserving point and buffer
4156 @cindex Point and buffer preservation
4160 The @code{save-excursion} function is the third and final special form
4161 that we will discuss in this chapter.
4163 In Emacs Lisp programs used for editing, the @code{save-excursion}
4164 function is very common. It saves the location of point,
4165 executes the body of the function, and then restores point to
4166 its previous position if its location was changed. Its primary
4167 purpose is to keep the user from being surprised and disturbed by
4168 unexpected movement of point.
4171 * Point and mark:: A review of various locations.
4172 * Template for save-excursion::
4176 @node Point and mark
4177 @unnumberedsubsec Point and Mark
4180 Before discussing @code{save-excursion}, however, it may be useful
4181 first to review what point and mark are in GNU Emacs. @dfn{Point} is
4182 the current location of the cursor. Wherever the cursor
4183 is, that is point. More precisely, on terminals where the cursor
4184 appears to be on top of a character, point is immediately before the
4185 character. In Emacs Lisp, point is an integer. The first character in
4186 a buffer is number one, the second is number two, and so on. The
4187 function @code{point} returns the current position of the cursor as a
4188 number. Each buffer has its own value for point.
4190 The @dfn{mark} is another position in the buffer; its value can be set
4191 with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If
4192 a mark has been set, you can use the command @kbd{C-x C-x}
4193 (@code{exchange-point-and-mark}) to cause the cursor to jump to the mark
4194 and set the mark to be the previous position of point. In addition, if
4195 you set another mark, the position of the previous mark is saved in the
4196 mark ring. Many mark positions can be saved this way. You can jump the
4197 cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more
4200 The part of the buffer between point and mark is called @dfn{the
4201 region}. Numerous commands work on the region, including
4202 @code{center-region}, @code{count-lines-region}, @code{kill-region}, and
4203 @code{print-region}.
4205 The @code{save-excursion} special form saves the location of point and
4206 restores this position after the code within the body of the
4207 special form is evaluated by the Lisp interpreter. Thus, if point were
4208 in the beginning of a piece of text and some code moved point to the end
4209 of the buffer, the @code{save-excursion} would put point back to where
4210 it was before, after the expressions in the body of the function were
4213 In Emacs, a function frequently moves point as part of its internal
4214 workings even though a user would not expect this. For example,
4215 @code{count-lines-region} moves point. To prevent the user from being
4216 bothered by jumps that are both unexpected and (from the user's point of
4217 view) unnecessary, @code{save-excursion} is often used to keep point in
4218 the location expected by the user. The use of
4219 @code{save-excursion} is good housekeeping.
4221 To make sure the house stays clean, @code{save-excursion} restores the
4222 value of point even if something goes wrong in the code inside
4223 of it (or, to be more precise and to use the proper jargon, ``in case of
4224 abnormal exit''). This feature is very helpful.
4226 In addition to recording the value of point,
4227 @code{save-excursion} keeps track of the current buffer, and restores
4228 it, too. This means you can write code that will change the buffer and
4229 have @code{save-excursion} switch you back to the original buffer.
4230 This is how @code{save-excursion} is used in @code{append-to-buffer}.
4231 (@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
4233 @node Template for save-excursion
4234 @subsection Template for a @code{save-excursion} Expression
4237 The template for code using @code{save-excursion} is simple:
4247 The body of the function is one or more expressions that will be
4248 evaluated in sequence by the Lisp interpreter. If there is more than
4249 one expression in the body, the value of the last one will be returned
4250 as the value of the @code{save-excursion} function. The other
4251 expressions in the body are evaluated only for their side effects; and
4252 @code{save-excursion} itself is used only for its side effect (which
4253 is restoring the position of point).
4256 In more detail, the template for a @code{save-excursion} expression
4262 @var{first-expression-in-body}
4263 @var{second-expression-in-body}
4264 @var{third-expression-in-body}
4266 @var{last-expression-in-body})
4271 An expression, of course, may be a symbol on its own or a list.
4273 In Emacs Lisp code, a @code{save-excursion} expression often occurs
4274 within the body of a @code{let} expression. It looks like this:
4287 In the last few chapters we have introduced a macro and a fair number
4288 of functions and special forms. Here they are described in brief,
4289 along with a few similar functions that have not been mentioned yet.
4292 @item eval-last-sexp
4293 Evaluate the last symbolic expression before the current location of
4294 point. The value is printed in the echo area unless the function is
4295 invoked with an argument; in that case, the output is printed in the
4296 current buffer. This command is normally bound to @kbd{C-x C-e}.
4299 Define function. This macro has up to five parts: the name, a
4300 template for the arguments that will be passed to the function,
4301 documentation, an optional interactive declaration, and the body of
4305 For example, in Emacs the function definition of
4306 @code{dired-unmark-all-marks} is as follows.
4310 (defun dired-unmark-all-marks ()
4311 "Remove all marks from all files in the Dired buffer."
4313 (dired-unmark-all-files ?\r))
4318 Declare to the interpreter that the function can be used
4319 interactively. This special form may be followed by a string with one
4320 or more parts that pass the information to the arguments of the
4321 function, in sequence. These parts may also tell the interpreter to
4322 prompt for information. Parts of the string are separated by
4323 newlines, @samp{\n}.
4326 Common code characters are:
4330 The name of an existing buffer.
4333 The name of an existing file.
4336 The numeric prefix argument. (Note that this @code{p} is lower case.)
4339 Point and the mark, as two numeric arguments, smallest first. This
4340 is the only code letter that specifies two successive arguments
4344 @xref{Interactive Codes, , Code Characters for @samp{interactive},
4345 elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of
4349 Declare that a list of variables is for use within the body of the
4350 @code{let} and give them an initial value, either @code{nil} or a
4351 specified value; then evaluate the rest of the expressions in the body
4352 of the @code{let} and return the value of the last one. Inside the
4353 body of the @code{let}, the Lisp interpreter does not see the values of
4354 the variables of the same names that are bound outside of the
4362 (let ((foo (buffer-name))
4363 (bar (buffer-size)))
4365 "This buffer is %s and has %d characters."
4370 @item save-excursion
4371 Record the values of point and the current buffer before
4372 evaluating the body of this special form. Restore the value of point and
4380 (message "We are %d characters into this buffer."
4383 (goto-char (point-min)) (point))))
4388 Evaluate the first argument to the function; if it is true, evaluate
4389 the second argument; else evaluate the third argument, if there is one.
4391 The @code{if} special form is called a @dfn{conditional}. There are
4392 other conditionals in Emacs Lisp, but @code{if} is perhaps the most
4400 (if (= 22 emacs-major-version)
4401 (message "This is version 22 Emacs")
4402 (message "This is not version 22 Emacs"))
4411 The @code{<} function tests whether its first argument is smaller than
4412 its second argument. A corresponding function, @code{>}, tests whether
4413 the first argument is greater than the second. Likewise, @code{<=}
4414 tests whether the first argument is less than or equal to the second and
4415 @code{>=} tests whether the first argument is greater than or equal to
4416 the second. In all cases, both arguments must be numbers or markers
4417 (markers indicate positions in buffers).
4421 The @code{=} function tests whether two arguments, both numbers or
4427 Test whether two objects are the same. @code{equal} uses one meaning
4428 of the word ``same'' and @code{eq} uses another: @code{equal} returns
4429 true if the two objects have a similar structure and contents, such as
4430 two copies of the same book. On the other hand, @code{eq}, returns
4431 true if both arguments are actually the same object.
4440 The @code{string-lessp} function tests whether its first argument is
4441 smaller than the second argument. A shorter, alternative name for the
4442 same function (a @code{defalias}) is @code{string<}.
4444 The arguments to @code{string-lessp} must be strings or symbols; the
4445 ordering is lexicographic, so case is significant. The print names of
4446 symbols are used instead of the symbols themselves.
4448 @cindex @samp{empty string} defined
4449 An empty string, @samp{""}, a string with no characters in it, is
4450 smaller than any string of characters.
4452 @code{string-equal} provides the corresponding test for equality. Its
4453 shorter, alternative name is @code{string=}. There are no string test
4454 functions that correspond to @var{>}, @code{>=}, or @code{<=}.
4457 Print a message in the echo area. The first argument is a string that
4458 can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of
4459 arguments that follow the string. The argument used by @samp{%s} must
4460 be a string or a symbol; the argument used by @samp{%d} must be a
4461 number. The argument used by @samp{%c} must be an @sc{ascii} code
4462 number; it will be printed as the character with that @sc{ascii} code.
4463 (Various other %-sequences have not been mentioned.)
4467 The @code{setq} function sets the value of its first argument to the
4468 value of the second argument. The first argument is automatically
4469 quoted by @code{setq}. It does the same for succeeding pairs of
4470 arguments. Another function, @code{set}, takes only two arguments and
4471 evaluates both of them before setting the value returned by its first
4472 argument to the value returned by its second argument.
4475 Without an argument, return the name of the buffer, as a string.
4477 @item buffer-file-name
4478 Without an argument, return the name of the file the buffer is
4481 @item current-buffer
4482 Return the buffer in which Emacs is active; it may not be
4483 the buffer that is visible on the screen.
4486 Return the most recently selected buffer (other than the buffer passed
4487 to @code{other-buffer} as an argument and other than the current
4490 @item switch-to-buffer
4491 Select a buffer for Emacs to be active in and display it in the current
4492 window so users can look at it. Usually bound to @kbd{C-x b}.
4495 Switch Emacs's attention to a buffer on which programs will run. Don't
4496 alter what the window is showing.
4499 Return the number of characters in the current buffer.
4502 Return the value of the current position of the cursor, as an
4503 integer counting the number of characters from the beginning of the
4507 Return the minimum permissible value of point in
4508 the current buffer. This is 1, unless narrowing is in effect.
4511 Return the value of the maximum permissible value of point in the
4512 current buffer. This is the end of the buffer, unless narrowing is in
4517 @node defun Exercises
4522 Write a non-interactive function that doubles the value of its
4523 argument, a number. Make that function interactive.
4526 Write a function that tests whether the current value of
4527 @code{fill-column} is greater than the argument passed to the function,
4528 and if so, prints an appropriate message.
4531 @node Buffer Walk Through
4532 @chapter A Few Buffer-Related Functions
4534 In this chapter we study in detail several of the functions used in GNU
4535 Emacs. This is called a ``walk-through''. These functions are used as
4536 examples of Lisp code, but are not imaginary examples; with the
4537 exception of the first, simplified function definition, these functions
4538 show the actual code used in GNU Emacs. You can learn a great deal from
4539 these definitions. The functions described here are all related to
4540 buffers. Later, we will study other functions.
4543 * Finding More:: How to find more information.
4544 * simplified-beginning-of-buffer:: Shows @code{goto-char},
4545 @code{point-min}, and @code{push-mark}.
4546 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
4547 * append-to-buffer:: Uses @code{save-excursion} and
4548 @code{insert-buffer-substring}.
4549 * Buffer Related Review:: Review.
4550 * Buffer Exercises::
4554 @section Finding More Information
4556 @findex describe-function, @r{introduced}
4557 @cindex Find function documentation
4558 In this walk-through, I will describe each new function as we come to
4559 it, sometimes in detail and sometimes briefly. If you are interested,
4560 you can get the full documentation of any Emacs Lisp function at any
4561 time by typing @kbd{C-h f} and then the name of the function (and then
4562 @key{RET}). Similarly, you can get the full documentation for a
4563 variable by typing @kbd{C-h v} and then the name of the variable (and
4566 @cindex Find source of function
4567 @c In version 22, tells location both of C and of Emacs Lisp
4568 Also, @code{describe-function} will tell you the location of the
4569 function definition.
4571 Put point into the name of the file that contains the function and
4572 press the @key{RET} key. In this case, @key{RET} means
4573 @code{push-button} rather than ``return'' or ``enter''. Emacs will take
4574 you directly to the function definition.
4579 If you move point over the file name and press
4580 the @key{RET} key, which in this case means @code{help-follow} rather
4581 than ``return'' or ``enter'', Emacs will take you directly to the function
4585 More generally, if you want to see a function in its original source
4586 file, you can use the @code{find-tag} function to jump to it.
4587 @code{find-tag} works with a wide variety of languages, not just
4588 Lisp, and C, and it works with non-programming text as well. For
4589 example, @code{find-tag} will jump to the various nodes in the
4590 Texinfo source file of this document.
4591 The @code{find-tag} function depends on @dfn{tags tables} that record
4592 the locations of the functions, variables, and other items to which
4593 @code{find-tag} jumps.
4595 To use the @code{find-tag} command, type @kbd{M-.} (i.e., press the
4596 period key while holding down the @key{META} key, or else type the
4597 @key{ESC} key and then type the period key), and then, at the prompt,
4598 type in the name of the function whose source code you want to see,
4599 such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will
4600 switch buffers and display the source code for the function on your
4601 screen. To switch back to your current buffer, type @kbd{C-x b
4602 @key{RET}}. (On some keyboards, the @key{META} key is labeled
4605 @c !!! 22.1.1 tags table location in this paragraph
4606 @cindex TAGS table, specifying
4608 Depending on how the initial default values of your copy of Emacs are
4609 set, you may also need to specify the location of your tags table,
4610 which is a file called @file{TAGS}. For example, if you are
4611 interested in Emacs sources, the tags table you will most likely want,
4612 if it has already been created for you, will be in a subdirectory of
4613 the @file{/usr/local/share/emacs/} directory; thus you would use the
4614 @code{M-x visit-tags-table} command and specify a pathname such as
4615 @file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table
4616 has not already been created, you will have to create it yourself. It
4617 will be in a file such as @file{/usr/local/src/emacs/src/TAGS}.
4620 To create a @file{TAGS} file in a specific directory, switch to that
4621 directory in Emacs using @kbd{M-x cd} command, or list the directory
4622 with @kbd{C-x d} (@code{dired}). Then run the compile command, with
4623 @w{@code{etags *.el}} as the command to execute:
4626 M-x compile RET etags *.el RET
4629 For more information, see @ref{etags, , Create Your Own @file{TAGS} File}.
4631 After you become more familiar with Emacs Lisp, you will find that you will
4632 frequently use @code{find-tag} to navigate your way around source code;
4633 and you will create your own @file{TAGS} tables.
4635 @cindex Library, as term for ``file''
4636 Incidentally, the files that contain Lisp code are conventionally
4637 called @dfn{libraries}. The metaphor is derived from that of a
4638 specialized library, such as a law library or an engineering library,
4639 rather than a general library. Each library, or file, contains
4640 functions that relate to a particular topic or activity, such as
4641 @file{abbrev.el} for handling abbreviations and other typing
4642 shortcuts, and @file{help.el} for help. (Sometimes several
4643 libraries provide code for a single activity, as the various
4644 @file{rmail@dots{}} files provide code for reading electronic mail.)
4645 In @cite{The GNU Emacs Manual}, you will see sentences such as ``The
4646 @kbd{C-h p} command lets you search the standard Emacs Lisp libraries
4647 by topic keywords.''
4649 @node simplified-beginning-of-buffer
4650 @section A Simplified @code{beginning-of-buffer} Definition
4651 @findex simplified-beginning-of-buffer
4653 The @code{beginning-of-buffer} command is a good function to start with
4654 since you are likely to be familiar with it and it is easy to
4655 understand. Used as an interactive command, @code{beginning-of-buffer}
4656 moves the cursor to the beginning of the buffer, leaving the mark at the
4657 previous position. It is generally bound to @kbd{M-<}.
4659 In this section, we will discuss a shortened version of the function
4660 that shows how it is most frequently used. This shortened function
4661 works as written, but it does not contain the code for a complex option.
4662 In another section, we will describe the entire function.
4663 (@xref{beginning-of-buffer, , Complete Definition of
4664 @code{beginning-of-buffer}}.)
4666 Before looking at the code, let's consider what the function
4667 definition has to contain: it must include an expression that makes
4668 the function interactive so it can be called by typing @kbd{M-x
4669 beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it
4670 must include code to leave a mark at the original position in the
4671 buffer; and it must include code to move the cursor to the beginning
4675 Here is the complete text of the shortened version of the function:
4679 (defun simplified-beginning-of-buffer ()
4680 "Move point to the beginning of the buffer;
4681 leave mark at previous position."
4684 (goto-char (point-min)))
4688 Like all function definitions, this definition has five parts following
4689 the macro @code{defun}:
4693 The name: in this example, @code{simplified-beginning-of-buffer}.
4696 A list of the arguments: in this example, an empty list, @code{()},
4699 The documentation string.
4702 The interactive expression.
4709 In this function definition, the argument list is empty; this means that
4710 this function does not require any arguments. (When we look at the
4711 definition for the complete function, we will see that it may be passed
4712 an optional argument.)
4714 The interactive expression tells Emacs that the function is intended to
4715 be used interactively. In this example, @code{interactive} does not have
4716 an argument because @code{simplified-beginning-of-buffer} does not
4720 The body of the function consists of the two lines:
4725 (goto-char (point-min))
4729 The first of these lines is the expression, @code{(push-mark)}. When
4730 this expression is evaluated by the Lisp interpreter, it sets a mark at
4731 the current position of the cursor, wherever that may be. The position
4732 of this mark is saved in the mark ring.
4734 The next line is @code{(goto-char (point-min))}. This expression
4735 jumps the cursor to the minimum point in the buffer, that is, to the
4736 beginning of the buffer (or to the beginning of the accessible portion
4737 of the buffer if it is narrowed. @xref{Narrowing & Widening, ,
4738 Narrowing and Widening}.)
4740 The @code{push-mark} command sets a mark at the place where the cursor
4741 was located before it was moved to the beginning of the buffer by the
4742 @code{(goto-char (point-min))} expression. Consequently, you can, if
4743 you wish, go back to where you were originally by typing @kbd{C-x C-x}.
4745 That is all there is to the function definition!
4747 @findex describe-function
4748 When you are reading code such as this and come upon an unfamiliar
4749 function, such as @code{goto-char}, you can find out what it does by
4750 using the @code{describe-function} command. To use this command, type
4751 @kbd{C-h f} and then type in the name of the function and press
4752 @key{RET}. The @code{describe-function} command will print the
4753 function's documentation string in a @file{*Help*} window. For
4754 example, the documentation for @code{goto-char} is:
4758 Set point to POSITION, a number or marker.
4759 Beginning of buffer is position (point-min), end is (point-max).
4764 The function's one argument is the desired position.
4767 (The prompt for @code{describe-function} will offer you the symbol
4768 under or preceding the cursor, so you can save typing by positioning
4769 the cursor right over or after the function and then typing @kbd{C-h f
4772 The @code{end-of-buffer} function definition is written in the same way as
4773 the @code{beginning-of-buffer} definition except that the body of the
4774 function contains the expression @code{(goto-char (point-max))} in place
4775 of @code{(goto-char (point-min))}.
4777 @node mark-whole-buffer
4778 @section The Definition of @code{mark-whole-buffer}
4779 @findex mark-whole-buffer
4781 The @code{mark-whole-buffer} function is no harder to understand than the
4782 @code{simplified-beginning-of-buffer} function. In this case, however,
4783 we will look at the complete function, not a shortened version.
4785 The @code{mark-whole-buffer} function is not as commonly used as the
4786 @code{beginning-of-buffer} function, but is useful nonetheless: it
4787 marks a whole buffer as a region by putting point at the beginning and
4788 a mark at the end of the buffer. It is generally bound to @kbd{C-x
4792 * mark-whole-buffer overview::
4793 * Body of mark-whole-buffer:: Only three lines of code.
4797 @node mark-whole-buffer overview
4798 @unnumberedsubsec An overview of @code{mark-whole-buffer}
4802 In GNU Emacs 22, the code for the complete function looks like this:
4806 (defun mark-whole-buffer ()
4807 "Put point at beginning and mark at end of buffer.
4808 You probably should not use this function in Lisp programs;
4809 it is usually a mistake for a Lisp function to use any subroutine
4810 that uses or sets the mark."
4813 (push-mark (point-max) nil t)
4814 (goto-char (point-min)))
4819 Like all other functions, the @code{mark-whole-buffer} function fits
4820 into the template for a function definition. The template looks like
4825 (defun @var{name-of-function} (@var{argument-list})
4826 "@var{documentation}@dots{}"
4827 (@var{interactive-expression}@dots{})
4832 Here is how the function works: the name of the function is
4833 @code{mark-whole-buffer}; it is followed by an empty argument list,
4834 @samp{()}, which means that the function does not require arguments.
4835 The documentation comes next.
4837 The next line is an @code{(interactive)} expression that tells Emacs
4838 that the function will be used interactively. These details are similar
4839 to the @code{simplified-beginning-of-buffer} function described in the
4843 @node Body of mark-whole-buffer
4844 @subsection Body of @code{mark-whole-buffer}
4846 The body of the @code{mark-whole-buffer} function consists of three
4853 (push-mark (point-max) nil t)
4854 (goto-char (point-min))
4858 The first of these lines is the expression, @code{(push-mark (point))}.
4860 This line does exactly the same job as the first line of the body of
4861 the @code{simplified-beginning-of-buffer} function, which is written
4862 @code{(push-mark)}. In both cases, the Lisp interpreter sets a mark
4863 at the current position of the cursor.
4865 I don't know why the expression in @code{mark-whole-buffer} is written
4866 @code{(push-mark (point))} and the expression in
4867 @code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps
4868 whoever wrote the code did not know that the arguments for
4869 @code{push-mark} are optional and that if @code{push-mark} is not
4870 passed an argument, the function automatically sets mark at the
4871 location of point by default. Or perhaps the expression was written
4872 so as to parallel the structure of the next line. In any case, the
4873 line causes Emacs to determine the position of point and set a mark
4876 In earlier versions of GNU Emacs, the next line of
4877 @code{mark-whole-buffer} was @code{(push-mark (point-max))}. This
4878 expression sets a mark at the point in the buffer that has the highest
4879 number. This will be the end of the buffer (or, if the buffer is
4880 narrowed, the end of the accessible portion of the buffer.
4881 @xref{Narrowing & Widening, , Narrowing and Widening}, for more about
4882 narrowing.) After this mark has been set, the previous mark, the one
4883 set at point, is no longer set, but Emacs remembers its position, just
4884 as all other recent marks are always remembered. This means that you
4885 can, if you wish, go back to that position by typing @kbd{C-u
4889 In GNU Emacs 22, the @code{(point-max)} is slightly more complicated.
4893 (push-mark (point-max) nil t)
4897 The expression works nearly the same as before. It sets a mark at the
4898 highest numbered place in the buffer that it can. However, in this
4899 version, @code{push-mark} has two additional arguments. The second
4900 argument to @code{push-mark} is @code{nil}. This tells the function
4901 it @emph{should} display a message that says ``Mark set'' when it pushes
4902 the mark. The third argument is @code{t}. This tells
4903 @code{push-mark} to activate the mark when Transient Mark mode is
4904 turned on. Transient Mark mode highlights the currently active
4905 region. It is often turned off.
4907 Finally, the last line of the function is @code{(goto-char
4908 (point-min)))}. This is written exactly the same way as it is written
4909 in @code{beginning-of-buffer}. The expression moves the cursor to
4910 the minimum point in the buffer, that is, to the beginning of the buffer
4911 (or to the beginning of the accessible portion of the buffer). As a
4912 result of this, point is placed at the beginning of the buffer and mark
4913 is set at the end of the buffer. The whole buffer is, therefore, the
4916 @c FIXME: the definition of append-to-buffer has been changed (in
4918 @node append-to-buffer
4919 @section The Definition of @code{append-to-buffer}
4920 @findex append-to-buffer
4922 The @code{append-to-buffer} command is more complex than the
4923 @code{mark-whole-buffer} command. What it does is copy the region
4924 (that is, the part of the buffer between point and mark) from the
4925 current buffer to a specified buffer.
4928 * append-to-buffer overview::
4929 * append interactive:: A two part interactive expression.
4930 * append-to-buffer body:: Incorporates a @code{let} expression.
4931 * append save-excursion:: How the @code{save-excursion} works.
4935 @node append-to-buffer overview
4936 @unnumberedsubsec An Overview of @code{append-to-buffer}
4939 @findex insert-buffer-substring
4940 The @code{append-to-buffer} command uses the
4941 @code{insert-buffer-substring} function to copy the region.
4942 @code{insert-buffer-substring} is described by its name: it takes a
4943 substring from a buffer, and inserts it into another buffer.
4945 Most of @code{append-to-buffer} is
4946 concerned with setting up the conditions for
4947 @code{insert-buffer-substring} to work: the code must specify both the
4948 buffer to which the text will go, the window it comes from and goes
4949 to, and the region that will be copied.
4952 Here is the complete text of the function:
4956 (defun append-to-buffer (buffer start end)
4957 "Append to specified buffer the text of the region.
4958 It is inserted into that buffer before its point.
4962 When calling from a program, give three arguments:
4963 BUFFER (or buffer name), START and END.
4964 START and END specify the portion of the current buffer to be copied."
4966 (list (read-buffer "Append to buffer: " (other-buffer
4967 (current-buffer) t))
4968 (region-beginning) (region-end)))
4971 (let ((oldbuf (current-buffer)))
4973 (let* ((append-to (get-buffer-create buffer))
4974 (windows (get-buffer-window-list append-to t t))
4976 (set-buffer append-to)
4977 (setq point (point))
4978 (barf-if-buffer-read-only)
4979 (insert-buffer-substring oldbuf start end)
4980 (dolist (window windows)
4981 (when (= (window-point window) point)
4982 (set-window-point window (point))))))))
4986 The function can be understood by looking at it as a series of
4987 filled-in templates.
4989 The outermost template is for the function definition. In this
4990 function, it looks like this (with several slots filled in):
4994 (defun append-to-buffer (buffer start end)
4995 "@var{documentation}@dots{}"
4996 (interactive @dots{})
5001 The first line of the function includes its name and three arguments.
5002 The arguments are the @code{buffer} to which the text will be copied, and
5003 the @code{start} and @code{end} of the region in the current buffer that
5006 The next part of the function is the documentation, which is clear and
5007 complete. As is conventional, the three arguments are written in
5008 upper case so you will notice them easily. Even better, they are
5009 described in the same order as in the argument list.
5011 Note that the documentation distinguishes between a buffer and its
5012 name. (The function can handle either.)
5014 @node append interactive
5015 @subsection The @code{append-to-buffer} Interactive Expression
5017 Since the @code{append-to-buffer} function will be used interactively,
5018 the function must have an @code{interactive} expression. (For a
5019 review of @code{interactive}, see @ref{Interactive, , Making a
5020 Function Interactive}.) The expression reads as follows:
5026 "Append to buffer: "
5027 (other-buffer (current-buffer) t))
5034 This expression is not one with letters standing for parts, as
5035 described earlier. Instead, it starts a list with these parts:
5037 The first part of the list is an expression to read the name of a
5038 buffer and return it as a string. That is @code{read-buffer}. The
5039 function requires a prompt as its first argument, @samp{"Append to
5040 buffer: "}. Its second argument tells the command what value to
5041 provide if you don't specify anything.
5043 In this case that second argument is an expression containing the
5044 function @code{other-buffer}, an exception, and a @samp{t}, standing
5047 The first argument to @code{other-buffer}, the exception, is yet
5048 another function, @code{current-buffer}. That is not going to be
5049 returned. The second argument is the symbol for true, @code{t}. that
5050 tells @code{other-buffer} that it may show visible buffers (except in
5051 this case, it will not show the current buffer, which makes sense).
5054 The expression looks like this:
5057 (other-buffer (current-buffer) t)
5060 The second and third arguments to the @code{list} expression are
5061 @code{(region-beginning)} and @code{(region-end)}. These two
5062 functions specify the beginning and end of the text to be appended.
5065 Originally, the command used the letters @samp{B} and @samp{r}.
5066 The whole @code{interactive} expression looked like this:
5069 (interactive "BAppend to buffer:@: \nr")
5073 But when that was done, the default value of the buffer switched to
5074 was invisible. That was not wanted.
5076 (The prompt was separated from the second argument with a newline,
5077 @samp{\n}. It was followed by an @samp{r} that told Emacs to bind the
5078 two arguments that follow the symbol @code{buffer} in the function's
5079 argument list (that is, @code{start} and @code{end}) to the values of
5080 point and mark. That argument worked fine.)
5082 @node append-to-buffer body
5083 @subsection The Body of @code{append-to-buffer}
5086 in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el
5088 (defun append-to-buffer (buffer start end)
5089 "Append to specified buffer the text of the region.
5090 It is inserted into that buffer before its point.
5092 When calling from a program, give three arguments:
5093 BUFFER (or buffer name), START and END.
5094 START and END specify the portion of the current buffer to be copied."
5096 (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t))
5097 (region-beginning) (region-end)))
5098 (let ((oldbuf (current-buffer)))
5100 (let* ((append-to (get-buffer-create buffer))
5101 (windows (get-buffer-window-list append-to t t))
5103 (set-buffer append-to)
5104 (setq point (point))
5105 (barf-if-buffer-read-only)
5106 (insert-buffer-substring oldbuf start end)
5107 (dolist (window windows)
5108 (when (= (window-point window) point)
5109 (set-window-point window (point))))))))
5112 The body of the @code{append-to-buffer} function begins with @code{let}.
5114 As we have seen before (@pxref{let, , @code{let}}), the purpose of a
5115 @code{let} expression is to create and give initial values to one or
5116 more variables that will only be used within the body of the
5117 @code{let}. This means that such a variable will not be confused with
5118 any variable of the same name outside the @code{let} expression.
5120 We can see how the @code{let} expression fits into the function as a
5121 whole by showing a template for @code{append-to-buffer} with the
5122 @code{let} expression in outline:
5126 (defun append-to-buffer (buffer start end)
5127 "@var{documentation}@dots{}"
5128 (interactive @dots{})
5129 (let ((@var{variable} @var{value}))
5134 The @code{let} expression has three elements:
5138 The symbol @code{let};
5141 A varlist containing, in this case, a single two-element list,
5142 @code{(@var{variable} @var{value})};
5145 The body of the @code{let} expression.
5149 In the @code{append-to-buffer} function, the varlist looks like this:
5152 (oldbuf (current-buffer))
5156 In this part of the @code{let} expression, the one variable,
5157 @code{oldbuf}, is bound to the value returned by the
5158 @code{(current-buffer)} expression. The variable, @code{oldbuf}, is
5159 used to keep track of the buffer in which you are working and from
5160 which you will copy.
5162 The element or elements of a varlist are surrounded by a set of
5163 parentheses so the Lisp interpreter can distinguish the varlist from
5164 the body of the @code{let}. As a consequence, the two-element list
5165 within the varlist is surrounded by a circumscribing set of parentheses.
5166 The line looks like this:
5170 (let ((oldbuf (current-buffer)))
5176 The two parentheses before @code{oldbuf} might surprise you if you did
5177 not realize that the first parenthesis before @code{oldbuf} marks the
5178 boundary of the varlist and the second parenthesis marks the beginning
5179 of the two-element list, @code{(oldbuf (current-buffer))}.
5181 @node append save-excursion
5182 @subsection @code{save-excursion} in @code{append-to-buffer}
5184 The body of the @code{let} expression in @code{append-to-buffer}
5185 consists of a @code{save-excursion} expression.
5187 The @code{save-excursion} function saves the location of point, and restores it
5188 to that position after the expressions in the
5189 body of the @code{save-excursion} complete execution. In addition,
5190 @code{save-excursion} keeps track of the original buffer, and
5191 restores it. This is how @code{save-excursion} is used in
5192 @code{append-to-buffer}.
5195 @cindex Indentation for formatting
5196 @cindex Formatting convention
5197 Incidentally, it is worth noting here that a Lisp function is normally
5198 formatted so that everything that is enclosed in a multi-line spread is
5199 indented more to the right than the first symbol. In this function
5200 definition, the @code{let} is indented more than the @code{defun}, and
5201 the @code{save-excursion} is indented more than the @code{let}, like
5217 This formatting convention makes it easy to see that the lines in
5218 the body of the @code{save-excursion} are enclosed by the parentheses
5219 associated with @code{save-excursion}, just as the
5220 @code{save-excursion} itself is enclosed by the parentheses associated
5221 with the @code{let}:
5225 (let ((oldbuf (current-buffer)))
5228 (set-buffer @dots{})
5229 (insert-buffer-substring oldbuf start end)
5235 The use of the @code{save-excursion} function can be viewed as a process
5236 of filling in the slots of a template:
5241 @var{first-expression-in-body}
5242 @var{second-expression-in-body}
5244 @var{last-expression-in-body})
5250 In this function, the body of the @code{save-excursion} contains only
5251 one expression, the @code{let*} expression. You know about a
5252 @code{let} function. The @code{let*} function is different. It has a
5253 @samp{*} in its name. It enables Emacs to set each variable in its
5254 varlist in sequence, one after another.
5256 Its critical feature is that variables later in the varlist can make
5257 use of the values to which Emacs set variables earlier in the varlist.
5258 @xref{fwd-para let, , The @code{let*} expression}.
5260 We will skip functions like @code{let*} and focus on two: the
5261 @code{set-buffer} function and the @code{insert-buffer-substring}
5265 In the old days, the @code{set-buffer} expression was simply
5268 (set-buffer (get-buffer-create buffer))
5276 (set-buffer append-to)
5280 @code{append-to} is bound to @code{(get-buffer-create buffer)} earlier
5281 on in the @code{let*} expression. That extra binding would not be
5282 necessary except for that @code{append-to} is used later in the
5283 varlist as an argument to @code{get-buffer-window-list}.
5288 (let ((oldbuf (current-buffer)))
5290 (let* ((append-to (get-buffer-create buffer))
5291 (windows (get-buffer-window-list append-to t t))
5293 (set-buffer append-to)
5294 (setq point (point))
5295 (barf-if-buffer-read-only)
5296 (insert-buffer-substring oldbuf start end)
5297 (dolist (window windows)
5298 (when (= (window-point window) point)
5299 (set-window-point window (point))))))))
5302 The @code{append-to-buffer} function definition inserts text from the
5303 buffer in which you are currently to a named buffer. It happens that
5304 @code{insert-buffer-substring} copies text from another buffer to the
5305 current buffer, just the reverse---that is why the
5306 @code{append-to-buffer} definition starts out with a @code{let} that
5307 binds the local symbol @code{oldbuf} to the value returned by
5308 @code{current-buffer}.
5311 The @code{insert-buffer-substring} expression looks like this:
5314 (insert-buffer-substring oldbuf start end)
5318 The @code{insert-buffer-substring} function copies a string
5319 @emph{from} the buffer specified as its first argument and inserts the
5320 string into the present buffer. In this case, the argument to
5321 @code{insert-buffer-substring} is the value of the variable created
5322 and bound by the @code{let}, namely the value of @code{oldbuf}, which
5323 was the current buffer when you gave the @code{append-to-buffer}
5326 After @code{insert-buffer-substring} has done its work,
5327 @code{save-excursion} will restore the action to the original buffer
5328 and @code{append-to-buffer} will have done its job.
5331 Written in skeletal form, the workings of the body look like this:
5335 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5336 (save-excursion ; @r{Keep track of buffer.}
5338 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})
5340 @var{change-back-to-original-buffer-when-finished}
5341 @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished}
5345 In summary, @code{append-to-buffer} works as follows: it saves the
5346 value of the current buffer in the variable called @code{oldbuf}. It
5347 gets the new buffer (creating one if need be) and switches Emacs's
5348 attention to it. Using the value of @code{oldbuf}, it inserts the
5349 region of text from the old buffer into the new buffer; and then using
5350 @code{save-excursion}, it brings you back to your original buffer.
5352 In looking at @code{append-to-buffer}, you have explored a fairly
5353 complex function. It shows how to use @code{let} and
5354 @code{save-excursion}, and how to change to and come back from another
5355 buffer. Many function definitions use @code{let},
5356 @code{save-excursion}, and @code{set-buffer} this way.
5358 @node Buffer Related Review
5361 Here is a brief summary of the various functions discussed in this chapter.
5364 @item describe-function
5365 @itemx describe-variable
5366 Print the documentation for a function or variable.
5367 Conventionally bound to @kbd{C-h f} and @kbd{C-h v}.
5370 Find the file containing the source for a function or variable and
5371 switch buffers to it, positioning point at the beginning of the item.
5372 Conventionally bound to @kbd{M-.} (that's a period following the
5375 @item save-excursion
5376 Save the location of point and restore its value after the
5377 arguments to @code{save-excursion} have been evaluated. Also, remember
5378 the current buffer and return to it.
5381 Set mark at a location and record the value of the previous mark on the
5382 mark ring. The mark is a location in the buffer that will keep its
5383 relative position even if text is added to or removed from the buffer.
5386 Set point to the location specified by the value of the argument, which
5387 can be a number, a marker, or an expression that returns the number of
5388 a position, such as @code{(point-min)}.
5390 @item insert-buffer-substring
5391 Copy a region of text from a buffer that is passed to the function as
5392 an argument and insert the region into the current buffer.
5394 @item mark-whole-buffer
5395 Mark the whole buffer as a region. Normally bound to @kbd{C-x h}.
5398 Switch the attention of Emacs to another buffer, but do not change the
5399 window being displayed. Used when the program rather than a human is
5400 to work on a different buffer.
5402 @item get-buffer-create
5404 Find a named buffer or create one if a buffer of that name does not
5405 exist. The @code{get-buffer} function returns @code{nil} if the named
5406 buffer does not exist.
5410 @node Buffer Exercises
5415 Write your own @code{simplified-end-of-buffer} function definition;
5416 then test it to see whether it works.
5419 Use @code{if} and @code{get-buffer} to write a function that prints a
5420 message telling you whether a buffer exists.
5423 Using @code{find-tag}, find the source for the @code{copy-to-buffer}
5428 @chapter A Few More Complex Functions
5430 In this chapter, we build on what we have learned in previous chapters
5431 by looking at more complex functions. The @code{copy-to-buffer}
5432 function illustrates use of two @code{save-excursion} expressions in
5433 one definition, while the @code{insert-buffer} function illustrates
5434 use of an asterisk in an @code{interactive} expression, use of
5435 @code{or}, and the important distinction between a name and the object
5436 to which the name refers.
5439 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
5440 * insert-buffer:: Read-only, and with @code{or}.
5441 * beginning-of-buffer:: Shows @code{goto-char},
5442 @code{point-min}, and @code{push-mark}.
5443 * Second Buffer Related Review::
5444 * optional Exercise::
5447 @node copy-to-buffer
5448 @section The Definition of @code{copy-to-buffer}
5449 @findex copy-to-buffer
5451 After understanding how @code{append-to-buffer} works, it is easy to
5452 understand @code{copy-to-buffer}. This function copies text into a
5453 buffer, but instead of adding to the second buffer, it replaces all the
5454 previous text in the second buffer.
5457 The body of @code{copy-to-buffer} looks like this,
5462 (interactive "BCopy to buffer: \nr")
5463 (let ((oldbuf (current-buffer)))
5464 (with-current-buffer (get-buffer-create buffer)
5465 (barf-if-buffer-read-only)
5468 (insert-buffer-substring oldbuf start end)))))
5472 The @code{copy-to-buffer} function has a simpler @code{interactive}
5473 expression than @code{append-to-buffer}.
5476 The definition then says
5479 (with-current-buffer (get-buffer-create buffer) @dots{}
5482 First, look at the earliest inner expression; that is evaluated first.
5483 That expression starts with @code{get-buffer-create buffer}. The
5484 function tells the computer to use the buffer with the name specified
5485 as the one to which you are copying, or if such a buffer does not
5486 exist, to create it. Then, the @code{with-current-buffer} function
5487 evaluates its body with that buffer temporarily current.
5489 (This demonstrates another way to shift the computer's attention but
5490 not the user's. The @code{append-to-buffer} function showed how to do
5491 the same with @code{save-excursion} and @code{set-buffer}.
5492 @code{with-current-buffer} is a newer, and arguably easier,
5495 The @code{barf-if-buffer-read-only} function sends you an error
5496 message saying the buffer is read-only if you cannot modify it.
5498 The next line has the @code{erase-buffer} function as its sole
5499 contents. That function erases the buffer.
5501 Finally, the last two lines contain the @code{save-excursion}
5502 expression with @code{insert-buffer-substring} as its body.
5503 The @code{insert-buffer-substring} expression copies the text from
5504 the buffer you are in (and you have not seen the computer shift its
5505 attention, so you don't know that that buffer is now called
5508 Incidentally, this is what is meant by ``replacement''. To replace text,
5509 Emacs erases the previous text and then inserts new text.
5512 In outline, the body of @code{copy-to-buffer} looks like this:
5516 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5517 (@var{with-the-buffer-you-are-copying-to}
5518 (@var{but-do-not-erase-or-copy-to-a-read-only-buffer})
5521 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})))
5526 @section The Definition of @code{insert-buffer}
5527 @findex insert-buffer
5529 @code{insert-buffer} is yet another buffer-related function. This
5530 command copies another buffer @emph{into} the current buffer. It is the
5531 reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they
5532 copy a region of text @emph{from} the current buffer to another buffer.
5534 Here is a discussion based on the original code. The code was
5535 simplified in 2003 and is harder to understand.
5537 (@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see
5538 a discussion of the new body.)
5540 In addition, this code illustrates the use of @code{interactive} with a
5541 buffer that might be @dfn{read-only} and the important distinction
5542 between the name of an object and the object actually referred to.
5545 * insert-buffer code::
5546 * insert-buffer interactive:: When you can read, but not write.
5547 * insert-buffer body:: The body has an @code{or} and a @code{let}.
5548 * if & or:: Using an @code{if} instead of an @code{or}.
5549 * Insert or:: How the @code{or} expression works.
5550 * Insert let:: Two @code{save-excursion} expressions.
5551 * New insert-buffer::
5555 @node insert-buffer code
5556 @unnumberedsubsec The Code for @code{insert-buffer}
5560 Here is the earlier code:
5564 (defun insert-buffer (buffer)
5565 "Insert after point the contents of BUFFER.
5566 Puts mark after the inserted text.
5567 BUFFER may be a buffer or a buffer name."
5568 (interactive "*bInsert buffer:@: ")
5571 (or (bufferp buffer)
5572 (setq buffer (get-buffer buffer)))
5573 (let (start end newmark)
5577 (setq start (point-min) end (point-max)))
5580 (insert-buffer-substring buffer start end)
5581 (setq newmark (point)))
5582 (push-mark newmark)))
5587 As with other function definitions, you can use a template to see an
5588 outline of the function:
5592 (defun insert-buffer (buffer)
5593 "@var{documentation}@dots{}"
5594 (interactive "*bInsert buffer:@: ")
5599 @node insert-buffer interactive
5600 @subsection The Interactive Expression in @code{insert-buffer}
5601 @findex interactive, @r{example use of}
5603 In @code{insert-buffer}, the argument to the @code{interactive}
5604 declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert
5608 * Read-only buffer:: When a buffer cannot be modified.
5609 * b for interactive:: An existing buffer or else its name.
5612 @node Read-only buffer
5613 @unnumberedsubsubsec A Read-only Buffer
5614 @cindex Read-only buffer
5615 @cindex Asterisk for read-only buffer
5616 @findex * @r{for read-only buffer}
5618 The asterisk is for the situation when the current buffer is a
5619 read-only buffer---a buffer that cannot be modified. If
5620 @code{insert-buffer} is called when the current buffer is read-only, a
5621 message to this effect is printed in the echo area and the terminal
5622 may beep or blink at you; you will not be permitted to insert anything
5623 into current buffer. The asterisk does not need to be followed by a
5624 newline to separate it from the next argument.
5626 @node b for interactive
5627 @unnumberedsubsubsec @samp{b} in an Interactive Expression
5629 The next argument in the interactive expression starts with a lower
5630 case @samp{b}. (This is different from the code for
5631 @code{append-to-buffer}, which uses an upper-case @samp{B}.
5632 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
5633 The lower-case @samp{b} tells the Lisp interpreter that the argument
5634 for @code{insert-buffer} should be an existing buffer or else its
5635 name. (The upper-case @samp{B} option provides for the possibility
5636 that the buffer does not exist.) Emacs will prompt you for the name
5637 of the buffer, offering you a default buffer, with name completion
5638 enabled. If the buffer does not exist, you receive a message that
5639 says ``No match''; your terminal may beep at you as well.
5641 The new and simplified code generates a list for @code{interactive}.
5642 It uses the @code{barf-if-buffer-read-only} and @code{read-buffer}
5643 functions with which we are already familiar and the @code{progn}
5644 special form with which we are not. (It will be described later.)
5646 @node insert-buffer body
5647 @subsection The Body of the @code{insert-buffer} Function
5649 The body of the @code{insert-buffer} function has two major parts: an
5650 @code{or} expression and a @code{let} expression. The purpose of the
5651 @code{or} expression is to ensure that the argument @code{buffer} is
5652 bound to a buffer and not just the name of a buffer. The body of the
5653 @code{let} expression contains the code which copies the other buffer
5654 into the current buffer.
5657 In outline, the two expressions fit into the @code{insert-buffer}
5662 (defun insert-buffer (buffer)
5663 "@var{documentation}@dots{}"
5664 (interactive "*bInsert buffer:@: ")
5669 (let (@var{varlist})
5670 @var{body-of-}@code{let}@dots{} )
5674 To understand how the @code{or} expression ensures that the argument
5675 @code{buffer} is bound to a buffer and not to the name of a buffer, it
5676 is first necessary to understand the @code{or} function.
5678 Before doing this, let me rewrite this part of the function using
5679 @code{if} so that you can see what is done in a manner that will be familiar.
5682 @subsection @code{insert-buffer} With an @code{if} Instead of an @code{or}
5684 The job to be done is to make sure the value of @code{buffer} is a
5685 buffer itself and not the name of a buffer. If the value is the name,
5686 then the buffer itself must be got.
5688 You can imagine yourself at a conference where an usher is wandering
5689 around holding a list with your name on it and looking for you: the
5690 usher is bound to your name, not to you; but when the usher finds
5691 you and takes your arm, the usher becomes bound to you.
5694 In Lisp, you might describe this situation like this:
5698 (if (not (holding-on-to-guest))
5699 (find-and-take-arm-of-guest))
5703 We want to do the same thing with a buffer---if we do not have the
5704 buffer itself, we want to get it.
5707 Using a predicate called @code{bufferp} that tells us whether we have a
5708 buffer (rather than its name), we can write the code like this:
5712 (if (not (bufferp buffer)) ; @r{if-part}
5713 (setq buffer (get-buffer buffer))) ; @r{then-part}
5718 Here, the true-or-false-test of the @code{if} expression is
5719 @w{@code{(not (bufferp buffer))}}; and the then-part is the expression
5720 @w{@code{(setq buffer (get-buffer buffer))}}.
5722 In the test, the function @code{bufferp} returns true if its argument is
5723 a buffer---but false if its argument is the name of the buffer. (The
5724 last character of the function name @code{bufferp} is the character
5725 @samp{p}; as we saw earlier, such use of @samp{p} is a convention that
5726 indicates that the function is a predicate, which is a term that means
5727 that the function will determine whether some property is true or false.
5728 @xref{Wrong Type of Argument, , Using the Wrong Type Object as an
5732 The function @code{not} precedes the expression @code{(bufferp buffer)},
5733 so the true-or-false-test looks like this:
5736 (not (bufferp buffer))
5740 @code{not} is a function that returns true if its argument is false
5741 and false if its argument is true. So if @code{(bufferp buffer)}
5742 returns true, the @code{not} expression returns false and vice versa.
5744 Using this test, the @code{if} expression works as follows: when the
5745 value of the variable @code{buffer} is actually a buffer rather than
5746 its name, the true-or-false-test returns false and the @code{if}
5747 expression does not evaluate the then-part. This is fine, since we do
5748 not need to do anything to the variable @code{buffer} if it really is
5751 On the other hand, when the value of @code{buffer} is not a buffer
5752 itself, but the name of a buffer, the true-or-false-test returns true
5753 and the then-part of the expression is evaluated. In this case, the
5754 then-part is @code{(setq buffer (get-buffer buffer))}. This
5755 expression uses the @code{get-buffer} function to return an actual
5756 buffer itself, given its name. The @code{setq} then sets the variable
5757 @code{buffer} to the value of the buffer itself, replacing its previous
5758 value (which was the name of the buffer).
5761 @subsection The @code{or} in the Body
5763 The purpose of the @code{or} expression in the @code{insert-buffer}
5764 function is to ensure that the argument @code{buffer} is bound to a
5765 buffer and not just to the name of a buffer. The previous section shows
5766 how the job could have been done using an @code{if} expression.
5767 However, the @code{insert-buffer} function actually uses @code{or}.
5768 To understand this, it is necessary to understand how @code{or} works.
5771 An @code{or} function can have any number of arguments. It evaluates
5772 each argument in turn and returns the value of the first of its
5773 arguments that is not @code{nil}. Also, and this is a crucial feature
5774 of @code{or}, it does not evaluate any subsequent arguments after
5775 returning the first non-@code{nil} value.
5778 The @code{or} expression looks like this:
5782 (or (bufferp buffer)
5783 (setq buffer (get-buffer buffer)))
5788 The first argument to @code{or} is the expression @code{(bufferp buffer)}.
5789 This expression returns true (a non-@code{nil} value) if the buffer is
5790 actually a buffer, and not just the name of a buffer. In the @code{or}
5791 expression, if this is the case, the @code{or} expression returns this
5792 true value and does not evaluate the next expression---and this is fine
5793 with us, since we do not want to do anything to the value of
5794 @code{buffer} if it really is a buffer.
5796 On the other hand, if the value of @code{(bufferp buffer)} is @code{nil},
5797 which it will be if the value of @code{buffer} is the name of a buffer,
5798 the Lisp interpreter evaluates the next element of the @code{or}
5799 expression. This is the expression @code{(setq buffer (get-buffer
5800 buffer))}. This expression returns a non-@code{nil} value, which
5801 is the value to which it sets the variable @code{buffer}---and this
5802 value is a buffer itself, not the name of a buffer.
5804 The result of all this is that the symbol @code{buffer} is always
5805 bound to a buffer itself rather than to the name of a buffer. All
5806 this is necessary because the @code{set-buffer} function in a
5807 following line only works with a buffer itself, not with the name to a
5811 Incidentally, using @code{or}, the situation with the usher would be
5815 (or (holding-on-to-guest) (find-and-take-arm-of-guest))
5819 @subsection The @code{let} Expression in @code{insert-buffer}
5821 After ensuring that the variable @code{buffer} refers to a buffer itself
5822 and not just to the name of a buffer, the @code{insert-buffer function}
5823 continues with a @code{let} expression. This specifies three local
5824 variables, @code{start}, @code{end}, and @code{newmark} and binds them
5825 to the initial value @code{nil}. These variables are used inside the
5826 remainder of the @code{let} and temporarily hide any other occurrence of
5827 variables of the same name in Emacs until the end of the @code{let}.
5830 The body of the @code{let} contains two @code{save-excursion}
5831 expressions. First, we will look at the inner @code{save-excursion}
5832 expression in detail. The expression looks like this:
5838 (setq start (point-min) end (point-max)))
5843 The expression @code{(set-buffer buffer)} changes Emacs's attention
5844 from the current buffer to the one from which the text will copied.
5845 In that buffer, the variables @code{start} and @code{end} are set to
5846 the beginning and end of the buffer, using the commands
5847 @code{point-min} and @code{point-max}. Note that we have here an
5848 illustration of how @code{setq} is able to set two variables in the
5849 same expression. The first argument of @code{setq} is set to the
5850 value of its second, and its third argument is set to the value of its
5853 After the body of the inner @code{save-excursion} is evaluated, the
5854 @code{save-excursion} restores the original buffer, but @code{start} and
5855 @code{end} remain set to the values of the beginning and end of the
5856 buffer from which the text will be copied.
5859 The outer @code{save-excursion} expression looks like this:
5864 (@var{inner-}@code{save-excursion}@var{-expression}
5865 (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end})
5866 (insert-buffer-substring buffer start end)
5867 (setq newmark (point)))
5872 The @code{insert-buffer-substring} function copies the text
5873 @emph{into} the current buffer @emph{from} the region indicated by
5874 @code{start} and @code{end} in @code{buffer}. Since the whole of the
5875 second buffer lies between @code{start} and @code{end}, the whole of
5876 the second buffer is copied into the buffer you are editing. Next,
5877 the value of point, which will be at the end of the inserted text, is
5878 recorded in the variable @code{newmark}.
5880 After the body of the outer @code{save-excursion} is evaluated, point
5881 is relocated to its original place.
5883 However, it is convenient to locate a mark at the end of the newly
5884 inserted text and locate point at its beginning. The @code{newmark}
5885 variable records the end of the inserted text. In the last line of
5886 the @code{let} expression, the @code{(push-mark newmark)} expression
5887 function sets a mark to this location. (The previous location of the
5888 mark is still accessible; it is recorded on the mark ring and you can
5889 go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is
5890 located at the beginning of the inserted text, which is where it was
5891 before you called the insert function, the position of which was saved
5892 by the first @code{save-excursion}.
5895 The whole @code{let} expression looks like this:
5899 (let (start end newmark)
5903 (setq start (point-min) end (point-max)))
5904 (insert-buffer-substring buffer start end)
5905 (setq newmark (point)))
5906 (push-mark newmark))
5910 Like the @code{append-to-buffer} function, the @code{insert-buffer}
5911 function uses @code{let}, @code{save-excursion}, and
5912 @code{set-buffer}. In addition, the function illustrates one way to
5913 use @code{or}. All these functions are building blocks that we will
5914 find and use again and again.
5916 @node New insert-buffer
5917 @subsection New Body for @code{insert-buffer}
5918 @findex insert-buffer, new version body
5919 @findex new version body for insert-buffer
5921 The body in the GNU Emacs 22 version is more confusing than the original.
5924 It consists of two expressions,
5930 (insert-buffer-substring (get-buffer buffer))
5938 except, and this is what confuses novices, very important work is done
5939 inside the @code{push-mark} expression.
5941 The @code{get-buffer} function returns a buffer with the name
5942 provided. You will note that the function is @emph{not} called
5943 @code{get-buffer-create}; it does not create a buffer if one does not
5944 already exist. The buffer returned by @code{get-buffer}, an existing
5945 buffer, is passed to @code{insert-buffer-substring}, which inserts the
5946 whole of the buffer (since you did not specify anything else).
5948 The location into which the buffer is inserted is recorded by
5949 @code{push-mark}. Then the function returns @code{nil}, the value of
5950 its last command. Put another way, the @code{insert-buffer} function
5951 exists only to produce a side effect, inserting another buffer, not to
5954 @node beginning-of-buffer
5955 @section Complete Definition of @code{beginning-of-buffer}
5956 @findex beginning-of-buffer
5958 The basic structure of the @code{beginning-of-buffer} function has
5959 already been discussed. (@xref{simplified-beginning-of-buffer, , A
5960 Simplified @code{beginning-of-buffer} Definition}.)
5961 This section describes the complex part of the definition.
5963 As previously described, when invoked without an argument,
5964 @code{beginning-of-buffer} moves the cursor to the beginning of the
5965 buffer (in truth, the beginning of the accessible portion of the
5966 buffer), leaving the mark at the previous position. However, when the
5967 command is invoked with a number between one and ten, the function
5968 considers that number to be a fraction of the length of the buffer,
5969 measured in tenths, and Emacs moves the cursor that fraction of the
5970 way from the beginning of the buffer. Thus, you can either call this
5971 function with the key command @kbd{M-<}, which will move the cursor to
5972 the beginning of the buffer, or with a key command such as @kbd{C-u 7
5973 M-<} which will move the cursor to a point 70% of the way through the
5974 buffer. If a number bigger than ten is used for the argument, it
5975 moves to the end of the buffer.
5977 The @code{beginning-of-buffer} function can be called with or without an
5978 argument. The use of the argument is optional.
5981 * Optional Arguments::
5982 * beginning-of-buffer opt arg:: Example with optional argument.
5983 * beginning-of-buffer complete::
5986 @node Optional Arguments
5987 @subsection Optional Arguments
5989 Unless told otherwise, Lisp expects that a function with an argument in
5990 its function definition will be called with a value for that argument.
5991 If that does not happen, you get an error and a message that says
5992 @samp{Wrong number of arguments}.
5994 @cindex Optional arguments
5997 However, optional arguments are a feature of Lisp: a particular
5998 @dfn{keyword} is used to tell the Lisp interpreter that an argument is
5999 optional. The keyword is @code{&optional}. (The @samp{&} in front of
6000 @samp{optional} is part of the keyword.) In a function definition, if
6001 an argument follows the keyword @code{&optional}, no value need be
6002 passed to that argument when the function is called.
6005 The first line of the function definition of @code{beginning-of-buffer}
6006 therefore looks like this:
6009 (defun beginning-of-buffer (&optional arg)
6013 In outline, the whole function looks like this:
6017 (defun beginning-of-buffer (&optional arg)
6018 "@var{documentation}@dots{}"
6020 (or (@var{is-the-argument-a-cons-cell} arg)
6021 (and @var{are-both-transient-mark-mode-and-mark-active-true})
6023 (let (@var{determine-size-and-set-it})
6025 (@var{if-there-is-an-argument}
6026 @var{figure-out-where-to-go}
6033 The function is similar to the @code{simplified-beginning-of-buffer}
6034 function except that the @code{interactive} expression has @code{"P"}
6035 as an argument and the @code{goto-char} function is followed by an
6036 if-then-else expression that figures out where to put the cursor if
6037 there is an argument that is not a cons cell.
6039 (Since I do not explain a cons cell for many more chapters, please
6040 consider ignoring the function @code{consp}. @xref{List
6041 Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type,
6042 , Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference
6045 The @code{"P"} in the @code{interactive} expression tells Emacs to
6046 pass a prefix argument, if there is one, to the function in raw form.
6047 A prefix argument is made by typing the @key{META} key followed by a
6048 number, or by typing @kbd{C-u} and then a number. (If you don't type
6049 a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase
6050 @code{"p"} in the @code{interactive} expression causes the function to
6051 convert a prefix arg to a number.)
6053 The true-or-false-test of the @code{if} expression looks complex, but
6054 it is not: it checks whether @code{arg} has a value that is not
6055 @code{nil} and whether it is a cons cell. (That is what @code{consp}
6056 does; it checks whether its argument is a cons cell.) If @code{arg}
6057 has a value that is not @code{nil} (and is not a cons cell), which
6058 will be the case if @code{beginning-of-buffer} is called with a
6059 numeric argument, then this true-or-false-test will return true and
6060 the then-part of the @code{if} expression will be evaluated. On the
6061 other hand, if @code{beginning-of-buffer} is not called with an
6062 argument, the value of @code{arg} will be @code{nil} and the else-part
6063 of the @code{if} expression will be evaluated. The else-part is
6064 simply @code{point-min}, and when this is the outcome, the whole
6065 @code{goto-char} expression is @code{(goto-char (point-min))}, which
6066 is how we saw the @code{beginning-of-buffer} function in its
6069 @node beginning-of-buffer opt arg
6070 @subsection @code{beginning-of-buffer} with an Argument
6072 When @code{beginning-of-buffer} is called with an argument, an
6073 expression is evaluated which calculates what value to pass to
6074 @code{goto-char}. This expression is rather complicated at first sight.
6075 It includes an inner @code{if} expression and much arithmetic. It looks
6080 (if (> (buffer-size) 10000)
6081 ;; @r{Avoid overflow for large buffer sizes!}
6082 (* (prefix-numeric-value arg)
6087 size (prefix-numeric-value arg))) 10)))
6092 * Disentangle beginning-of-buffer::
6093 * Large buffer case::
6094 * Small buffer case::
6098 @node Disentangle beginning-of-buffer
6099 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer}
6102 Like other complex-looking expressions, the conditional expression
6103 within @code{beginning-of-buffer} can be disentangled by looking at it
6104 as parts of a template, in this case, the template for an if-then-else
6105 expression. In skeletal form, the expression looks like this:
6109 (if (@var{buffer-is-large}
6110 @var{divide-buffer-size-by-10-and-multiply-by-arg}
6111 @var{else-use-alternate-calculation}
6115 The true-or-false-test of this inner @code{if} expression checks the
6116 size of the buffer. The reason for this is that the old version 18
6117 Emacs used numbers that are no bigger than eight million or so and in
6118 the computation that followed, the programmer feared that Emacs might
6119 try to use over-large numbers if the buffer were large. The term
6120 ``overflow'', mentioned in the comment, means numbers that are over
6121 large. More recent versions of Emacs use larger numbers, but this
6122 code has not been touched, if only because people now look at buffers
6123 that are far, far larger than ever before.
6125 There are two cases: if the buffer is large and if it is not.
6127 @node Large buffer case
6128 @unnumberedsubsubsec What happens in a large buffer
6130 In @code{beginning-of-buffer}, the inner @code{if} expression tests
6131 whether the size of the buffer is greater than 10,000 characters. To do
6132 this, it uses the @code{>} function and the computation of @code{size}
6133 that comes from the let expression.
6135 In the old days, the function @code{buffer-size} was used. Not only
6136 was that function called several times, it gave the size of the whole
6137 buffer, not the accessible part. The computation makes much more
6138 sense when it handles just the accessible part. (@xref{Narrowing &
6139 Widening, , Narrowing and Widening}, for more information on focusing
6140 attention to an accessible part.)
6143 The line looks like this:
6151 When the buffer is large, the then-part of the @code{if} expression is
6152 evaluated. It reads like this (after formatting for easy reading):
6157 (prefix-numeric-value arg)
6163 This expression is a multiplication, with two arguments to the function
6166 The first argument is @code{(prefix-numeric-value arg)}. When
6167 @code{"P"} is used as the argument for @code{interactive}, the value
6168 passed to the function as its argument is passed a @dfn{raw prefix
6169 argument}, and not a number. (It is a number in a list.) To perform
6170 the arithmetic, a conversion is necessary, and
6171 @code{prefix-numeric-value} does the job.
6173 @findex / @r{(division)}
6175 The second argument is @code{(/ size 10)}. This expression divides
6176 the numeric value by ten---the numeric value of the size of the
6177 accessible portion of the buffer. This produces a number that tells
6178 how many characters make up one tenth of the buffer size. (In Lisp,
6179 @code{/} is used for division, just as @code{*} is used for
6183 In the multiplication expression as a whole, this amount is multiplied
6184 by the value of the prefix argument---the multiplication looks like this:
6188 (* @var{numeric-value-of-prefix-arg}
6189 @var{number-of-characters-in-one-tenth-of-the-accessible-buffer})
6194 If, for example, the prefix argument is @samp{7}, the one-tenth value
6195 will be multiplied by 7 to give a position 70% of the way through.
6198 The result of all this is that if the accessible portion of the buffer
6199 is large, the @code{goto-char} expression reads like this:
6203 (goto-char (* (prefix-numeric-value arg)
6208 This puts the cursor where we want it.
6210 @node Small buffer case
6211 @unnumberedsubsubsec What happens in a small buffer
6213 If the buffer contains fewer than 10,000 characters, a slightly
6214 different computation is performed. You might think this is not
6215 necessary, since the first computation could do the job. However, in
6216 a small buffer, the first method may not put the cursor on exactly the
6217 desired line; the second method does a better job.
6220 The code looks like this:
6222 @c Keep this on one line.
6224 (/ (+ 10 (* size (prefix-numeric-value arg))) 10))
6229 This is code in which you figure out what happens by discovering how the
6230 functions are embedded in parentheses. It is easier to read if you
6231 reformat it with each expression indented more deeply than its
6232 enclosing expression:
6240 (prefix-numeric-value arg)))
6247 Looking at parentheses, we see that the innermost operation is
6248 @code{(prefix-numeric-value arg)}, which converts the raw argument to
6249 a number. In the following expression, this number is multiplied by
6250 the size of the accessible portion of the buffer:
6253 (* size (prefix-numeric-value arg))
6257 This multiplication creates a number that may be larger than the size of
6258 the buffer---seven times larger if the argument is 7, for example. Ten
6259 is then added to this number and finally the large number is divided by
6260 ten to provide a value that is one character larger than the percentage
6261 position in the buffer.
6263 The number that results from all this is passed to @code{goto-char} and
6264 the cursor is moved to that point.
6267 @node beginning-of-buffer complete
6268 @subsection The Complete @code{beginning-of-buffer}
6271 Here is the complete text of the @code{beginning-of-buffer} function:
6277 (defun beginning-of-buffer (&optional arg)
6278 "Move point to the beginning of the buffer;
6279 leave mark at previous position.
6280 With \\[universal-argument] prefix,
6281 do not set mark at previous position.
6283 put point N/10 of the way from the beginning.
6285 If the buffer is narrowed,
6286 this command uses the beginning and size
6287 of the accessible part of the buffer.
6291 Don't use this command in Lisp programs!
6292 \(goto-char (point-min)) is faster
6293 and avoids clobbering the mark."
6296 (and transient-mark-mode mark-active)
6300 (let ((size (- (point-max) (point-min))))
6301 (goto-char (if (and arg (not (consp arg)))
6304 ;; Avoid overflow for large buffer sizes!
6305 (* (prefix-numeric-value arg)
6307 (/ (+ 10 (* size (prefix-numeric-value arg)))
6310 (if (and arg (not (consp arg))) (forward-line 1)))
6315 From before GNU Emacs 22
6318 (defun beginning-of-buffer (&optional arg)
6319 "Move point to the beginning of the buffer;
6320 leave mark at previous position.
6321 With arg N, put point N/10 of the way
6322 from the true beginning.
6325 Don't use this in Lisp programs!
6326 \(goto-char (point-min)) is faster
6327 and does not set the mark."
6334 (if (> (buffer-size) 10000)
6335 ;; @r{Avoid overflow for large buffer sizes!}
6336 (* (prefix-numeric-value arg)
6337 (/ (buffer-size) 10))
6340 (/ (+ 10 (* (buffer-size)
6341 (prefix-numeric-value arg)))
6344 (if arg (forward-line 1)))
6350 Except for two small points, the previous discussion shows how this
6351 function works. The first point deals with a detail in the
6352 documentation string, and the second point concerns the last line of
6356 In the documentation string, there is reference to an expression:
6359 \\[universal-argument]
6363 A @samp{\\} is used before the first square bracket of this
6364 expression. This @samp{\\} tells the Lisp interpreter to substitute
6365 whatever key is currently bound to the @samp{[@dots{}]}. In the case
6366 of @code{universal-argument}, that is usually @kbd{C-u}, but it might
6367 be different. (@xref{Documentation Tips, , Tips for Documentation
6368 Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more
6372 Finally, the last line of the @code{beginning-of-buffer} command says
6373 to move point to the beginning of the next line if the command is
6374 invoked with an argument:
6377 (if (and arg (not (consp arg))) (forward-line 1))
6381 This puts the cursor at the beginning of the first line after the
6382 appropriate tenths position in the buffer. This is a flourish that
6383 means that the cursor is always located @emph{at least} the requested
6384 tenths of the way through the buffer, which is a nicety that is,
6385 perhaps, not necessary, but which, if it did not occur, would be sure
6386 to draw complaints. (The @code{(not (consp arg))} portion is so that
6387 if you specify the command with a @kbd{C-u}, but without a number,
6388 that is to say, if the raw prefix argument is simply a cons cell,
6389 the command does not put you at the beginning of the second line.)
6391 @node Second Buffer Related Review
6394 Here is a brief summary of some of the topics covered in this chapter.
6398 Evaluate each argument in sequence, and return the value of the first
6399 argument that is not @code{nil}; if none return a value that is not
6400 @code{nil}, return @code{nil}. In brief, return the first true value
6401 of the arguments; return a true value if one @emph{or} any of the
6405 Evaluate each argument in sequence, and if any are @code{nil}, return
6406 @code{nil}; if none are @code{nil}, return the value of the last
6407 argument. In brief, return a true value only if all the arguments are
6408 true; return a true value if one @emph{and} each of the others is
6412 A keyword used to indicate that an argument to a function definition
6413 is optional; this means that the function can be evaluated without the
6414 argument, if desired.
6416 @item prefix-numeric-value
6417 Convert the raw prefix argument produced by @code{(interactive
6418 "P")} to a numeric value.
6421 Move point forward to the beginning of the next line, or if the argument
6422 is greater than one, forward that many lines. If it can't move as far
6423 forward as it is supposed to, @code{forward-line} goes forward as far as
6424 it can and then returns a count of the number of additional lines it was
6425 supposed to move but couldn't.
6428 Delete the entire contents of the current buffer.
6431 Return @code{t} if its argument is a buffer; otherwise return @code{nil}.
6434 @node optional Exercise
6435 @section @code{optional} Argument Exercise
6437 Write an interactive function with an optional argument that tests
6438 whether its argument, a number, is greater than or equal to, or else,
6439 less than the value of @code{fill-column}, and tells you which, in a
6440 message. However, if you do not pass an argument to the function, use
6441 56 as a default value.
6443 @node Narrowing & Widening
6444 @chapter Narrowing and Widening
6445 @cindex Focusing attention (narrowing)
6449 Narrowing is a feature of Emacs that makes it possible for you to focus
6450 on a specific part of a buffer, and work without accidentally changing
6451 other parts. Narrowing is normally disabled since it can confuse
6455 * Narrowing advantages:: The advantages of narrowing
6456 * save-restriction:: The @code{save-restriction} special form.
6457 * what-line:: The number of the line that point is on.
6462 @node Narrowing advantages
6463 @unnumberedsec The Advantages of Narrowing
6466 With narrowing, the rest of a buffer is made invisible, as if it weren't
6467 there. This is an advantage if, for example, you want to replace a word
6468 in one part of a buffer but not in another: you narrow to the part you want
6469 and the replacement is carried out only in that section, not in the rest
6470 of the buffer. Searches will only work within a narrowed region, not
6471 outside of one, so if you are fixing a part of a document, you can keep
6472 yourself from accidentally finding parts you do not need to fix by
6473 narrowing just to the region you want.
6474 (The key binding for @code{narrow-to-region} is @kbd{C-x n n}.)
6476 However, narrowing does make the rest of the buffer invisible, which
6477 can scare people who inadvertently invoke narrowing and think they
6478 have deleted a part of their file. Moreover, the @code{undo} command
6479 (which is usually bound to @kbd{C-x u}) does not turn off narrowing
6480 (nor should it), so people can become quite desperate if they do not
6481 know that they can return the rest of a buffer to visibility with the
6482 @code{widen} command.
6483 (The key binding for @code{widen} is @kbd{C-x n w}.)
6485 Narrowing is just as useful to the Lisp interpreter as to a human.
6486 Often, an Emacs Lisp function is designed to work on just part of a
6487 buffer; or conversely, an Emacs Lisp function needs to work on all of a
6488 buffer that has been narrowed. The @code{what-line} function, for
6489 example, removes the narrowing from a buffer, if it has any narrowing
6490 and when it has finished its job, restores the narrowing to what it was.
6491 On the other hand, the @code{count-lines} function
6492 uses narrowing to restrict itself to just that portion
6493 of the buffer in which it is interested and then restores the previous
6496 @node save-restriction
6497 @section The @code{save-restriction} Special Form
6498 @findex save-restriction
6500 In Emacs Lisp, you can use the @code{save-restriction} special form to
6501 keep track of whatever narrowing is in effect, if any. When the Lisp
6502 interpreter meets with @code{save-restriction}, it executes the code
6503 in the body of the @code{save-restriction} expression, and then undoes
6504 any changes to narrowing that the code caused. If, for example, the
6505 buffer is narrowed and the code that follows @code{save-restriction}
6506 gets rid of the narrowing, @code{save-restriction} returns the buffer
6507 to its narrowed region afterwards. In the @code{what-line} command,
6508 any narrowing the buffer may have is undone by the @code{widen}
6509 command that immediately follows the @code{save-restriction} command.
6510 Any original narrowing is restored just before the completion of the
6514 The template for a @code{save-restriction} expression is simple:
6524 The body of the @code{save-restriction} is one or more expressions that
6525 will be evaluated in sequence by the Lisp interpreter.
6527 Finally, a point to note: when you use both @code{save-excursion} and
6528 @code{save-restriction}, one right after the other, you should use
6529 @code{save-excursion} outermost. If you write them in reverse order,
6530 you may fail to record narrowing in the buffer to which Emacs switches
6531 after calling @code{save-excursion}. Thus, when written together,
6532 @code{save-excursion} and @code{save-restriction} should be written
6543 In other circumstances, when not written together, the
6544 @code{save-excursion} and @code{save-restriction} special forms must
6545 be written in the order appropriate to the function.
6561 /usr/local/src/emacs/lisp/simple.el
6564 "Print the current buffer line number and narrowed line number of point."
6566 (let ((start (point-min))
6567 (n (line-number-at-pos)))
6569 (message "Line %d" n)
6573 (message "line %d (narrowed line %d)"
6574 (+ n (line-number-at-pos start) -1) n))))))
6576 (defun line-number-at-pos (&optional pos)
6577 "Return (narrowed) buffer line number at position POS.
6578 If POS is nil, use current buffer location.
6579 Counting starts at (point-min), so the value refers
6580 to the contents of the accessible portion of the buffer."
6581 (let ((opoint (or pos (point))) start)
6583 (goto-char (point-min))
6584 (setq start (point))
6587 (1+ (count-lines start (point))))))
6589 (defun count-lines (start end)
6590 "Return number of lines between START and END.
6591 This is usually the number of newlines between them,
6592 but can be one more if START is not equal to END
6593 and the greater of them is not at the start of a line."
6596 (narrow-to-region start end)
6597 (goto-char (point-min))
6598 (if (eq selective-display t)
6601 (while (re-search-forward "[\n\C-m]" nil t 40)
6602 (setq done (+ 40 done)))
6603 (while (re-search-forward "[\n\C-m]" nil t 1)
6604 (setq done (+ 1 done)))
6605 (goto-char (point-max))
6606 (if (and (/= start end)
6610 (- (buffer-size) (forward-line (buffer-size)))))))
6614 @section @code{what-line}
6616 @cindex Widening, example of
6618 The @code{what-line} command tells you the number of the line in which
6619 the cursor is located. The function illustrates the use of the
6620 @code{save-restriction} and @code{save-excursion} commands. Here is the
6621 original text of the function:
6626 "Print the current line number (in the buffer) of point."
6633 (1+ (count-lines 1 (point)))))))
6637 (In recent versions of GNU Emacs, the @code{what-line} function has
6638 been expanded to tell you your line number in a narrowed buffer as
6639 well as your line number in a widened buffer. The recent version is
6640 more complex than the version shown here. If you feel adventurous,
6641 you might want to look at it after figuring out how this version
6642 works. You will probably need to use @kbd{C-h f}
6643 (@code{describe-function}). The newer version uses a conditional to
6644 determine whether the buffer has been narrowed.
6646 (Also, it uses @code{line-number-at-pos}, which among other simple
6647 expressions, such as @code{(goto-char (point-min))}, moves point to
6648 the beginning of the current line with @code{(forward-line 0)} rather
6649 than @code{beginning-of-line}.)
6651 The @code{what-line} function as shown here has a documentation line
6652 and is interactive, as you would expect. The next two lines use the
6653 functions @code{save-restriction} and @code{widen}.
6655 The @code{save-restriction} special form notes whatever narrowing is in
6656 effect, if any, in the current buffer and restores that narrowing after
6657 the code in the body of the @code{save-restriction} has been evaluated.
6659 The @code{save-restriction} special form is followed by @code{widen}.
6660 This function undoes any narrowing the current buffer may have had
6661 when @code{what-line} was called. (The narrowing that was there is
6662 the narrowing that @code{save-restriction} remembers.) This widening
6663 makes it possible for the line counting commands to count from the
6664 beginning of the buffer. Otherwise, they would have been limited to
6665 counting within the accessible region. Any original narrowing is
6666 restored just before the completion of the function by the
6667 @code{save-restriction} special form.
6669 The call to @code{widen} is followed by @code{save-excursion}, which
6670 saves the location of the cursor (i.e., of point), and
6671 restores it after the code in the body of the @code{save-excursion}
6672 uses the @code{beginning-of-line} function to move point.
6674 (Note that the @code{(widen)} expression comes between the
6675 @code{save-restriction} and @code{save-excursion} special forms. When
6676 you write the two @code{save- @dots{}} expressions in sequence, write
6677 @code{save-excursion} outermost.)
6680 The last two lines of the @code{what-line} function are functions to
6681 count the number of lines in the buffer and then print the number in the
6687 (1+ (count-lines 1 (point)))))))
6691 The @code{message} function prints a one-line message at the bottom of
6692 the Emacs screen. The first argument is inside of quotation marks and
6693 is printed as a string of characters. However, it may contain a
6694 @samp{%d} expression to print a following argument. @samp{%d} prints
6695 the argument as a decimal, so the message will say something such as
6699 The number that is printed in place of the @samp{%d} is computed by the
6700 last line of the function:
6703 (1+ (count-lines 1 (point)))
6709 (defun count-lines (start end)
6710 "Return number of lines between START and END.
6711 This is usually the number of newlines between them,
6712 but can be one more if START is not equal to END
6713 and the greater of them is not at the start of a line."
6716 (narrow-to-region start end)
6717 (goto-char (point-min))
6718 (if (eq selective-display t)
6721 (while (re-search-forward "[\n\C-m]" nil t 40)
6722 (setq done (+ 40 done)))
6723 (while (re-search-forward "[\n\C-m]" nil t 1)
6724 (setq done (+ 1 done)))
6725 (goto-char (point-max))
6726 (if (and (/= start end)
6730 (- (buffer-size) (forward-line (buffer-size)))))))
6734 What this does is count the lines from the first position of the
6735 buffer, indicated by the @code{1}, up to @code{(point)}, and then add
6736 one to that number. (The @code{1+} function adds one to its
6737 argument.) We add one to it because line 2 has only one line before
6738 it, and @code{count-lines} counts only the lines @emph{before} the
6741 After @code{count-lines} has done its job, and the message has been
6742 printed in the echo area, the @code{save-excursion} restores point to
6743 its original position; and @code{save-restriction} restores
6744 the original narrowing, if any.
6746 @node narrow Exercise
6747 @section Exercise with Narrowing
6749 Write a function that will display the first 60 characters of the
6750 current buffer, even if you have narrowed the buffer to its latter
6751 half so that the first line is inaccessible. Restore point, mark, and
6752 narrowing. For this exercise, you need to use a whole potpourri of
6753 functions, including @code{save-restriction}, @code{widen},
6754 @code{goto-char}, @code{point-min}, @code{message}, and
6755 @code{buffer-substring}.
6757 @cindex Properties, mention of @code{buffer-substring-no-properties}
6758 (@code{buffer-substring} is a previously unmentioned function you will
6759 have to investigate yourself; or perhaps you will have to use
6760 @code{buffer-substring-no-properties} or
6761 @code{filter-buffer-substring} @dots{}, yet other functions. Text
6762 properties are a feature otherwise not discussed here. @xref{Text
6763 Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference
6766 Additionally, do you really need @code{goto-char} or @code{point-min}?
6767 Or can you write the function without them?
6769 @node car cdr & cons
6770 @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
6771 @findex car, @r{introduced}
6772 @findex cdr, @r{introduced}
6774 In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental
6775 functions. The @code{cons} function is used to construct lists, and
6776 the @code{car} and @code{cdr} functions are used to take them apart.
6778 In the walk through of the @code{copy-region-as-kill} function, we
6779 will see @code{cons} as well as two variants on @code{cdr},
6780 namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.)
6783 * Strange Names:: An historical aside: why the strange names?
6784 * car & cdr:: Functions for extracting part of a list.
6785 * cons:: Constructing a list.
6786 * nthcdr:: Calling @code{cdr} repeatedly.
6788 * setcar:: Changing the first element of a list.
6789 * setcdr:: Changing the rest of a list.
6795 @unnumberedsec Strange Names
6798 The name of the @code{cons} function is not unreasonable: it is an
6799 abbreviation of the word ``construct''. The origins of the names for
6800 @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car}
6801 is an acronym from the phrase ``Contents of the Address part of the
6802 Register''; and @code{cdr} (pronounced ``could-er'') is an acronym from
6803 the phrase ``Contents of the Decrement part of the Register''. These
6804 phrases refer to specific pieces of hardware on the very early
6805 computer on which the original Lisp was developed. Besides being
6806 obsolete, the phrases have been completely irrelevant for more than 25
6807 years to anyone thinking about Lisp. Nonetheless, although a few
6808 brave scholars have begun to use more reasonable names for these
6809 functions, the old terms are still in use. In particular, since the
6810 terms are used in the Emacs Lisp source code, we will use them in this
6814 @section @code{car} and @code{cdr}
6816 The @sc{car} of a list is, quite simply, the first item in the list.
6817 Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is
6821 If you are reading this in Info in GNU Emacs, you can see this by
6822 evaluating the following:
6825 (car '(rose violet daisy buttercup))
6829 After evaluating the expression, @code{rose} will appear in the echo
6832 Clearly, a more reasonable name for the @code{car} function would be
6833 @code{first} and this is often suggested.
6835 @code{car} does not remove the first item from the list; it only reports
6836 what it is. After @code{car} has been applied to a list, the list is
6837 still the same as it was. In the jargon, @code{car} is
6838 ``non-destructive''. This feature turns out to be important.
6840 The @sc{cdr} of a list is the rest of the list, that is, the
6841 @code{cdr} function returns the part of the list that follows the
6842 first item. Thus, while the @sc{car} of the list @code{'(rose violet
6843 daisy buttercup)} is @code{rose}, the rest of the list, the value
6844 returned by the @code{cdr} function, is @code{(violet daisy
6848 You can see this by evaluating the following in the usual way:
6851 (cdr '(rose violet daisy buttercup))
6855 When you evaluate this, @code{(violet daisy buttercup)} will appear in
6858 Like @code{car}, @code{cdr} does not remove any elements from the
6859 list---it just returns a report of what the second and subsequent
6862 Incidentally, in the example, the list of flowers is quoted. If it were
6863 not, the Lisp interpreter would try to evaluate the list by calling
6864 @code{rose} as a function. In this example, we do not want to do that.
6866 Clearly, a more reasonable name for @code{cdr} would be @code{rest}.
6868 (There is a lesson here: when you name new functions, consider very
6869 carefully what you are doing, since you may be stuck with the names
6870 for far longer than you expect. The reason this document perpetuates
6871 these names is that the Emacs Lisp source code uses them, and if I did
6872 not use them, you would have a hard time reading the code; but do,
6873 please, try to avoid using these terms yourself. The people who come
6874 after you will be grateful to you.)
6876 When @code{car} and @code{cdr} are applied to a list made up of symbols,
6877 such as the list @code{(pine fir oak maple)}, the element of the list
6878 returned by the function @code{car} is the symbol @code{pine} without
6879 any parentheses around it. @code{pine} is the first element in the
6880 list. However, the @sc{cdr} of the list is a list itself, @code{(fir
6881 oak maple)}, as you can see by evaluating the following expressions in
6886 (car '(pine fir oak maple))
6888 (cdr '(pine fir oak maple))
6892 On the other hand, in a list of lists, the first element is itself a
6893 list. @code{car} returns this first element as a list. For example,
6894 the following list contains three sub-lists, a list of carnivores, a
6895 list of herbivores and a list of sea mammals:
6899 (car '((lion tiger cheetah)
6900 (gazelle antelope zebra)
6901 (whale dolphin seal)))
6906 In this example, the first element or @sc{car} of the list is the list of
6907 carnivores, @code{(lion tiger cheetah)}, and the rest of the list is
6908 @code{((gazelle antelope zebra) (whale dolphin seal))}.
6912 (cdr '((lion tiger cheetah)
6913 (gazelle antelope zebra)
6914 (whale dolphin seal)))
6918 It is worth saying again that @code{car} and @code{cdr} are
6919 non-destructive---that is, they do not modify or change lists to which
6920 they are applied. This is very important for how they are used.
6922 Also, in the first chapter, in the discussion about atoms, I said that
6923 in Lisp, certain kinds of atom, such as an array, can be separated
6924 into parts; but the mechanism for doing this is different from the
6925 mechanism for splitting a list. As far as Lisp is concerned, the
6926 atoms of a list are unsplittable. (@xref{Lisp Atoms}.) The
6927 @code{car} and @code{cdr} functions are used for splitting lists and
6928 are considered fundamental to Lisp. Since they cannot split or gain
6929 access to the parts of an array, an array is considered an atom.
6930 Conversely, the other fundamental function, @code{cons}, can put
6931 together or construct a list, but not an array. (Arrays are handled
6932 by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU
6933 Emacs Lisp Reference Manual}.)
6936 @section @code{cons}
6937 @findex cons, @r{introduced}
6939 The @code{cons} function constructs lists; it is the inverse of
6940 @code{car} and @code{cdr}. For example, @code{cons} can be used to make
6941 a four element list from the three element list, @code{(fir oak maple)}:
6944 (cons 'pine '(fir oak maple))
6949 After evaluating this list, you will see
6952 (pine fir oak maple)
6956 appear in the echo area. @code{cons} causes the creation of a new
6957 list in which the element is followed by the elements of the original
6960 We often say that @code{cons} puts a new element at the beginning of
6961 a list, or that it attaches or pushes elements onto the list, but this
6962 phrasing can be misleading, since @code{cons} does not change an
6963 existing list, but creates a new one.
6965 Like @code{car} and @code{cdr}, @code{cons} is non-destructive.
6969 * length:: How to find the length of a list.
6974 @unnumberedsubsec Build a list
6977 @code{cons} must have a list to attach to.@footnote{Actually, you can
6978 @code{cons} an element to an atom to produce a dotted pair. Dotted
6979 pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted
6980 Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You
6981 cannot start from absolutely nothing. If you are building a list, you
6982 need to provide at least an empty list at the beginning. Here is a
6983 series of @code{cons} expressions that build up a list of flowers. If
6984 you are reading this in Info in GNU Emacs, you can evaluate each of
6985 the expressions in the usual way; the value is printed in this text
6986 after @samp{@result{}}, which you may read as ``evaluates to''.
6990 (cons 'buttercup ())
6991 @result{} (buttercup)
6995 (cons 'daisy '(buttercup))
6996 @result{} (daisy buttercup)
7000 (cons 'violet '(daisy buttercup))
7001 @result{} (violet daisy buttercup)
7005 (cons 'rose '(violet daisy buttercup))
7006 @result{} (rose violet daisy buttercup)
7011 In the first example, the empty list is shown as @code{()} and a list
7012 made up of @code{buttercup} followed by the empty list is constructed.
7013 As you can see, the empty list is not shown in the list that was
7014 constructed. All that you see is @code{(buttercup)}. The empty list is
7015 not counted as an element of a list because there is nothing in an empty
7016 list. Generally speaking, an empty list is invisible.
7018 The second example, @code{(cons 'daisy '(buttercup))} constructs a new,
7019 two element list by putting @code{daisy} in front of @code{buttercup};
7020 and the third example constructs a three element list by putting
7021 @code{violet} in front of @code{daisy} and @code{buttercup}.
7024 @subsection Find the Length of a List: @code{length}
7027 You can find out how many elements there are in a list by using the Lisp
7028 function @code{length}, as in the following examples:
7032 (length '(buttercup))
7037 (length '(daisy buttercup))
7042 (length (cons 'violet '(daisy buttercup)))
7048 In the third example, the @code{cons} function is used to construct a
7049 three element list which is then passed to the @code{length} function as
7053 We can also use @code{length} to count the number of elements in an
7064 As you would expect, the number of elements in an empty list is zero.
7066 An interesting experiment is to find out what happens if you try to find
7067 the length of no list at all; that is, if you try to call @code{length}
7068 without giving it an argument, not even an empty list:
7076 What you see, if you evaluate this, is the error message
7079 Lisp error: (wrong-number-of-arguments length 0)
7083 This means that the function receives the wrong number of
7084 arguments, zero, when it expects some other number of arguments. In
7085 this case, one argument is expected, the argument being a list whose
7086 length the function is measuring. (Note that @emph{one} list is
7087 @emph{one} argument, even if the list has many elements inside it.)
7089 The part of the error message that says @samp{length} is the name of
7093 @code{length} is still a subroutine, but you need C-h f to discover that.
7095 In an earlier version:
7096 This is written with a special notation, @samp{#<subr},
7097 that indicates that the function @code{length} is one of the primitive
7098 functions written in C rather than in Emacs Lisp. (@samp{subr} is an
7099 abbreviation for ``subroutine''.) @xref{What Is a Function, , What Is a
7100 Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more
7105 @section @code{nthcdr}
7108 The @code{nthcdr} function is associated with the @code{cdr} function.
7109 What it does is take the @sc{cdr} of a list repeatedly.
7111 If you take the @sc{cdr} of the list @code{(pine fir
7112 oak maple)}, you will be returned the list @code{(fir oak maple)}. If you
7113 repeat this on what was returned, you will be returned the list
7114 @code{(oak maple)}. (Of course, repeated @sc{cdr}ing on the original
7115 list will just give you the original @sc{cdr} since the function does
7116 not change the list. You need to evaluate the @sc{cdr} of the
7117 @sc{cdr} and so on.) If you continue this, eventually you will be
7118 returned an empty list, which in this case, instead of being shown as
7119 @code{()} is shown as @code{nil}.
7122 For review, here is a series of repeated @sc{cdr}s, the text following
7123 the @samp{@result{}} shows what is returned.
7127 (cdr '(pine fir oak maple))
7128 @result{}(fir oak maple)
7132 (cdr '(fir oak maple))
7133 @result{} (oak maple)
7158 You can also do several @sc{cdr}s without printing the values in
7163 (cdr (cdr '(pine fir oak maple)))
7164 @result{} (oak maple)
7169 In this example, the Lisp interpreter evaluates the innermost list first.
7170 The innermost list is quoted, so it just passes the list as it is to the
7171 innermost @code{cdr}. This @code{cdr} passes a list made up of the
7172 second and subsequent elements of the list to the outermost @code{cdr},
7173 which produces a list composed of the third and subsequent elements of
7174 the original list. In this example, the @code{cdr} function is repeated
7175 and returns a list that consists of the original list without its
7178 The @code{nthcdr} function does the same as repeating the call to
7179 @code{cdr}. In the following example, the argument 2 is passed to the
7180 function @code{nthcdr}, along with the list, and the value returned is
7181 the list without its first two items, which is exactly the same
7182 as repeating @code{cdr} twice on the list:
7186 (nthcdr 2 '(pine fir oak maple))
7187 @result{} (oak maple)
7192 Using the original four element list, we can see what happens when
7193 various numeric arguments are passed to @code{nthcdr}, including 0, 1,
7198 ;; @r{Leave the list as it was.}
7199 (nthcdr 0 '(pine fir oak maple))
7200 @result{} (pine fir oak maple)
7204 ;; @r{Return a copy without the first element.}
7205 (nthcdr 1 '(pine fir oak maple))
7206 @result{} (fir oak maple)
7210 ;; @r{Return a copy of the list without three elements.}
7211 (nthcdr 3 '(pine fir oak maple))
7216 ;; @r{Return a copy lacking all four elements.}
7217 (nthcdr 4 '(pine fir oak maple))
7222 ;; @r{Return a copy lacking all elements.}
7223 (nthcdr 5 '(pine fir oak maple))
7232 The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly.
7233 The @code{nth} function takes the @sc{car} of the result returned by
7234 @code{nthcdr}. It returns the Nth element of the list.
7237 Thus, if it were not defined in C for speed, the definition of
7238 @code{nth} would be:
7243 "Returns the Nth element of LIST.
7244 N counts from zero. If LIST is not that long, nil is returned."
7245 (car (nthcdr n list)))
7250 (Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el},
7251 but its definition was redone in C in the 1980s.)
7253 The @code{nth} function returns a single element of a list.
7254 This can be very convenient.
7256 Note that the elements are numbered from zero, not one. That is to
7257 say, the first element of a list, its @sc{car} is the zeroth element.
7258 This zero-based counting often bothers people who
7259 are accustomed to the first element in a list being number one, which
7267 (nth 0 '("one" "two" "three"))
7270 (nth 1 '("one" "two" "three"))
7275 It is worth mentioning that @code{nth}, like @code{nthcdr} and
7276 @code{cdr}, does not change the original list---the function is
7277 non-destructive. This is in sharp contrast to the @code{setcar} and
7278 @code{setcdr} functions.
7281 @section @code{setcar}
7284 As you might guess from their names, the @code{setcar} and @code{setcdr}
7285 functions set the @sc{car} or the @sc{cdr} of a list to a new value.
7286 They actually change the original list, unlike @code{car} and @code{cdr}
7287 which leave the original list as it was. One way to find out how this
7288 works is to experiment. We will start with the @code{setcar} function.
7291 First, we can make a list and then set the value of a variable to the
7292 list, using the @code{setq} function. Here is a list of animals:
7295 (setq animals '(antelope giraffe lion tiger))
7299 If you are reading this in Info inside of GNU Emacs, you can evaluate
7300 this expression in the usual fashion, by positioning the cursor after
7301 the expression and typing @kbd{C-x C-e}. (I'm doing this right here
7302 as I write this. This is one of the advantages of having the
7303 interpreter built into the computing environment. Incidentally, when
7304 there is nothing on the line after the final parentheses, such as a
7305 comment, point can be on the next line. Thus, if your cursor is in
7306 the first column of the next line, you do not need to move it.
7307 Indeed, Emacs permits any amount of white space after the final
7311 When we evaluate the variable @code{animals}, we see that it is bound to
7312 the list @code{(antelope giraffe lion tiger)}:
7317 @result{} (antelope giraffe lion tiger)
7322 Put another way, the variable @code{animals} points to the list
7323 @code{(antelope giraffe lion tiger)}.
7325 Next, evaluate the function @code{setcar} while passing it two
7326 arguments, the variable @code{animals} and the quoted symbol
7327 @code{hippopotamus}; this is done by writing the three element list
7328 @code{(setcar animals 'hippopotamus)} and then evaluating it in the
7332 (setcar animals 'hippopotamus)
7337 After evaluating this expression, evaluate the variable @code{animals}
7338 again. You will see that the list of animals has changed:
7343 @result{} (hippopotamus giraffe lion tiger)
7348 The first element on the list, @code{antelope} is replaced by
7349 @code{hippopotamus}.
7351 So we can see that @code{setcar} did not add a new element to the list
7352 as @code{cons} would have; it replaced @code{antelope} with
7353 @code{hippopotamus}; it @emph{changed} the list.
7356 @section @code{setcdr}
7359 The @code{setcdr} function is similar to the @code{setcar} function,
7360 except that the function replaces the second and subsequent elements of
7361 a list rather than the first element.
7363 (To see how to change the last element of a list, look ahead to
7364 @ref{kill-new function, , The @code{kill-new} function}, which uses
7365 the @code{nthcdr} and @code{setcdr} functions.)
7368 To see how this works, set the value of the variable to a list of
7369 domesticated animals by evaluating the following expression:
7372 (setq domesticated-animals '(horse cow sheep goat))
7377 If you now evaluate the list, you will be returned the list
7378 @code{(horse cow sheep goat)}:
7382 domesticated-animals
7383 @result{} (horse cow sheep goat)
7388 Next, evaluate @code{setcdr} with two arguments, the name of the
7389 variable which has a list as its value, and the list to which the
7390 @sc{cdr} of the first list will be set;
7393 (setcdr domesticated-animals '(cat dog))
7397 If you evaluate this expression, the list @code{(cat dog)} will appear
7398 in the echo area. This is the value returned by the function. The
7399 result we are interested in is the side effect, which we can see by
7400 evaluating the variable @code{domesticated-animals}:
7404 domesticated-animals
7405 @result{} (horse cat dog)
7410 Indeed, the list is changed from @code{(horse cow sheep goat)} to
7411 @code{(horse cat dog)}. The @sc{cdr} of the list is changed from
7412 @code{(cow sheep goat)} to @code{(cat dog)}.
7417 Construct a list of four birds by evaluating several expressions with
7418 @code{cons}. Find out what happens when you @code{cons} a list onto
7419 itself. Replace the first element of the list of four birds with a
7420 fish. Replace the rest of that list with a list of other fish.
7422 @node Cutting & Storing Text
7423 @chapter Cutting and Storing Text
7424 @cindex Cutting and storing text
7425 @cindex Storing and cutting text
7426 @cindex Killing text
7427 @cindex Clipping text
7428 @cindex Erasing text
7429 @cindex Deleting text
7431 Whenever you cut or clip text out of a buffer with a @dfn{kill} command in
7432 GNU Emacs, it is stored in a list and you can bring it back with a
7435 (The use of the word ``kill'' in Emacs for processes which specifically
7436 @emph{do not} destroy the values of the entities is an unfortunate
7437 historical accident. A much more appropriate word would be ``clip'' since
7438 that is what the kill commands do; they clip text out of a buffer and
7439 put it into storage from which it can be brought back. I have often
7440 been tempted to replace globally all occurrences of ``kill'' in the Emacs
7441 sources with ``clip'' and all occurrences of ``killed'' with ``clipped''.)
7444 * Storing Text:: Text is stored in a list.
7445 * zap-to-char:: Cutting out text up to a character.
7446 * kill-region:: Cutting text out of a region.
7447 * copy-region-as-kill:: A definition for copying text.
7448 * Digression into C:: Minor note on C programming language macros.
7449 * defvar:: How to give a variable an initial value.
7450 * cons & search-fwd Review::
7451 * search Exercises::
7456 @unnumberedsec Storing Text in a List
7459 When text is cut out of a buffer, it is stored on a list. Successive
7460 pieces of text are stored on the list successively, so the list might
7464 ("a piece of text" "previous piece")
7469 The function @code{cons} can be used to create a new list from a piece
7470 of text (an ``atom'', to use the jargon) and an existing list, like
7475 (cons "another piece"
7476 '("a piece of text" "previous piece"))
7482 If you evaluate this expression, a list of three elements will appear in
7486 ("another piece" "a piece of text" "previous piece")
7489 With the @code{car} and @code{nthcdr} functions, you can retrieve
7490 whichever piece of text you want. For example, in the following code,
7491 @code{nthcdr 1 @dots{}} returns the list with the first item removed;
7492 and the @code{car} returns the first element of that remainder---the
7493 second element of the original list:
7497 (car (nthcdr 1 '("another piece"
7500 @result{} "a piece of text"
7504 The actual functions in Emacs are more complex than this, of course.
7505 The code for cutting and retrieving text has to be written so that
7506 Emacs can figure out which element in the list you want---the first,
7507 second, third, or whatever. In addition, when you get to the end of
7508 the list, Emacs should give you the first element of the list, rather
7509 than nothing at all.
7511 The list that holds the pieces of text is called the @dfn{kill ring}.
7512 This chapter leads up to a description of the kill ring and how it is
7513 used by first tracing how the @code{zap-to-char} function works. This
7514 function calls a function that invokes a function that
7515 manipulates the kill ring. Thus, before reaching the mountains, we
7516 climb the foothills.
7518 A subsequent chapter describes how text that is cut from the buffer is
7519 retrieved. @xref{Yanking, , Yanking Text Back}.
7522 @section @code{zap-to-char}
7525 Let us look at the interactive @code{zap-to-char} function.
7528 * Complete zap-to-char:: The complete implementation.
7529 * zap-to-char interactive:: A three part interactive expression.
7530 * zap-to-char body:: A short overview.
7531 * search-forward:: How to search for a string.
7532 * progn:: The @code{progn} special form.
7533 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
7537 @node Complete zap-to-char
7538 @unnumberedsubsec The Complete @code{zap-to-char} Implementation
7541 The @code{zap-to-char} function removes the text in the region between
7542 the location of the cursor (i.e., of point) up to and including the
7543 next occurrence of a specified character. The text that
7544 @code{zap-to-char} removes is put in the kill ring; and it can be
7545 retrieved from the kill ring by typing @kbd{C-y} (@code{yank}). If
7546 the command is given an argument, it removes text through that number
7547 of occurrences. Thus, if the cursor were at the beginning of this
7548 sentence and the character were @samp{s}, @samp{Thus} would be
7549 removed. If the argument were two, @samp{Thus, if the curs} would be
7550 removed, up to and including the @samp{s} in @samp{cursor}.
7552 If the specified character is not found, @code{zap-to-char} will say
7553 ``Search failed'', tell you the character you typed, and not remove
7556 In order to determine how much text to remove, @code{zap-to-char} uses
7557 a search function. Searches are used extensively in code that
7558 manipulates text, and we will focus attention on them as well as on the
7562 @c GNU Emacs version 19
7563 (defun zap-to-char (arg char) ; version 19 implementation
7564 "Kill up to and including ARG'th occurrence of CHAR.
7565 Goes backward if ARG is negative; error if CHAR not found."
7566 (interactive "*p\ncZap to char: ")
7567 (kill-region (point)
7570 (char-to-string char) nil nil arg)
7575 Here is the complete text of the version 22 implementation of the function:
7580 (defun zap-to-char (arg char)
7581 "Kill up to and including ARG'th occurrence of CHAR.
7582 Case is ignored if `case-fold-search' is non-nil in the current buffer.
7583 Goes backward if ARG is negative; error if CHAR not found."
7584 (interactive "p\ncZap to char: ")
7585 (if (char-table-p translation-table-for-input)
7586 (setq char (or (aref translation-table-for-input char) char)))
7587 (kill-region (point) (progn
7588 (search-forward (char-to-string char)
7594 The documentation is thorough. You do need to know the jargon meaning
7595 of the word ``kill''.
7597 @cindex curved quotes
7598 @cindex curly quotes
7599 The version 22 documentation string for @code{zap-to-char} uses ASCII
7600 grave accent and apostrophe to quote a symbol, so it appears as
7601 @t{`case-fold-search'}. This quoting style was inspired by 1970s-era
7602 displays in which grave accent and apostrophe were often mirror images
7603 suitable for use as quotes. On most modern displays this is no longer
7604 true, and when these two ASCII characters appear in documentation
7605 strings or diagnostic message formats, Emacs typically transliterates
7606 them to @dfn{curved quotes} (left and right single quotation marks),
7607 so that the abovequoted symbol appears
7608 as @t{‘case-fold-search’}. Source-code strings can also simply use
7609 curved quotes directly.
7611 @node zap-to-char interactive
7612 @subsection The @code{interactive} Expression
7615 The interactive expression in the @code{zap-to-char} command looks like
7619 (interactive "p\ncZap to char: ")
7622 The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies
7623 two different things. First, and most simply, is the @samp{p}.
7624 This part is separated from the next part by a newline, @samp{\n}.
7625 The @samp{p} means that the first argument to the function will be
7626 passed the value of a @dfn{processed prefix}. The prefix argument is
7627 passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If
7628 the function is called interactively without a prefix, 1 is passed to
7631 The second part of @code{"p\ncZap to char:@: "} is
7632 @samp{cZap to char:@: }. In this part, the lower case @samp{c}
7633 indicates that @code{interactive} expects a prompt and that the
7634 argument will be a character. The prompt follows the @samp{c} and is
7635 the string @samp{Zap to char:@: } (with a space after the colon to
7638 What all this does is prepare the arguments to @code{zap-to-char} so they
7639 are of the right type, and give the user a prompt.
7641 In a read-only buffer, the @code{zap-to-char} function copies the text
7642 to the kill ring, but does not remove it. The echo area displays a
7643 message saying that the buffer is read-only. Also, the terminal may
7644 beep or blink at you.
7646 @node zap-to-char body
7647 @subsection The Body of @code{zap-to-char}
7649 The body of the @code{zap-to-char} function contains the code that
7650 kills (that is, removes) the text in the region from the current
7651 position of the cursor up to and including the specified character.
7653 The first part of the code looks like this:
7656 (if (char-table-p translation-table-for-input)
7657 (setq char (or (aref translation-table-for-input char) char)))
7658 (kill-region (point) (progn
7659 (search-forward (char-to-string char) nil nil arg)
7664 @code{char-table-p} is an hitherto unseen function. It determines
7665 whether its argument is a character table. When it is, it sets the
7666 character passed to @code{zap-to-char} to one of them, if that
7667 character exists, or to the character itself. (This becomes important
7668 for certain characters in non-European languages. The @code{aref}
7669 function extracts an element from an array. It is an array-specific
7670 function that is not described in this document. @xref{Arrays, ,
7671 Arrays, elisp, The GNU Emacs Lisp Reference Manual}.)
7674 @code{(point)} is the current position of the cursor.
7676 The next part of the code is an expression using @code{progn}. The body
7677 of the @code{progn} consists of calls to @code{search-forward} and
7680 It is easier to understand how @code{progn} works after learning about
7681 @code{search-forward}, so we will look at @code{search-forward} and
7682 then at @code{progn}.
7684 @node search-forward
7685 @subsection The @code{search-forward} Function
7686 @findex search-forward
7688 The @code{search-forward} function is used to locate the
7689 zapped-for-character in @code{zap-to-char}. If the search is
7690 successful, @code{search-forward} leaves point immediately after the
7691 last character in the target string. (In @code{zap-to-char}, the
7692 target string is just one character long. @code{zap-to-char} uses the
7693 function @code{char-to-string} to ensure that the computer treats that
7694 character as a string.) If the search is backwards,
7695 @code{search-forward} leaves point just before the first character in
7696 the target. Also, @code{search-forward} returns @code{t} for true.
7697 (Moving point is therefore a side effect.)
7700 In @code{zap-to-char}, the @code{search-forward} function looks like this:
7703 (search-forward (char-to-string char) nil nil arg)
7706 The @code{search-forward} function takes four arguments:
7710 The first argument is the target, what is searched for. This must be a
7711 string, such as @samp{"z"}.
7713 As it happens, the argument passed to @code{zap-to-char} is a single
7714 character. Because of the way computers are built, the Lisp
7715 interpreter may treat a single character as being different from a
7716 string of characters. Inside the computer, a single character has a
7717 different electronic format than a string of one character. (A single
7718 character can often be recorded in the computer using exactly one
7719 byte; but a string may be longer, and the computer needs to be ready
7720 for this.) Since the @code{search-forward} function searches for a
7721 string, the character that the @code{zap-to-char} function receives as
7722 its argument must be converted inside the computer from one format to
7723 the other; otherwise the @code{search-forward} function will fail.
7724 The @code{char-to-string} function is used to make this conversion.
7727 The second argument bounds the search; it is specified as a position in
7728 the buffer. In this case, the search can go to the end of the buffer,
7729 so no bound is set and the second argument is @code{nil}.
7732 The third argument tells the function what it should do if the search
7733 fails---it can signal an error (and print a message) or it can return
7734 @code{nil}. A @code{nil} as the third argument causes the function to
7735 signal an error when the search fails.
7738 The fourth argument to @code{search-forward} is the repeat count---how
7739 many occurrences of the string to look for. This argument is optional
7740 and if the function is called without a repeat count, this argument is
7741 passed the value 1. If this argument is negative, the search goes
7746 In template form, a @code{search-forward} expression looks like this:
7750 (search-forward "@var{target-string}"
7751 @var{limit-of-search}
7752 @var{what-to-do-if-search-fails}
7757 We will look at @code{progn} next.
7760 @subsection The @code{progn} Special Form
7763 @code{progn} is a special form that causes each of its arguments to be
7764 evaluated in sequence and then returns the value of the last one. The
7765 preceding expressions are evaluated only for the side effects they
7766 perform. The values produced by them are discarded.
7769 The template for a @code{progn} expression is very simple:
7778 In @code{zap-to-char}, the @code{progn} expression has to do two things:
7779 put point in exactly the right position; and return the location of
7780 point so that @code{kill-region} will know how far to kill to.
7782 The first argument to the @code{progn} is @code{search-forward}. When
7783 @code{search-forward} finds the string, the function leaves point
7784 immediately after the last character in the target string. (In this
7785 case the target string is just one character long.) If the search is
7786 backwards, @code{search-forward} leaves point just before the first
7787 character in the target. The movement of point is a side effect.
7789 The second and last argument to @code{progn} is the expression
7790 @code{(point)}. This expression returns the value of point, which in
7791 this case will be the location to which it has been moved by
7792 @code{search-forward}. (In the source, a line that tells the function
7793 to go to the previous character, if it is going forward, was commented
7794 out in 1999; I don't remember whether that feature or mis-feature was
7795 ever a part of the distributed source.) The value of @code{point} is
7796 returned by the @code{progn} expression and is passed to
7797 @code{kill-region} as @code{kill-region}'s second argument.
7799 @node Summing up zap-to-char
7800 @subsection Summing up @code{zap-to-char}
7802 Now that we have seen how @code{search-forward} and @code{progn} work,
7803 we can see how the @code{zap-to-char} function works as a whole.
7805 The first argument to @code{kill-region} is the position of the cursor
7806 when the @code{zap-to-char} command is given---the value of point at
7807 that time. Within the @code{progn}, the search function then moves
7808 point to just after the zapped-to-character and @code{point} returns the
7809 value of this location. The @code{kill-region} function puts together
7810 these two values of point, the first one as the beginning of the region
7811 and the second one as the end of the region, and removes the region.
7813 The @code{progn} special form is necessary because the
7814 @code{kill-region} command takes two arguments; and it would fail if
7815 @code{search-forward} and @code{point} expressions were written in
7816 sequence as two additional arguments. The @code{progn} expression is
7817 a single argument to @code{kill-region} and returns the one value that
7818 @code{kill-region} needs for its second argument.
7821 @section @code{kill-region}
7824 The @code{zap-to-char} function uses the @code{kill-region} function.
7825 This function clips text from a region and copies that text to
7826 the kill ring, from which it may be retrieved.
7831 (defun kill-region (beg end &optional yank-handler)
7832 "Kill (\"cut\") text between point and mark.
7833 This deletes the text from the buffer and saves it in the kill ring.
7834 The command \\[yank] can retrieve it from there.
7835 \(If you want to kill and then yank immediately, use \\[kill-ring-save].)
7837 If you want to append the killed region to the last killed text,
7838 use \\[append-next-kill] before \\[kill-region].
7840 If the buffer is read-only, Emacs will beep and refrain from deleting
7841 the text, but put the text in the kill ring anyway. This means that
7842 you can use the killing commands to copy text from a read-only buffer.
7844 This is the primitive for programs to kill text (as opposed to deleting it).
7845 Supply two arguments, character positions indicating the stretch of text
7847 Any command that calls this function is a \"kill command\".
7848 If the previous command was also a kill command,
7849 the text killed this time appends to the text killed last time
7850 to make one entry in the kill ring.
7852 In Lisp code, optional third arg YANK-HANDLER, if non-nil,
7853 specifies the yank-handler text property to be set on the killed
7854 text. See `insert-for-yank'."
7855 ;; Pass point first, then mark, because the order matters
7856 ;; when calling kill-append.
7857 (interactive (list (point) (mark)))
7858 (unless (and beg end)
7859 (error "The mark is not set now, so there is no region"))
7861 (let ((string (filter-buffer-substring beg end t)))
7862 (when string ;STRING is nil if BEG = END
7863 ;; Add that string to the kill ring, one way or another.
7864 (if (eq last-command 'kill-region)
7865 (kill-append string (< end beg) yank-handler)
7866 (kill-new string nil yank-handler)))
7867 (when (or string (eq last-command 'kill-region))
7868 (setq this-command 'kill-region))
7870 ((buffer-read-only text-read-only)
7871 ;; The code above failed because the buffer, or some of the characters
7872 ;; in the region, are read-only.
7873 ;; We should beep, in case the user just isn't aware of this.
7874 ;; However, there's no harm in putting
7875 ;; the region's text in the kill ring, anyway.
7876 (copy-region-as-kill beg end)
7877 ;; Set this-command now, so it will be set even if we get an error.
7878 (setq this-command 'kill-region)
7879 ;; This should barf, if appropriate, and give us the correct error.
7880 (if kill-read-only-ok
7881 (progn (message "Read only text copied to kill ring") nil)
7882 ;; Signal an error if the buffer is read-only.
7883 (barf-if-buffer-read-only)
7884 ;; If the buffer isn't read-only, the text is.
7885 (signal 'text-read-only (list (current-buffer)))))))
7888 The Emacs 22 version of that function uses @code{condition-case} and
7889 @code{copy-region-as-kill}, both of which we will explain.
7890 @code{condition-case} is an important special form.
7892 In essence, the @code{kill-region} function calls
7893 @code{condition-case}, which takes three arguments. In this function,
7894 the first argument does nothing. The second argument contains the
7895 code that does the work when all goes well. The third argument
7896 contains the code that is called in the event of an error.
7899 * Complete kill-region:: The function definition.
7900 * condition-case:: Dealing with a problem.
7905 @node Complete kill-region
7906 @unnumberedsubsec The Complete @code{kill-region} Definition
7910 We will go through the @code{condition-case} code in a moment. First,
7911 let us look at the definition of @code{kill-region}, with comments
7917 (defun kill-region (beg end)
7918 "Kill (\"cut\") text between point and mark.
7919 This deletes the text from the buffer and saves it in the kill ring.
7920 The command \\[yank] can retrieve it from there. @dots{} "
7924 ;; @bullet{} Since order matters, pass point first.
7925 (interactive (list (point) (mark)))
7926 ;; @bullet{} And tell us if we cannot cut the text.
7927 ;; 'unless' is an 'if' without a then-part.
7928 (unless (and beg end)
7929 (error "The mark is not set now, so there is no region"))
7933 ;; @bullet{} 'condition-case' takes three arguments.
7934 ;; If the first argument is nil, as it is here,
7935 ;; information about the error signal is not
7936 ;; stored for use by another function.
7941 ;; @bullet{} The second argument to 'condition-case' tells the
7942 ;; Lisp interpreter what to do when all goes well.
7946 ;; It starts with a 'let' function that extracts the string
7947 ;; and tests whether it exists. If so (that is what the
7948 ;; 'when' checks), it calls an 'if' function that determines
7949 ;; whether the previous command was another call to
7950 ;; 'kill-region'; if it was, then the new text is appended to
7951 ;; the previous text; if not, then a different function,
7952 ;; 'kill-new', is called.
7956 ;; The 'kill-append' function concatenates the new string and
7957 ;; the old. The 'kill-new' function inserts text into a new
7958 ;; item in the kill ring.
7962 ;; 'when' is an 'if' without an else-part. The second 'when'
7963 ;; again checks whether the current string exists; in
7964 ;; addition, it checks whether the previous command was
7965 ;; another call to 'kill-region'. If one or the other
7966 ;; condition is true, then it sets the current command to
7967 ;; be 'kill-region'.
7970 (let ((string (filter-buffer-substring beg end t)))
7971 (when string ;STRING is nil if BEG = END
7972 ;; Add that string to the kill ring, one way or another.
7973 (if (eq last-command 'kill-region)
7976 ;; @minus{} 'yank-handler' is an optional argument to
7977 ;; 'kill-region' that tells the 'kill-append' and
7978 ;; 'kill-new' functions how deal with properties
7979 ;; added to the text, such as 'bold' or 'italics'.
7980 (kill-append string (< end beg) yank-handler)
7981 (kill-new string nil yank-handler)))
7982 (when (or string (eq last-command 'kill-region))
7983 (setq this-command 'kill-region))
7988 ;; @bullet{} The third argument to 'condition-case' tells the interpreter
7989 ;; what to do with an error.
7992 ;; The third argument has a conditions part and a body part.
7993 ;; If the conditions are met (in this case,
7994 ;; if text or buffer are read-only)
7995 ;; then the body is executed.
7998 ;; The first part of the third argument is the following:
7999 ((buffer-read-only text-read-only) ;; the if-part
8000 ;; @dots{} the then-part
8001 (copy-region-as-kill beg end)
8004 ;; Next, also as part of the then-part, set this-command, so
8005 ;; it will be set in an error
8006 (setq this-command 'kill-region)
8007 ;; Finally, in the then-part, send a message if you may copy
8008 ;; the text to the kill ring without signaling an error, but
8009 ;; don't if you may not.
8012 (if kill-read-only-ok
8013 (progn (message "Read only text copied to kill ring") nil)
8014 (barf-if-buffer-read-only)
8015 ;; If the buffer isn't read-only, the text is.
8016 (signal 'text-read-only (list (current-buffer)))))
8024 (defun kill-region (beg end)
8025 "Kill between point and mark.
8026 The text is deleted but saved in the kill ring."
8031 ;; 1. 'condition-case' takes three arguments.
8032 ;; If the first argument is nil, as it is here,
8033 ;; information about the error signal is not
8034 ;; stored for use by another function.
8039 ;; 2. The second argument to 'condition-case'
8040 ;; tells the Lisp interpreter what to do when all goes well.
8044 ;; The 'delete-and-extract-region' function usually does the
8045 ;; work. If the beginning and ending of the region are both
8046 ;; the same, then the variable 'string' will be empty, or nil
8047 (let ((string (delete-and-extract-region beg end)))
8051 ;; 'when' is an 'if' clause that cannot take an 'else-part'.
8052 ;; Emacs normally sets the value of 'last-command' to the
8053 ;; previous command.
8056 ;; 'kill-append' concatenates the new string and the old.
8057 ;; 'kill-new' inserts text into a new item in the kill ring.
8059 (if (eq last-command 'kill-region)
8060 ;; if true, prepend string
8061 (kill-append string (< end beg))
8063 (setq this-command 'kill-region))
8067 ;; 3. The third argument to 'condition-case' tells the interpreter
8068 ;; what to do with an error.
8071 ;; The third argument has a conditions part and a body part.
8072 ;; If the conditions are met (in this case,
8073 ;; if text or buffer are read-only)
8074 ;; then the body is executed.
8077 ((buffer-read-only text-read-only) ;; this is the if-part
8079 (copy-region-as-kill beg end)
8082 (if kill-read-only-ok ;; usually this variable is nil
8083 (message "Read only text copied to kill ring")
8084 ;; or else, signal an error if the buffer is read-only;
8085 (barf-if-buffer-read-only)
8086 ;; and, in any case, signal that the text is read-only.
8087 (signal 'text-read-only (list (current-buffer)))))))
8092 @node condition-case
8093 @subsection @code{condition-case}
8094 @findex condition-case
8096 As we have seen earlier (@pxref{Making Errors, , Generate an Error
8097 Message}), when the Emacs Lisp interpreter has trouble evaluating an
8098 expression, it provides you with help; in the jargon, this is called
8099 ``signaling an error''. Usually, the computer stops the program and
8100 shows you a message.
8102 However, some programs undertake complicated actions. They should not
8103 simply stop on an error. In the @code{kill-region} function, the most
8104 likely error is that you will try to kill text that is read-only and
8105 cannot be removed. So the @code{kill-region} function contains code
8106 to handle this circumstance. This code, which makes up the body of
8107 the @code{kill-region} function, is inside of a @code{condition-case}
8111 The template for @code{condition-case} looks like this:
8118 @var{error-handler}@dots{})
8122 The second argument, @var{bodyform}, is straightforward. The
8123 @code{condition-case} special form causes the Lisp interpreter to
8124 evaluate the code in @var{bodyform}. If no error occurs, the special
8125 form returns the code's value and produces the side-effects, if any.
8127 In short, the @var{bodyform} part of a @code{condition-case}
8128 expression determines what should happen when everything works
8131 However, if an error occurs, among its other actions, the function
8132 generating the error signal will define one or more error condition
8135 An error handler is the third argument to @code{condition-case}.
8136 An error handler has two parts, a @var{condition-name} and a
8137 @var{body}. If the @var{condition-name} part of an error handler
8138 matches a condition name generated by an error, then the @var{body}
8139 part of the error handler is run.
8141 As you will expect, the @var{condition-name} part of an error handler
8142 may be either a single condition name or a list of condition names.
8144 Also, a complete @code{condition-case} expression may contain more
8145 than one error handler. When an error occurs, the first applicable
8148 Lastly, the first argument to the @code{condition-case} expression,
8149 the @var{var} argument, is sometimes bound to a variable that
8150 contains information about the error. However, if that argument is
8151 nil, as is the case in @code{kill-region}, that information is
8155 In brief, in the @code{kill-region} function, the code
8156 @code{condition-case} works like this:
8160 @var{If no errors}, @var{run only this code}
8161 @var{but}, @var{if errors}, @var{run this other code}.
8168 copy-region-as-kill is short, 12 lines, and uses
8169 filter-buffer-substring, which is longer, 39 lines
8170 and has delete-and-extract-region in it.
8171 delete-and-extract-region is written in C.
8173 see Initializing a Variable with @code{defvar}
8175 Initializing a Variable with @code{defvar} includes line 8350
8179 @subsection Lisp macro
8183 The part of the @code{condition-case} expression that is evaluated in
8184 the expectation that all goes well has a @code{when}. The code uses
8185 @code{when} to determine whether the @code{string} variable points to
8188 A @code{when} expression is simply a programmers' convenience. It is
8189 an @code{if} without the possibility of an else clause. In your mind,
8190 you can replace @code{when} with @code{if} and understand what goes
8191 on. That is what the Lisp interpreter does.
8193 Technically speaking, @code{when} is a Lisp macro. A Lisp macro
8194 enables you to define new control constructs and other language
8195 features. It tells the interpreter how to compute another Lisp
8196 expression which will in turn compute the value. In this case, the
8197 other expression is an @code{if} expression.
8199 The @code{kill-region} function definition also has an @code{unless}
8200 macro; it is the converse of @code{when}. The @code{unless} macro is
8201 an @code{if} without a then clause
8203 For more about Lisp macros, see @ref{Macros, , Macros, elisp, The GNU
8204 Emacs Lisp Reference Manual}. The C programming language also
8205 provides macros. These are different, but also useful.
8208 We will briefly look at C macros in
8209 @ref{Digression into C}.
8213 Regarding the @code{when} macro, in the @code{condition-case}
8214 expression, when the string has content, then another conditional
8215 expression is executed. This is an @code{if} with both a then-part
8220 (if (eq last-command 'kill-region)
8221 (kill-append string (< end beg) yank-handler)
8222 (kill-new string nil yank-handler))
8226 The then-part is evaluated if the previous command was another call to
8227 @code{kill-region}; if not, the else-part is evaluated.
8229 @code{yank-handler} is an optional argument to @code{kill-region} that
8230 tells the @code{kill-append} and @code{kill-new} functions how deal
8231 with properties added to the text, such as bold or italics.
8233 @code{last-command} is a variable that comes with Emacs that we have
8234 not seen before. Normally, whenever a function is executed, Emacs
8235 sets the value of @code{last-command} to the previous command.
8238 In this segment of the definition, the @code{if} expression checks
8239 whether the previous command was @code{kill-region}. If it was,
8242 (kill-append string (< end beg) yank-handler)
8246 concatenates a copy of the newly clipped text to the just previously
8247 clipped text in the kill ring.
8249 @node copy-region-as-kill
8250 @section @code{copy-region-as-kill}
8251 @findex copy-region-as-kill
8254 The @code{copy-region-as-kill} function copies a region of text from a
8255 buffer and (via either @code{kill-append} or @code{kill-new}) saves it
8256 in the @code{kill-ring}.
8258 If you call @code{copy-region-as-kill} immediately after a
8259 @code{kill-region} command, Emacs appends the newly copied text to the
8260 previously copied text. This means that if you yank back the text, you
8261 get it all, from both this and the previous operation. On the other
8262 hand, if some other command precedes the @code{copy-region-as-kill},
8263 the function copies the text into a separate entry in the kill ring.
8266 * Complete copy-region-as-kill:: The complete function definition.
8267 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
8271 @node Complete copy-region-as-kill
8272 @unnumberedsubsec The complete @code{copy-region-as-kill} function definition
8276 Here is the complete text of the version 22 @code{copy-region-as-kill}
8281 (defun copy-region-as-kill (beg end)
8282 "Save the region as if killed, but don't kill it.
8283 In Transient Mark mode, deactivate the mark.
8284 If `interprogram-cut-function' is non-nil, also save the text for a window
8285 system cut and paste."
8289 (if (eq last-command 'kill-region)
8290 (kill-append (filter-buffer-substring beg end) (< end beg))
8291 (kill-new (filter-buffer-substring beg end)))
8294 (if transient-mark-mode
8295 (setq deactivate-mark t))
8301 As usual, this function can be divided into its component parts:
8305 (defun copy-region-as-kill (@var{argument-list})
8306 "@var{documentation}@dots{}"
8312 The arguments are @code{beg} and @code{end} and the function is
8313 interactive with @code{"r"}, so the two arguments must refer to the
8314 beginning and end of the region. If you have been reading through this
8315 document from the beginning, understanding these parts of a function is
8316 almost becoming routine.
8318 The documentation is somewhat confusing unless you remember that the
8319 word ``kill'' has a meaning different from usual. The Transient Mark
8320 and @code{interprogram-cut-function} comments explain certain
8323 After you once set a mark, a buffer always contains a region. If you
8324 wish, you can use Transient Mark mode to highlight the region
8325 temporarily. (No one wants to highlight the region all the time, so
8326 Transient Mark mode highlights it only at appropriate times. Many
8327 people turn off Transient Mark mode, so the region is never
8330 Also, a windowing system allows you to copy, cut, and paste among
8331 different programs. In the X windowing system, for example, the
8332 @code{interprogram-cut-function} function is @code{x-select-text},
8333 which works with the windowing system's equivalent of the Emacs kill
8336 The body of the @code{copy-region-as-kill} function starts with an
8337 @code{if} clause. What this clause does is distinguish between two
8338 different situations: whether or not this command is executed
8339 immediately after a previous @code{kill-region} command. In the first
8340 case, the new region is appended to the previously copied text.
8341 Otherwise, it is inserted into the beginning of the kill ring as a
8342 separate piece of text from the previous piece.
8344 The last two lines of the function prevent the region from lighting up
8345 if Transient Mark mode is turned on.
8347 The body of @code{copy-region-as-kill} merits discussion in detail.
8349 @node copy-region-as-kill body
8350 @subsection The Body of @code{copy-region-as-kill}
8352 The @code{copy-region-as-kill} function works in much the same way as
8353 the @code{kill-region} function. Both are written so that two or more
8354 kills in a row combine their text into a single entry. If you yank
8355 back the text from the kill ring, you get it all in one piece.
8356 Moreover, kills that kill forward from the current position of the
8357 cursor are added to the end of the previously copied text and commands
8358 that copy text backwards add it to the beginning of the previously
8359 copied text. This way, the words in the text stay in the proper
8362 Like @code{kill-region}, the @code{copy-region-as-kill} function makes
8363 use of the @code{last-command} variable that keeps track of the
8364 previous Emacs command.
8367 * last-command & this-command::
8368 * kill-append function::
8369 * kill-new function::
8373 @node last-command & this-command
8374 @unnumberedsubsubsec @code{last-command} and @code{this-command}
8377 Normally, whenever a function is executed, Emacs sets the value of
8378 @code{this-command} to the function being executed (which in this case
8379 would be @code{copy-region-as-kill}). At the same time, Emacs sets
8380 the value of @code{last-command} to the previous value of
8381 @code{this-command}.
8383 In the first part of the body of the @code{copy-region-as-kill}
8384 function, an @code{if} expression determines whether the value of
8385 @code{last-command} is @code{kill-region}. If so, the then-part of
8386 the @code{if} expression is evaluated; it uses the @code{kill-append}
8387 function to concatenate the text copied at this call to the function
8388 with the text already in the first element (the @sc{car}) of the kill
8389 ring. On the other hand, if the value of @code{last-command} is not
8390 @code{kill-region}, then the @code{copy-region-as-kill} function
8391 attaches a new element to the kill ring using the @code{kill-new}
8395 The @code{if} expression reads as follows; it uses @code{eq}:
8399 (if (eq last-command 'kill-region)
8401 (kill-append (filter-buffer-substring beg end) (< end beg))
8403 (kill-new (filter-buffer-substring beg end)))
8407 @findex filter-buffer-substring
8408 (The @code{filter-buffer-substring} function returns a filtered
8409 substring of the buffer, if any. Optionally---the arguments are not
8410 here, so neither is done---the function may delete the initial text or
8411 return the text without its properties; this function is a replacement
8412 for the older @code{buffer-substring} function, which came before text
8413 properties were implemented.)
8415 @findex eq @r{(example of use)}
8417 The @code{eq} function tests whether its first argument is the same Lisp
8418 object as its second argument. The @code{eq} function is similar to the
8419 @code{equal} function in that it is used to test for equality, but
8420 differs in that it determines whether two representations are actually
8421 the same object inside the computer, but with different names.
8422 @code{equal} determines whether the structure and contents of two
8423 expressions are the same.
8425 If the previous command was @code{kill-region}, then the Emacs Lisp
8426 interpreter calls the @code{kill-append} function
8428 @node kill-append function
8429 @unnumberedsubsubsec The @code{kill-append} function
8433 The @code{kill-append} function looks like this:
8438 (defun kill-append (string before-p &optional yank-handler)
8439 "Append STRING to the end of the latest kill in the kill ring.
8440 If BEFORE-P is non-nil, prepend STRING to the kill.
8442 (let* ((cur (car kill-ring)))
8443 (kill-new (if before-p (concat string cur) (concat cur string))
8444 (or (= (length cur) 0)
8446 (get-text-property 0 'yank-handler cur)))
8453 (defun kill-append (string before-p)
8454 "Append STRING to the end of the latest kill in the kill ring.
8455 If BEFORE-P is non-nil, prepend STRING to the kill.
8456 If `interprogram-cut-function' is set, pass the resulting kill to
8458 (kill-new (if before-p
8459 (concat string (car kill-ring))
8460 (concat (car kill-ring) string))
8465 The @code{kill-append} function is fairly straightforward. It uses
8466 the @code{kill-new} function, which we will discuss in more detail in
8469 (Also, the function provides an optional argument called
8470 @code{yank-handler}; when invoked, this argument tells the function
8471 how to deal with properties added to the text, such as bold or
8474 @c !!! bug in GNU Emacs 22 version of kill-append ?
8475 It has a @code{let*} function to set the value of the first element of
8476 the kill ring to @code{cur}. (I do not know why the function does not
8477 use @code{let} instead; only one value is set in the expression.
8478 Perhaps this is a bug that produces no problems?)
8480 Consider the conditional that is one of the two arguments to
8481 @code{kill-new}. It uses @code{concat} to concatenate the new text to
8482 the @sc{car} of the kill ring. Whether it prepends or appends the
8483 text depends on the results of an @code{if} expression:
8487 (if before-p ; @r{if-part}
8488 (concat string cur) ; @r{then-part}
8489 (concat cur string)) ; @r{else-part}
8494 If the region being killed is before the region that was killed in the
8495 last command, then it should be prepended before the material that was
8496 saved in the previous kill; and conversely, if the killed text follows
8497 what was just killed, it should be appended after the previous text.
8498 The @code{if} expression depends on the predicate @code{before-p} to
8499 decide whether the newly saved text should be put before or after the
8500 previously saved text.
8502 The symbol @code{before-p} is the name of one of the arguments to
8503 @code{kill-append}. When the @code{kill-append} function is
8504 evaluated, it is bound to the value returned by evaluating the actual
8505 argument. In this case, this is the expression @code{(< end beg)}.
8506 This expression does not directly determine whether the killed text in
8507 this command is located before or after the kill text of the last
8508 command; what it does is determine whether the value of the variable
8509 @code{end} is less than the value of the variable @code{beg}. If it
8510 is, it means that the user is most likely heading towards the
8511 beginning of the buffer. Also, the result of evaluating the predicate
8512 expression, @code{(< end beg)}, will be true and the text will be
8513 prepended before the previous text. On the other hand, if the value of
8514 the variable @code{end} is greater than the value of the variable
8515 @code{beg}, the text will be appended after the previous text.
8518 When the newly saved text will be prepended, then the string with the new
8519 text will be concatenated before the old text:
8527 But if the text will be appended, it will be concatenated
8531 (concat cur string))
8534 To understand how this works, we first need to review the
8535 @code{concat} function. The @code{concat} function links together or
8536 unites two strings of text. The result is a string. For example:
8540 (concat "abc" "def")
8546 (car '("first element" "second element")))
8547 @result{} "new first element"
8550 '("first element" "second element")) " modified")
8551 @result{} "first element modified"
8555 We can now make sense of @code{kill-append}: it modifies the contents
8556 of the kill ring. The kill ring is a list, each element of which is
8557 saved text. The @code{kill-append} function uses the @code{kill-new}
8558 function which in turn uses the @code{setcar} function.
8560 @node kill-new function
8561 @unnumberedsubsubsec The @code{kill-new} function
8565 In version 22 the @code{kill-new} function looks like this:
8569 (defun kill-new (string &optional replace yank-handler)
8570 "Make STRING the latest kill in the kill ring.
8571 Set `kill-ring-yank-pointer' to point to it.
8573 If `interprogram-cut-function' is non-nil, apply it to STRING.
8574 Optional second argument REPLACE non-nil means that STRING will replace
8575 the front of the kill ring, rather than being added to the list.
8579 (if (> (length string) 0)
8581 (put-text-property 0 (length string)
8582 'yank-handler yank-handler string))
8584 (signal 'args-out-of-range
8585 (list string "yank-handler specified for empty string"))))
8588 (if (fboundp 'menu-bar-update-yank-menu)
8589 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8592 (if (and replace kill-ring)
8593 (setcar kill-ring string)
8594 (push string kill-ring)
8595 (if (> (length kill-ring) kill-ring-max)
8596 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8599 (setq kill-ring-yank-pointer kill-ring)
8600 (if interprogram-cut-function
8601 (funcall interprogram-cut-function string (not replace))))
8606 (defun kill-new (string &optional replace)
8607 "Make STRING the latest kill in the kill ring.
8608 Set the kill-ring-yank pointer to point to it.
8609 If `interprogram-cut-function' is non-nil, apply it to STRING.
8610 Optional second argument REPLACE non-nil means that STRING will replace
8611 the front of the kill ring, rather than being added to the list."
8612 (and (fboundp 'menu-bar-update-yank-menu)
8613 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8614 (if (and replace kill-ring)
8615 (setcar kill-ring string)
8616 (setq kill-ring (cons string kill-ring))
8617 (if (> (length kill-ring) kill-ring-max)
8618 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8619 (setq kill-ring-yank-pointer kill-ring)
8620 (if interprogram-cut-function
8621 (funcall interprogram-cut-function string (not replace))))
8624 (Notice that the function is not interactive.)
8626 As usual, we can look at this function in parts.
8628 The function definition has an optional @code{yank-handler} argument,
8629 which when invoked tells the function how to deal with properties
8630 added to the text, such as bold or italics. We will skip that.
8633 The first line of the documentation makes sense:
8636 Make STRING the latest kill in the kill ring.
8640 Let's skip over the rest of the documentation for the moment.
8643 Also, let's skip over the initial @code{if} expression and those lines
8644 of code involving @code{menu-bar-update-yank-menu}. We will explain
8648 The critical lines are these:
8652 (if (and replace kill-ring)
8654 (setcar kill-ring string)
8658 (push string kill-ring)
8661 (if (> (length kill-ring) kill-ring-max)
8662 ;; @r{avoid overly long kill ring}
8663 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8666 (setq kill-ring-yank-pointer kill-ring)
8667 (if interprogram-cut-function
8668 (funcall interprogram-cut-function string (not replace))))
8672 The conditional test is @w{@code{(and replace kill-ring)}}.
8673 This will be true when two conditions are met: the kill ring has
8674 something in it, and the @code{replace} variable is true.
8677 When the @code{kill-append} function sets @code{replace} to be true
8678 and when the kill ring has at least one item in it, the @code{setcar}
8679 expression is executed:
8682 (setcar kill-ring string)
8685 The @code{setcar} function actually changes the first element of the
8686 @code{kill-ring} list to the value of @code{string}. It replaces the
8690 On the other hand, if the kill ring is empty, or replace is false, the
8691 else-part of the condition is executed:
8694 (push string kill-ring)
8699 @code{push} puts its first argument onto the second. It is similar to
8703 (setq kill-ring (cons string kill-ring))
8711 (add-to-list kill-ring string)
8715 When it is false, the expression first constructs a new version of the
8716 kill ring by prepending @code{string} to the existing kill ring as a
8717 new element (that is what the @code{push} does). Then it executes a
8718 second @code{if} clause. This second @code{if} clause keeps the kill
8719 ring from growing too long.
8721 Let's look at these two expressions in order.
8723 The @code{push} line of the else-part sets the new value of the kill
8724 ring to what results from adding the string being killed to the old
8727 We can see how this works with an example.
8733 (setq example-list '("here is a clause" "another clause"))
8738 After evaluating this expression with @kbd{C-x C-e}, you can evaluate
8739 @code{example-list} and see what it returns:
8744 @result{} ("here is a clause" "another clause")
8750 Now, we can add a new element on to this list by evaluating the
8751 following expression:
8752 @findex push, @r{example}
8755 (push "a third clause" example-list)
8760 When we evaluate @code{example-list}, we find its value is:
8765 @result{} ("a third clause" "here is a clause" "another clause")
8770 Thus, the third clause is added to the list by @code{push}.
8773 Now for the second part of the @code{if} clause. This expression
8774 keeps the kill ring from growing too long. It looks like this:
8778 (if (> (length kill-ring) kill-ring-max)
8779 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
8783 The code checks whether the length of the kill ring is greater than
8784 the maximum permitted length. This is the value of
8785 @code{kill-ring-max} (which is 60, by default). If the length of the
8786 kill ring is too long, then this code sets the last element of the
8787 kill ring to @code{nil}. It does this by using two functions,
8788 @code{nthcdr} and @code{setcdr}.
8790 We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
8791 It sets the @sc{cdr} of a list, just as @code{setcar} sets the
8792 @sc{car} of a list. In this case, however, @code{setcdr} will not be
8793 setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
8794 function is used to cause it to set the @sc{cdr} of the next to last
8795 element of the kill ring---this means that since the @sc{cdr} of the
8796 next to last element is the last element of the kill ring, it will set
8797 the last element of the kill ring.
8799 @findex nthcdr, @r{example}
8800 The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
8801 list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
8802 @dots{} It does this @var{N} times and returns the results.
8803 (@xref{nthcdr, , @code{nthcdr}}.)
8805 @findex setcdr, @r{example}
8806 Thus, if we had a four element list that was supposed to be three
8807 elements long, we could set the @sc{cdr} of the next to last element
8808 to @code{nil}, and thereby shorten the list. (If you set the last
8809 element to some other value than @code{nil}, which you could do, then
8810 you would not have shortened the list. @xref{setcdr, ,
8813 You can see shortening by evaluating the following three expressions
8814 in turn. First set the value of @code{trees} to @code{(maple oak pine
8815 birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
8816 and then find the value of @code{trees}:
8820 (setq trees '(maple oak pine birch))
8821 @result{} (maple oak pine birch)
8825 (setcdr (nthcdr 2 trees) nil)
8829 @result{} (maple oak pine)
8834 (The value returned by the @code{setcdr} expression is @code{nil} since
8835 that is what the @sc{cdr} is set to.)
8837 To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
8838 @sc{cdr} a number of times that is one less than the maximum permitted
8839 size of the kill ring and @code{setcdr} sets the @sc{cdr} of that
8840 element (which will be the rest of the elements in the kill ring) to
8841 @code{nil}. This prevents the kill ring from growing too long.
8844 The next to last expression in the @code{kill-new} function is
8847 (setq kill-ring-yank-pointer kill-ring)
8850 The @code{kill-ring-yank-pointer} is a global variable that is set to be
8851 the @code{kill-ring}.
8853 Even though the @code{kill-ring-yank-pointer} is called a
8854 @samp{pointer}, it is a variable just like the kill ring. However, the
8855 name has been chosen to help humans understand how the variable is used.
8858 Now, to return to an early expression in the body of the function:
8862 (if (fboundp 'menu-bar-update-yank-menu)
8863 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8868 It starts with an @code{if} expression
8870 In this case, the expression tests first to see whether
8871 @code{menu-bar-update-yank-menu} exists as a function, and if so,
8872 calls it. The @code{fboundp} function returns true if the symbol it
8873 is testing has a function definition that is not void. If the
8874 symbol's function definition were void, we would receive an error
8875 message, as we did when we created errors intentionally (@pxref{Making
8876 Errors, , Generate an Error Message}).
8879 The then-part contains an expression whose first element is the
8880 function @code{and}.
8883 The @code{and} special form evaluates each of its arguments until one
8884 of the arguments returns a value of @code{nil}, in which case the
8885 @code{and} expression returns @code{nil}; however, if none of the
8886 arguments returns a value of @code{nil}, the value resulting from
8887 evaluating the last argument is returned. (Since such a value is not
8888 @code{nil}, it is considered true in Emacs Lisp.) In other words, an
8889 @code{and} expression returns a true value only if all its arguments
8890 are true. (@xref{Second Buffer Related Review}.)
8892 The expression determines whether the second argument to
8893 @code{menu-bar-update-yank-menu} is true or not.
8895 ;; If we're supposed to be extending an existing string, and that
8896 ;; string really is at the front of the menu, then update it in place.
8899 @code{menu-bar-update-yank-menu} is one of the functions that make it
8900 possible to use the ``Select and Paste'' menu in the Edit item of a menu
8901 bar; using a mouse, you can look at the various pieces of text you
8902 have saved and select one piece to paste.
8904 The last expression in the @code{kill-new} function adds the newly
8905 copied string to whatever facility exists for copying and pasting
8906 among different programs running in a windowing system. In the X
8907 Windowing system, for example, the @code{x-select-text} function takes
8908 the string and stores it in memory operated by X@. You can paste the
8909 string in another program, such as an Xterm.
8912 The expression looks like this:
8916 (if interprogram-cut-function
8917 (funcall interprogram-cut-function string (not replace))))
8921 If an @code{interprogram-cut-function} exists, then Emacs executes
8922 @code{funcall}, which in turn calls its first argument as a function
8923 and passes the remaining arguments to it. (Incidentally, as far as I
8924 can see, this @code{if} expression could be replaced by an @code{and}
8925 expression similar to the one in the first part of the function.)
8927 We are not going to discuss windowing systems and other programs
8928 further, but merely note that this is a mechanism that enables GNU
8929 Emacs to work easily and well with other programs.
8931 This code for placing text in the kill ring, either concatenated with
8932 an existing element or as a new element, leads us to the code for
8933 bringing back text that has been cut out of the buffer---the yank
8934 commands. However, before discussing the yank commands, it is better
8935 to learn how lists are implemented in a computer. This will make
8936 clear such mysteries as the use of the term ``pointer''. But before
8937 that, we will digress into C.
8940 @c is this true in Emacs 22? Does not seems to be
8942 (If the @w{@code{(< end beg))}}
8943 expression is true, @code{kill-append} prepends the string to the just
8944 previously clipped text. For a detailed discussion, see
8945 @ref{kill-append function, , The @code{kill-append} function}.)
8947 If you then yank back the text, i.e., paste it, you get both
8948 pieces of text at once. That way, if you delete two words in a row,
8949 and then yank them back, you get both words, in their proper order,
8950 with one yank. (The @w{@code{(< end beg))}} expression makes sure the
8953 On the other hand, if the previous command is not @code{kill-region},
8954 then the @code{kill-new} function is called, which adds the text to
8955 the kill ring as the latest item, and sets the
8956 @code{kill-ring-yank-pointer} variable to point to it.
8960 @c Evidently, changed for Emacs 22. The zap-to-char command does not
8961 @c use the delete-and-extract-region function
8963 2006 Oct 26, the Digression into C is now OK but should come after
8964 copy-region-as-kill and filter-buffer-substring
8968 copy-region-as-kill is short, 12 lines, and uses
8969 filter-buffer-substring, which is longer, 39 lines
8970 and has delete-and-extract-region in it.
8971 delete-and-extract-region is written in C.
8973 see Initializing a Variable with @code{defvar}
8976 @node Digression into C
8977 @section Digression into C
8978 @findex delete-and-extract-region
8979 @cindex C, a digression into
8980 @cindex Digression into C
8982 The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, ,
8983 @code{copy-region-as-kill}}) uses the @code{filter-buffer-substring}
8984 function, which in turn uses the @code{delete-and-extract-region}
8985 function. It removes the contents of a region and you cannot get them
8988 Unlike the other code discussed here, the
8989 @code{delete-and-extract-region} function is not written in Emacs
8990 Lisp; it is written in C and is one of the primitives of the GNU Emacs
8991 system. Since it is very simple, I will digress briefly from Lisp and
8994 @c GNU Emacs 24 in src/editfns.c
8995 @c the DEFUN for delete-and-extract-region
8998 Like many of the other Emacs primitives,
8999 @code{delete-and-extract-region} is written as an instance of a C
9000 macro, a macro being a template for code. The complete macro looks
9005 DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
9006 Sdelete_and_extract_region, 2, 2, 0,
9007 doc: /* Delete the text between START and END and return it. */)
9008 (Lisp_Object start, Lisp_Object end)
9010 validate_region (&start, &end);
9011 if (XINT (start) == XINT (end))
9012 return empty_unibyte_string;
9013 return del_range_1 (XINT (start), XINT (end), 1, 1);
9018 Without going into the details of the macro writing process, let me
9019 point out that this macro starts with the word @code{DEFUN}. The word
9020 @code{DEFUN} was chosen since the code serves the same purpose as
9021 @code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in
9022 @file{emacs/src/lisp.h}.)
9024 The word @code{DEFUN} is followed by seven parts inside of
9029 The first part is the name given to the function in Lisp,
9030 @code{delete-and-extract-region}.
9033 The second part is the name of the function in C,
9034 @code{Fdelete_and_extract_region}. By convention, it starts with
9035 @samp{F}. Since C does not use hyphens in names, underscores are used
9039 The third part is the name for the C constant structure that records
9040 information on this function for internal use. It is the name of the
9041 function in C but begins with an @samp{S} instead of an @samp{F}.
9044 The fourth and fifth parts specify the minimum and maximum number of
9045 arguments the function can have. This function demands exactly 2
9049 The sixth part is nearly like the argument that follows the
9050 @code{interactive} declaration in a function written in Lisp: a letter
9051 followed, perhaps, by a prompt. The only difference from Lisp is
9052 when the macro is called with no arguments. Then you write a @code{0}
9053 (which is a null string), as in this macro.
9055 If you were to specify arguments, you would place them between
9056 quotation marks. The C macro for @code{goto-char} includes
9057 @code{"NGoto char: "} in this position to indicate that the function
9058 expects a raw prefix, in this case, a numerical location in a buffer,
9059 and provides a prompt.
9062 The seventh part is a documentation string, just like the one for a
9063 function written in Emacs Lisp. This is written as a C comment. (When
9064 you build Emacs, the program @command{lib-src/make-docfile} extracts
9065 these comments and uses them to make the documentation.)
9069 In a C macro, the formal parameters come next, with a statement of
9070 what kind of object they are, followed by the body
9071 of the macro. For @code{delete-and-extract-region} the body
9072 consists of the following four lines:
9076 validate_region (&start, &end);
9077 if (XINT (start) == XINT (end))
9078 return empty_unibyte_string;
9079 return del_range_1 (XINT (start), XINT (end), 1, 1);
9083 The @code{validate_region} function checks whether the values
9084 passed as the beginning and end of the region are the proper type and
9085 are within range. If the beginning and end positions are the same,
9086 then return an empty string.
9088 The @code{del_range_1} function actually deletes the text. It is a
9089 complex function we will not look into. It updates the buffer and
9090 does other things. However, it is worth looking at the two arguments
9091 passed to @code{del_range_1}. These are @w{@code{XINT (start)}} and
9092 @w{@code{XINT (end)}}.
9094 As far as the C language is concerned, @code{start} and @code{end} are
9095 two integers that mark the beginning and end of the region to be
9096 deleted@footnote{More precisely, and requiring more expert knowledge
9097 to understand, the two integers are of type @code{Lisp_Object}, which can
9098 also be a C union instead of an integer type.}.
9100 Integer widths depend on the machine, and are typically 32 or 64 bits.
9101 A few of the bits are used to specify the type of information; the
9102 remaining bits are used as content.
9104 @samp{XINT} is a C macro that extracts the relevant number from the
9105 longer collection of bits; the type bits are discarded.
9108 The command in @code{delete-and-extract-region} looks like this:
9111 del_range_1 (XINT (start), XINT (end), 1, 1);
9115 It deletes the region between the beginning position, @code{start},
9116 and the ending position, @code{end}.
9118 From the point of view of the person writing Lisp, Emacs is all very
9119 simple; but hidden underneath is a great deal of complexity to make it
9123 @section Initializing a Variable with @code{defvar}
9125 @cindex Initializing a variable
9126 @cindex Variable initialization
9131 copy-region-as-kill is short, 12 lines, and uses
9132 filter-buffer-substring, which is longer, 39 lines
9133 and has delete-and-extract-region in it.
9134 delete-and-extract-region is written in C.
9136 see Initializing a Variable with @code{defvar}
9140 The @code{copy-region-as-kill} function is written in Emacs Lisp. Two
9141 functions within it, @code{kill-append} and @code{kill-new}, copy a
9142 region in a buffer and save it in a variable called the
9143 @code{kill-ring}. This section describes how the @code{kill-ring}
9144 variable is created and initialized using the @code{defvar} special
9147 (Again we note that the term @code{kill-ring} is a misnomer. The text
9148 that is clipped out of the buffer can be brought back; it is not a ring
9149 of corpses, but a ring of resurrectable text.)
9151 In Emacs Lisp, a variable such as the @code{kill-ring} is created and
9152 given an initial value by using the @code{defvar} special form. The
9153 name comes from ``define variable''.
9155 The @code{defvar} special form is similar to @code{setq} in that it sets
9156 the value of a variable. It is unlike @code{setq} in two ways: first,
9157 it only sets the value of the variable if the variable does not already
9158 have a value. If the variable already has a value, @code{defvar} does
9159 not override the existing value. Second, @code{defvar} has a
9160 documentation string.
9162 (There is a related macro, @code{defcustom}, designed for variables
9163 that people customize. It has more features than @code{defvar}.
9164 (@xref{defcustom, , Setting Variables with @code{defcustom}}.)
9167 * See variable current value::
9168 * defvar and asterisk::
9172 @node See variable current value
9173 @unnumberedsubsec Seeing the Current Value of a Variable
9176 You can see the current value of a variable, any variable, by using
9177 the @code{describe-variable} function, which is usually invoked by
9178 typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring}
9179 (followed by @key{RET}) when prompted, you will see what is in your
9180 current kill ring---this may be quite a lot! Conversely, if you have
9181 been doing nothing this Emacs session except read this document, you
9182 may have nothing in it. Also, you will see the documentation for
9188 List of killed text sequences.
9189 Since the kill ring is supposed to interact nicely with cut-and-paste
9190 facilities offered by window systems, use of this variable should
9193 interact nicely with `interprogram-cut-function' and
9194 `interprogram-paste-function'. The functions `kill-new',
9195 `kill-append', and `current-kill' are supposed to implement this
9196 interaction; you may want to use them instead of manipulating the kill
9202 The kill ring is defined by a @code{defvar} in the following way:
9206 (defvar kill-ring nil
9207 "List of killed text sequences.
9213 In this variable definition, the variable is given an initial value of
9214 @code{nil}, which makes sense, since if you have saved nothing, you want
9215 nothing back if you give a @code{yank} command. The documentation
9216 string is written just like the documentation string of a @code{defun}.
9217 As with the documentation string of the @code{defun}, the first line of
9218 the documentation should be a complete sentence, since some commands,
9219 like @code{apropos}, print only the first line of documentation.
9220 Succeeding lines should not be indented; otherwise they look odd when
9221 you use @kbd{C-h v} (@code{describe-variable}).
9223 @node defvar and asterisk
9224 @subsection @code{defvar} and an asterisk
9225 @findex defvar @r{for a user customizable variable}
9226 @findex defvar @r{with an asterisk}
9228 In the past, Emacs used the @code{defvar} special form both for
9229 internal variables that you would not expect a user to change and for
9230 variables that you do expect a user to change. Although you can still
9231 use @code{defvar} for user customizable variables, please use
9232 @code{defcustom} instead, since it provides a path into
9233 the Customization commands. (@xref{defcustom, , Specifying Variables
9234 using @code{defcustom}}.)
9236 When you specified a variable using the @code{defvar} special form,
9237 you could distinguish a variable that a user might want to change from
9238 others by typing an asterisk, @samp{*}, in the first column of its
9239 documentation string. For example:
9243 (defvar shell-command-default-error-buffer nil
9244 "*Buffer name for `shell-command' @dots{} error output.
9249 @findex set-variable
9251 You could (and still can) use the @code{set-variable} command to
9252 change the value of @code{shell-command-default-error-buffer}
9253 temporarily. However, options set using @code{set-variable} are set
9254 only for the duration of your editing session. The new values are not
9255 saved between sessions. Each time Emacs starts, it reads the original
9256 value, unless you change the value within your @file{.emacs} file,
9257 either by setting it manually or by using @code{customize}.
9258 @xref{Emacs Initialization, , Your @file{.emacs} File}.
9260 For me, the major use of the @code{set-variable} command is to suggest
9261 variables that I might want to set in my @file{.emacs} file. There
9262 are now more than 700 such variables, far too many to remember
9263 readily. Fortunately, you can press @key{TAB} after calling the
9264 @code{M-x set-variable} command to see the list of variables.
9265 (@xref{Examining, , Examining and Setting Variables, emacs,
9266 The GNU Emacs Manual}.)
9269 @node cons & search-fwd Review
9272 Here is a brief summary of some recently introduced functions.
9277 @code{car} returns the first element of a list; @code{cdr} returns the
9278 second and subsequent elements of a list.
9285 (car '(1 2 3 4 5 6 7))
9287 (cdr '(1 2 3 4 5 6 7))
9288 @result{} (2 3 4 5 6 7)
9293 @code{cons} constructs a list by prepending its first argument to its
9307 @code{funcall} evaluates its first argument as a function. It passes
9308 its remaining arguments to its first argument.
9311 Return the result of taking @sc{cdr} @var{n} times on a list.
9319 The ``rest of the rest'', as it were.
9326 (nthcdr 3 '(1 2 3 4 5 6 7))
9333 @code{setcar} changes the first element of a list; @code{setcdr}
9334 changes the second and subsequent elements of a list.
9341 (setq triple '(1 2 3))
9348 (setcdr triple '("foo" "bar"))
9351 @result{} (37 "foo" "bar")
9356 Evaluate each argument in sequence and then return the value of the
9369 @item save-restriction
9370 Record whatever narrowing is in effect in the current buffer, if any,
9371 and restore that narrowing after evaluating the arguments.
9373 @item search-forward
9374 Search for a string, and if the string is found, move point. With a
9375 regular expression, use the similar @code{re-search-forward}.
9376 (@xref{Regexp Search, , Regular Expression Searches}, for an
9377 explanation of regular expression patterns and searches.)
9381 @code{search-forward} and @code{re-search-forward} take four
9386 The string or regular expression to search for.
9389 Optionally, the limit of the search.
9392 Optionally, what to do if the search fails, return @code{nil} or an
9396 Optionally, how many times to repeat the search; if negative, the
9397 search goes backwards.
9401 @itemx delete-and-extract-region
9402 @itemx copy-region-as-kill
9404 @code{kill-region} cuts the text between point and mark from the
9405 buffer and stores that text in the kill ring, so you can get it back
9408 @code{copy-region-as-kill} copies the text between point and mark into
9409 the kill ring, from which you can get it by yanking. The function
9410 does not cut or remove the text from the buffer.
9413 @code{delete-and-extract-region} removes the text between point and
9414 mark from the buffer and throws it away. You cannot get it back.
9415 (This is not an interactive command.)
9418 @node search Exercises
9419 @section Searching Exercises
9423 Write an interactive function that searches for a string. If the
9424 search finds the string, leave point after it and display a message
9425 that says ``Found!''. (Do not use @code{search-forward} for the name
9426 of this function; if you do, you will overwrite the existing version of
9427 @code{search-forward} that comes with Emacs. Use a name such as
9428 @code{test-search} instead.)
9431 Write a function that prints the third element of the kill ring in the
9432 echo area, if any; if the kill ring does not contain a third element,
9433 print an appropriate message.
9436 @node List Implementation
9437 @chapter How Lists are Implemented
9438 @cindex Lists in a computer
9440 In Lisp, atoms are recorded in a straightforward fashion; if the
9441 implementation is not straightforward in practice, it is, nonetheless,
9442 straightforward in theory. The atom @samp{rose}, for example, is
9443 recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s},
9444 @samp{e}. A list, on the other hand, is kept differently. The mechanism
9445 is equally simple, but it takes a moment to get used to the idea. A
9446 list is kept using a series of pairs of pointers. In the series, the
9447 first pointer in each pair points to an atom or to another list, and the
9448 second pointer in each pair points to the next pair, or to the symbol
9449 @code{nil}, which marks the end of the list.
9451 A pointer itself is quite simply the electronic address of what is
9452 pointed to. Hence, a list is kept as a series of electronic addresses.
9455 * Lists diagrammed::
9456 * Symbols as Chest:: Exploring a powerful metaphor.
9461 @node Lists diagrammed
9462 @unnumberedsec Lists diagrammed
9465 For example, the list @code{(rose violet buttercup)} has three elements,
9466 @samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the
9467 electronic address of @samp{rose} is recorded in a segment of computer
9468 memory along with the address that gives the electronic address of where
9469 the atom @samp{violet} is located; and that address (the one that tells
9470 where @samp{violet} is located) is kept along with an address that tells
9471 where the address for the atom @samp{buttercup} is located.
9474 This sounds more complicated than it is and is easier seen in a diagram:
9476 @c clear print-postscript-figures
9477 @c !!! cons-cell-diagram #1
9481 ___ ___ ___ ___ ___ ___
9482 |___|___|--> |___|___|--> |___|___|--> nil
9485 --> rose --> violet --> buttercup
9489 @ifset print-postscript-figures
9492 @center @image{cons-1}
9496 @ifclear print-postscript-figures
9500 ___ ___ ___ ___ ___ ___
9501 |___|___|--> |___|___|--> |___|___|--> nil
9504 --> rose --> violet --> buttercup
9511 In the diagram, each box represents a word of computer memory that
9512 holds a Lisp object, usually in the form of a memory address. The boxes,
9513 i.e., the addresses, are in pairs. Each arrow points to what the address
9514 is the address of, either an atom or another pair of addresses. The
9515 first box is the electronic address of @samp{rose} and the arrow points
9516 to @samp{rose}; the second box is the address of the next pair of boxes,
9517 the first part of which is the address of @samp{violet} and the second
9518 part of which is the address of the next pair. The very last box
9519 points to the symbol @code{nil}, which marks the end of the list.
9522 When a variable is set to a list with a function such as @code{setq},
9523 it stores the address of the first box in the variable. Thus,
9524 evaluation of the expression
9527 (setq bouquet '(rose violet buttercup))
9532 creates a situation like this:
9534 @c cons-cell-diagram #2
9540 | ___ ___ ___ ___ ___ ___
9541 --> |___|___|--> |___|___|--> |___|___|--> nil
9544 --> rose --> violet --> buttercup
9548 @ifset print-postscript-figures
9551 @center @image{cons-2}
9555 @ifclear print-postscript-figures
9561 | ___ ___ ___ ___ ___ ___
9562 --> |___|___|--> |___|___|--> |___|___|--> nil
9565 --> rose --> violet --> buttercup
9572 In this example, the symbol @code{bouquet} holds the address of the first
9576 This same list can be illustrated in a different sort of box notation
9579 @c cons-cell-diagram #2a
9585 | -------------- --------------- ----------------
9586 | | car | cdr | | car | cdr | | car | cdr |
9587 -->| rose | o------->| violet | o------->| butter- | nil |
9588 | | | | | | | cup | |
9589 -------------- --------------- ----------------
9593 @ifset print-postscript-figures
9596 @center @image{cons-2a}
9600 @ifclear print-postscript-figures
9606 | -------------- --------------- ----------------
9607 | | car | cdr | | car | cdr | | car | cdr |
9608 -->| rose | o------->| violet | o------->| butter- | nil |
9609 | | | | | | | cup | |
9610 -------------- --------------- ----------------
9616 (Symbols consist of more than pairs of addresses, but the structure of
9617 a symbol is made up of addresses. Indeed, the symbol @code{bouquet}
9618 consists of a group of address-boxes, one of which is the address of
9619 the printed word @samp{bouquet}, a second of which is the address of a
9620 function definition attached to the symbol, if any, a third of which
9621 is the address of the first pair of address-boxes for the list
9622 @code{(rose violet buttercup)}, and so on. Here we are showing that
9623 the symbol's third address-box points to the first pair of
9624 address-boxes for the list.)
9626 If a symbol is set to the @sc{cdr} of a list, the list itself is not
9627 changed; the symbol simply has an address further down the list. (In
9628 the jargon, @sc{car} and @sc{cdr} are ``non-destructive''.) Thus,
9629 evaluation of the following expression
9632 (setq flowers (cdr bouquet))
9639 @c cons-cell-diagram #3
9646 | ___ ___ | ___ ___ ___ ___
9647 --> | | | --> | | | | | |
9648 |___|___|----> |___|___|--> |___|___|--> nil
9651 --> rose --> violet --> buttercup
9656 @ifset print-postscript-figures
9659 @center @image{cons-3}
9663 @ifclear print-postscript-figures
9670 | ___ ___ | ___ ___ ___ ___
9671 --> | | | --> | | | | | |
9672 |___|___|----> |___|___|--> |___|___|--> nil
9675 --> rose --> violet --> buttercup
9683 The value of @code{flowers} is @code{(violet buttercup)}, which is
9684 to say, the symbol @code{flowers} holds the address of the pair of
9685 address-boxes, the first of which holds the address of @code{violet},
9686 and the second of which holds the address of @code{buttercup}.
9688 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
9689 pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp
9690 Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair
9691 Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more
9692 information about cons cells and dotted pairs.
9695 The function @code{cons} adds a new pair of addresses to the front of
9696 a series of addresses like that shown above. For example, evaluating
9700 (setq bouquet (cons 'lily bouquet))
9707 @c cons-cell-diagram #4
9714 | ___ ___ ___ ___ | ___ ___ ___ ___
9715 --> | | | | | | --> | | | | | |
9716 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9719 --> lily --> rose --> violet --> buttercup
9724 @ifset print-postscript-figures
9727 @center @image{cons-4}
9731 @ifclear print-postscript-figures
9738 | ___ ___ ___ ___ | ___ ___ ___ ___
9739 --> | | | | | | --> | | | | | |
9740 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9743 --> lily --> rose --> violet --> buttercup
9752 However, this does not change the value of the symbol
9753 @code{flowers}, as you can see by evaluating the following,
9756 (eq (cdr (cdr bouquet)) flowers)
9760 which returns @code{t} for true.
9762 Until it is reset, @code{flowers} still has the value
9763 @code{(violet buttercup)}; that is, it has the address of the cons
9764 cell whose first address is of @code{violet}. Also, this does not
9765 alter any of the pre-existing cons cells; they are all still there.
9767 Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address
9768 of the next cons cell in the series; to get the @sc{car} of a list,
9769 you get the address of the first element of the list; to @code{cons} a
9770 new element on a list, you add a new cons cell to the front of the list.
9771 That is all there is to it! The underlying structure of Lisp is
9774 And what does the last address in a series of cons cells refer to? It
9775 is the address of the empty list, of @code{nil}.
9777 In summary, when a Lisp variable is set to a value, it is provided with
9778 the address of the list to which the variable refers.
9780 @node Symbols as Chest
9781 @section Symbols as a Chest of Drawers
9782 @cindex Symbols as a Chest of Drawers
9783 @cindex Chest of Drawers, metaphor for a symbol
9784 @cindex Drawers, Chest of, metaphor for a symbol
9786 In an earlier section, I suggested that you might imagine a symbol as
9787 being a chest of drawers. The function definition is put in one
9788 drawer, the value in another, and so on. What is put in the drawer
9789 holding the value can be changed without affecting the contents of the
9790 drawer holding the function definition, and vice versa.
9792 Actually, what is put in each drawer is the address of the value or
9793 function definition. It is as if you found an old chest in the attic,
9794 and in one of its drawers you found a map giving you directions to
9795 where the buried treasure lies.
9797 (In addition to its name, symbol definition, and variable value, a
9798 symbol has a drawer for a @dfn{property list} which can be used to
9799 record other information. Property lists are not discussed here; see
9800 @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp
9804 Here is a fanciful representation:
9806 @c chest-of-drawers diagram
9811 Chest of Drawers Contents of Drawers
9815 ---------------------
9816 | directions to | [map to]
9817 | symbol name | bouquet
9819 +---------------------+
9821 | symbol definition | [none]
9823 +---------------------+
9824 | directions to | [map to]
9825 | variable value | (rose violet buttercup)
9827 +---------------------+
9829 | property list | [not described here]
9831 +---------------------+
9837 @ifset print-postscript-figures
9840 @center @image{drawers}
9844 @ifclear print-postscript-figures
9849 Chest of Drawers Contents of Drawers
9853 ---------------------
9854 | directions to | [map to]
9855 | symbol name | bouquet
9857 +---------------------+
9859 | symbol definition | [none]
9861 +---------------------+
9862 | directions to | [map to]
9863 | variable value | (rose violet buttercup)
9865 +---------------------+
9867 | property list | [not described here]
9869 +---------------------+
9880 Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two
9881 more flowers on to this list and set this new list to
9882 @code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish.
9883 What does the @code{more-flowers} list now contain?
9886 @chapter Yanking Text Back
9888 @cindex Text retrieval
9889 @cindex Retrieving text
9890 @cindex Pasting text
9892 Whenever you cut text out of a buffer with a kill command in GNU Emacs,
9893 you can bring it back with a yank command. The text that is cut out of
9894 the buffer is put in the kill ring and the yank commands insert the
9895 appropriate contents of the kill ring back into a buffer (not necessarily
9896 the original buffer).
9898 A simple @kbd{C-y} (@code{yank}) command inserts the first item from
9899 the kill ring into the current buffer. If the @kbd{C-y} command is
9900 followed immediately by @kbd{M-y}, the first element is replaced by
9901 the second element. Successive @kbd{M-y} commands replace the second
9902 element with the third, fourth, or fifth element, and so on. When the
9903 last element in the kill ring is reached, it is replaced by the first
9904 element and the cycle is repeated. (Thus the kill ring is called a
9905 ``ring'' rather than just a ``list''. However, the actual data structure
9906 that holds the text is a list.
9907 @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the
9908 list is handled as a ring.)
9911 * Kill Ring Overview::
9912 * kill-ring-yank-pointer:: The kill ring is a list.
9913 * yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
9916 @node Kill Ring Overview
9917 @section Kill Ring Overview
9918 @cindex Kill ring overview
9920 The kill ring is a list of textual strings. This is what it looks like:
9923 ("some text" "a different piece of text" "yet more text")
9926 If this were the contents of my kill ring and I pressed @kbd{C-y}, the
9927 string of characters saying @samp{some text} would be inserted in this
9928 buffer where my cursor is located.
9930 The @code{yank} command is also used for duplicating text by copying it.
9931 The copied text is not cut from the buffer, but a copy of it is put on the
9932 kill ring and is inserted by yanking it back.
9934 Three functions are used for bringing text back from the kill ring:
9935 @code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop},
9936 which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer},
9937 which is used by the two other functions.
9939 These functions refer to the kill ring through a variable called the
9940 @code{kill-ring-yank-pointer}. Indeed, the insertion code for both the
9941 @code{yank} and @code{yank-pop} functions is:
9944 (insert (car kill-ring-yank-pointer))
9948 (Well, no more. In GNU Emacs 22, the function has been replaced by
9949 @code{insert-for-yank} which calls @code{insert-for-yank-1}
9950 repetitively for each @code{yank-handler} segment. In turn,
9951 @code{insert-for-yank-1} strips text properties from the inserted text
9952 according to @code{yank-excluded-properties}. Otherwise, it is just
9953 like @code{insert}. We will stick with plain @code{insert} since it
9954 is easier to understand.)
9956 To begin to understand how @code{yank} and @code{yank-pop} work, it is
9957 first necessary to look at the @code{kill-ring-yank-pointer} variable.
9959 @node kill-ring-yank-pointer
9960 @section The @code{kill-ring-yank-pointer} Variable
9962 @code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is
9963 a variable. It points to something by being bound to the value of what
9964 it points to, like any other Lisp variable.
9967 Thus, if the value of the kill ring is:
9970 ("some text" "a different piece of text" "yet more text")
9975 and the @code{kill-ring-yank-pointer} points to the second clause, the
9976 value of @code{kill-ring-yank-pointer} is:
9979 ("a different piece of text" "yet more text")
9982 As explained in the previous chapter (@pxref{List Implementation}), the
9983 computer does not keep two different copies of the text being pointed to
9984 by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The
9985 words ``a different piece of text'' and ``yet more text'' are not
9986 duplicated. Instead, the two Lisp variables point to the same pieces of
9987 text. Here is a diagram:
9989 @c cons-cell-diagram #5
9993 kill-ring kill-ring-yank-pointer
9995 | ___ ___ | ___ ___ ___ ___
9996 ---> | | | --> | | | | | |
9997 |___|___|----> |___|___|--> |___|___|--> nil
10000 | | --> "yet more text"
10002 | --> "a different piece of text"
10009 @ifset print-postscript-figures
10012 @center @image{cons-5}
10016 @ifclear print-postscript-figures
10020 kill-ring kill-ring-yank-pointer
10022 | ___ ___ | ___ ___ ___ ___
10023 ---> | | | --> | | | | | |
10024 |___|___|----> |___|___|--> |___|___|--> nil
10027 | | --> "yet more text"
10029 | --> "a different piece of text
10038 Both the variable @code{kill-ring} and the variable
10039 @code{kill-ring-yank-pointer} are pointers. But the kill ring itself is
10040 usually described as if it were actually what it is composed of. The
10041 @code{kill-ring} is spoken of as if it were the list rather than that it
10042 points to the list. Conversely, the @code{kill-ring-yank-pointer} is
10043 spoken of as pointing to a list.
10045 These two ways of talking about the same thing sound confusing at first but
10046 make sense on reflection. The kill ring is generally thought of as the
10047 complete structure of data that holds the information of what has recently
10048 been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer}
10049 on the other hand, serves to indicate---that is, to point to---that part
10050 of the kill ring of which the first element (the @sc{car}) will be
10054 In GNU Emacs 22, the @code{kill-new} function calls
10056 @code{(setq kill-ring-yank-pointer kill-ring)}
10058 (defun rotate-yank-pointer (arg)
10059 "Rotate the yanking point in the kill ring.
10060 With argument, rotate that many kills forward (or backward, if negative)."
10062 (current-kill arg))
10064 (defun current-kill (n &optional do-not-move)
10065 "Rotate the yanking point by N places, and then return that kill.
10066 If N is zero, `interprogram-paste-function' is set, and calling it
10067 returns a string, then that string is added to the front of the
10068 kill ring and returned as the latest kill.
10069 If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
10070 yanking point; just return the Nth kill forward."
10071 (let ((interprogram-paste (and (= n 0)
10072 interprogram-paste-function
10073 (funcall interprogram-paste-function))))
10074 (if interprogram-paste
10076 ;; Disable the interprogram cut function when we add the new
10077 ;; text to the kill ring, so Emacs doesn't try to own the
10078 ;; selection, with identical text.
10079 (let ((interprogram-cut-function nil))
10080 (kill-new interprogram-paste))
10081 interprogram-paste)
10082 (or kill-ring (error "Kill ring is empty"))
10083 (let ((ARGth-kill-element
10084 (nthcdr (mod (- n (length kill-ring-yank-pointer))
10085 (length kill-ring))
10088 (setq kill-ring-yank-pointer ARGth-kill-element))
10089 (car ARGth-kill-element)))))
10094 @node yank nthcdr Exercises
10095 @section Exercises with @code{yank} and @code{nthcdr}
10099 Using @kbd{C-h v} (@code{describe-variable}), look at the value of
10100 your kill ring. Add several items to your kill ring; look at its
10101 value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way
10102 around the kill ring. How many items were in your kill ring? Find
10103 the value of @code{kill-ring-max}. Was your kill ring full, or could
10104 you have kept more blocks of text within it?
10107 Using @code{nthcdr} and @code{car}, construct a series of expressions
10108 to return the first, second, third, and fourth elements of a list.
10111 @node Loops & Recursion
10112 @chapter Loops and Recursion
10113 @cindex Loops and recursion
10114 @cindex Recursion and loops
10115 @cindex Repetition (loops)
10117 Emacs Lisp has two primary ways to cause an expression, or a series of
10118 expressions, to be evaluated repeatedly: one uses a @code{while}
10119 loop, and the other uses @dfn{recursion}.
10121 Repetition can be very valuable. For example, to move forward four
10122 sentences, you need only write a program that will move forward one
10123 sentence and then repeat the process four times. Since a computer does
10124 not get bored or tired, such repetitive action does not have the
10125 deleterious effects that excessive or the wrong kinds of repetition can
10128 People mostly write Emacs Lisp functions using @code{while} loops and
10129 their kin; but you can use recursion, which provides a very powerful
10130 way to think about and then to solve problems@footnote{You can write
10131 recursive functions to be frugal or wasteful of mental or computer
10132 resources; as it happens, methods that people find easy---that are
10133 frugal of mental resources---sometimes use considerable computer
10134 resources. Emacs was designed to run on machines that we now consider
10135 limited and its default settings are conservative. You may want to
10136 increase the values of @code{max-specpdl-size} and
10137 @code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to
10138 15 and 30 times their default value.}.
10141 * while:: Causing a stretch of code to repeat.
10143 * Recursion:: Causing a function to call itself.
10144 * Looping exercise::
10148 @section @code{while}
10152 The @code{while} special form tests whether the value returned by
10153 evaluating its first argument is true or false. This is similar to what
10154 the Lisp interpreter does with an @code{if}; what the interpreter does
10155 next, however, is different.
10157 In a @code{while} expression, if the value returned by evaluating the
10158 first argument is false, the Lisp interpreter skips the rest of the
10159 expression (the @dfn{body} of the expression) and does not evaluate it.
10160 However, if the value is true, the Lisp interpreter evaluates the body
10161 of the expression and then again tests whether the first argument to
10162 @code{while} is true or false. If the value returned by evaluating the
10163 first argument is again true, the Lisp interpreter again evaluates the
10164 body of the expression.
10167 The template for a @code{while} expression looks like this:
10171 (while @var{true-or-false-test}
10177 * Looping with while:: Repeat so long as test returns true.
10178 * Loop Example:: A @code{while} loop that uses a list.
10179 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
10180 * Incrementing Loop:: A loop with an incrementing counter.
10181 * Incrementing Loop Details::
10182 * Decrementing Loop:: A loop with a decrementing counter.
10186 @node Looping with while
10187 @unnumberedsubsec Looping with @code{while}
10190 So long as the true-or-false-test of the @code{while} expression
10191 returns a true value when it is evaluated, the body is repeatedly
10192 evaluated. This process is called a loop since the Lisp interpreter
10193 repeats the same thing again and again, like an airplane doing a loop.
10194 When the result of evaluating the true-or-false-test is false, the
10195 Lisp interpreter does not evaluate the rest of the @code{while}
10196 expression and exits the loop.
10198 Clearly, if the value returned by evaluating the first argument to
10199 @code{while} is always true, the body following will be evaluated
10200 again and again @dots{} and again @dots{} forever. Conversely, if the
10201 value returned is never true, the expressions in the body will never
10202 be evaluated. The craft of writing a @code{while} loop consists of
10203 choosing a mechanism such that the true-or-false-test returns true
10204 just the number of times that you want the subsequent expressions to
10205 be evaluated, and then have the test return false.
10207 The value returned by evaluating a @code{while} is the value of the
10208 true-or-false-test. An interesting consequence of this is that a
10209 @code{while} loop that evaluates without error will return @code{nil}
10210 or false regardless of whether it has looped 1 or 100 times or none at
10211 all. A @code{while} expression that evaluates successfully never
10212 returns a true value! What this means is that @code{while} is always
10213 evaluated for its side effects, which is to say, the consequences of
10214 evaluating the expressions within the body of the @code{while} loop.
10215 This makes sense. It is not the mere act of looping that is desired,
10216 but the consequences of what happens when the expressions in the loop
10217 are repeatedly evaluated.
10220 @subsection A @code{while} Loop and a List
10222 A common way to control a @code{while} loop is to test whether a list
10223 has any elements. If it does, the loop is repeated; but if it does not,
10224 the repetition is ended. Since this is an important technique, we will
10225 create a short example to illustrate it.
10227 A simple way to test whether a list has elements is to evaluate the
10228 list: if it has no elements, it is an empty list and will return the
10229 empty list, @code{()}, which is a synonym for @code{nil} or false. On
10230 the other hand, a list with elements will return those elements when it
10231 is evaluated. Since Emacs Lisp considers as true any value that is not
10232 @code{nil}, a list that returns elements will test true in a
10236 For example, you can set the variable @code{empty-list} to @code{nil} by
10237 evaluating the following @code{setq} expression:
10240 (setq empty-list ())
10244 After evaluating the @code{setq} expression, you can evaluate the
10245 variable @code{empty-list} in the usual way, by placing the cursor after
10246 the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your
10253 On the other hand, if you set a variable to be a list with elements, the
10254 list will appear when you evaluate the variable, as you can see by
10255 evaluating the following two expressions:
10259 (setq animals '(gazelle giraffe lion tiger))
10265 Thus, to create a @code{while} loop that tests whether there are any
10266 items in the list @code{animals}, the first part of the loop will be
10277 When the @code{while} tests its first argument, the variable
10278 @code{animals} is evaluated. It returns a list. So long as the list
10279 has elements, the @code{while} considers the results of the test to be
10280 true; but when the list is empty, it considers the results of the test
10283 To prevent the @code{while} loop from running forever, some mechanism
10284 needs to be provided to empty the list eventually. An oft-used
10285 technique is to have one of the subsequent forms in the @code{while}
10286 expression set the value of the list to be the @sc{cdr} of the list.
10287 Each time the @code{cdr} function is evaluated, the list will be made
10288 shorter, until eventually only the empty list will be left. At this
10289 point, the test of the @code{while} loop will return false, and the
10290 arguments to the @code{while} will no longer be evaluated.
10292 For example, the list of animals bound to the variable @code{animals}
10293 can be set to be the @sc{cdr} of the original list with the
10294 following expression:
10297 (setq animals (cdr animals))
10301 If you have evaluated the previous expressions and then evaluate this
10302 expression, you will see @code{(giraffe lion tiger)} appear in the echo
10303 area. If you evaluate the expression again, @code{(lion tiger)} will
10304 appear in the echo area. If you evaluate it again and yet again,
10305 @code{(tiger)} appears and then the empty list, shown by @code{nil}.
10307 A template for a @code{while} loop that uses the @code{cdr} function
10308 repeatedly to cause the true-or-false-test eventually to test false
10313 (while @var{test-whether-list-is-empty}
10315 @var{set-list-to-cdr-of-list})
10319 This test and use of @code{cdr} can be put together in a function that
10320 goes through a list and prints each element of the list on a line of its
10323 @node print-elements-of-list
10324 @subsection An Example: @code{print-elements-of-list}
10325 @findex print-elements-of-list
10327 The @code{print-elements-of-list} function illustrates a @code{while}
10330 @cindex @file{*scratch*} buffer
10331 The function requires several lines for its output. If you are
10332 reading this in a recent instance of GNU Emacs,
10333 @c GNU Emacs 21, GNU Emacs 22, or a later version,
10334 you can evaluate the following expression inside of Info, as usual.
10336 If you are using an earlier version of Emacs, you need to copy the
10337 necessary expressions to your @file{*scratch*} buffer and evaluate
10338 them there. This is because the echo area had only one line in the
10341 You can copy the expressions by marking the beginning of the region
10342 with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to
10343 the end of the region and then copying the region using @kbd{M-w}
10344 (@code{kill-ring-save}, which calls @code{copy-region-as-kill} and
10345 then provides visual feedback). In the @file{*scratch*}
10346 buffer, you can yank the expressions back by typing @kbd{C-y}
10349 After you have copied the expressions to the @file{*scratch*} buffer,
10350 evaluate each expression in turn. Be sure to evaluate the last
10351 expression, @code{(print-elements-of-list animals)}, by typing
10352 @kbd{C-u C-x C-e}, that is, by giving an argument to
10353 @code{eval-last-sexp}. This will cause the result of the evaluation
10354 to be printed in the @file{*scratch*} buffer instead of being printed
10355 in the echo area. (Otherwise you will see something like this in your
10356 echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which
10357 each @samp{^J} stands for a newline.)
10360 In a recent instance of GNU Emacs, you can evaluate these expressions
10361 directly in the Info buffer, and the echo area will grow to show the
10366 (setq animals '(gazelle giraffe lion tiger))
10368 (defun print-elements-of-list (list)
10369 "Print each element of LIST on a line of its own."
10372 (setq list (cdr list))))
10374 (print-elements-of-list animals)
10380 When you evaluate the three expressions in sequence, you will see
10396 Each element of the list is printed on a line of its own (that is what
10397 the function @code{print} does) and then the value returned by the
10398 function is printed. Since the last expression in the function is the
10399 @code{while} loop, and since @code{while} loops always return
10400 @code{nil}, a @code{nil} is printed after the last element of the list.
10402 @node Incrementing Loop
10403 @subsection A Loop with an Incrementing Counter
10405 A loop is not useful unless it stops when it ought. Besides
10406 controlling a loop with a list, a common way of stopping a loop is to
10407 write the first argument as a test that returns false when the correct
10408 number of repetitions are complete. This means that the loop must
10409 have a counter---an expression that counts how many times the loop
10413 @node Incrementing Loop Details
10414 @unnumberedsubsec Details of an Incrementing Loop
10417 The test for a loop with an incrementing counter can be an expression
10418 such as @code{(< count desired-number)} which returns @code{t} for
10419 true if the value of @code{count} is less than the
10420 @code{desired-number} of repetitions and @code{nil} for false if the
10421 value of @code{count} is equal to or is greater than the
10422 @code{desired-number}. The expression that increments the count can
10423 be a simple @code{setq} such as @code{(setq count (1+ count))}, where
10424 @code{1+} is a built-in function in Emacs Lisp that adds 1 to its
10425 argument. (The expression @w{@code{(1+ count)}} has the same result
10426 as @w{@code{(+ count 1)}}, but is easier for a human to read.)
10429 The template for a @code{while} loop controlled by an incrementing
10430 counter looks like this:
10434 @var{set-count-to-initial-value}
10435 (while (< count desired-number) ; @r{true-or-false-test}
10437 (setq count (1+ count))) ; @r{incrementer}
10442 Note that you need to set the initial value of @code{count}; usually it
10446 * Incrementing Example:: Counting pebbles in a triangle.
10447 * Inc Example parts:: The parts of the function definition.
10448 * Inc Example altogether:: Putting the function definition together.
10451 @node Incrementing Example
10452 @unnumberedsubsubsec Example with incrementing counter
10454 Suppose you are playing on the beach and decide to make a triangle of
10455 pebbles, putting one pebble in the first row, two in the second row,
10456 three in the third row and so on, like this:
10474 @bullet{} @bullet{}
10475 @bullet{} @bullet{} @bullet{}
10476 @bullet{} @bullet{} @bullet{} @bullet{}
10483 (About 2500 years ago, Pythagoras and others developed the beginnings of
10484 number theory by considering questions such as this.)
10486 Suppose you want to know how many pebbles you will need to make a
10487 triangle with 7 rows?
10489 Clearly, what you need to do is add up the numbers from 1 to 7. There
10490 are two ways to do this; start with the smallest number, one, and add up
10491 the list in sequence, 1, 2, 3, 4 and so on; or start with the largest
10492 number and add the list going down: 7, 6, 5, 4 and so on. Because both
10493 mechanisms illustrate common ways of writing @code{while} loops, we will
10494 create two examples, one counting up and the other counting down. In
10495 this first example, we will start with 1 and add 2, 3, 4 and so on.
10497 If you are just adding up a short list of numbers, the easiest way to do
10498 it is to add up all the numbers at once. However, if you do not know
10499 ahead of time how many numbers your list will have, or if you want to be
10500 prepared for a very long list, then you need to design your addition so
10501 that what you do is repeat a simple process many times instead of doing
10502 a more complex process once.
10504 For example, instead of adding up all the pebbles all at once, what you
10505 can do is add the number of pebbles in the first row, 1, to the number
10506 in the second row, 2, and then add the total of those two rows to the
10507 third row, 3. Then you can add the number in the fourth row, 4, to the
10508 total of the first three rows; and so on.
10510 The critical characteristic of the process is that each repetitive
10511 action is simple. In this case, at each step we add only two numbers,
10512 the number of pebbles in the row and the total already found. This
10513 process of adding two numbers is repeated again and again until the last
10514 row has been added to the total of all the preceding rows. In a more
10515 complex loop the repetitive action might not be so simple, but it will
10516 be simpler than doing everything all at once.
10518 @node Inc Example parts
10519 @unnumberedsubsubsec The parts of the function definition
10521 The preceding analysis gives us the bones of our function definition:
10522 first, we will need a variable that we can call @code{total} that will
10523 be the total number of pebbles. This will be the value returned by
10526 Second, we know that the function will require an argument: this
10527 argument will be the total number of rows in the triangle. It can be
10528 called @code{number-of-rows}.
10530 Finally, we need a variable to use as a counter. We could call this
10531 variable @code{counter}, but a better name is @code{row-number}. That
10532 is because what the counter does in this function is count rows, and a
10533 program should be written to be as understandable as possible.
10535 When the Lisp interpreter first starts evaluating the expressions in the
10536 function, the value of @code{total} should be set to zero, since we have
10537 not added anything to it. Then the function should add the number of
10538 pebbles in the first row to the total, and then add the number of
10539 pebbles in the second to the total, and then add the number of
10540 pebbles in the third row to the total, and so on, until there are no
10541 more rows left to add.
10543 Both @code{total} and @code{row-number} are used only inside the
10544 function, so they can be declared as local variables with @code{let}
10545 and given initial values. Clearly, the initial value for @code{total}
10546 should be 0. The initial value of @code{row-number} should be 1,
10547 since we start with the first row. This means that the @code{let}
10548 statement will look like this:
10558 After the internal variables are declared and bound to their initial
10559 values, we can begin the @code{while} loop. The expression that serves
10560 as the test should return a value of @code{t} for true so long as the
10561 @code{row-number} is less than or equal to the @code{number-of-rows}.
10562 (If the expression tests true only so long as the row number is less
10563 than the number of rows in the triangle, the last row will never be
10564 added to the total; hence the row number has to be either less than or
10565 equal to the number of rows.)
10568 @findex <= @r{(less than or equal)}
10569 Lisp provides the @code{<=} function that returns true if the value of
10570 its first argument is less than or equal to the value of its second
10571 argument and false otherwise. So the expression that the @code{while}
10572 will evaluate as its test should look like this:
10575 (<= row-number number-of-rows)
10578 The total number of pebbles can be found by repeatedly adding the number
10579 of pebbles in a row to the total already found. Since the number of
10580 pebbles in the row is equal to the row number, the total can be found by
10581 adding the row number to the total. (Clearly, in a more complex
10582 situation, the number of pebbles in the row might be related to the row
10583 number in a more complicated way; if this were the case, the row number
10584 would be replaced by the appropriate expression.)
10587 (setq total (+ total row-number))
10591 What this does is set the new value of @code{total} to be equal to the
10592 sum of adding the number of pebbles in the row to the previous total.
10594 After setting the value of @code{total}, the conditions need to be
10595 established for the next repetition of the loop, if there is one. This
10596 is done by incrementing the value of the @code{row-number} variable,
10597 which serves as a counter. After the @code{row-number} variable has
10598 been incremented, the true-or-false-test at the beginning of the
10599 @code{while} loop tests whether its value is still less than or equal to
10600 the value of the @code{number-of-rows} and if it is, adds the new value
10601 of the @code{row-number} variable to the @code{total} of the previous
10602 repetition of the loop.
10605 The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the
10606 @code{row-number} variable can be incremented with this expression:
10609 (setq row-number (1+ row-number))
10612 @node Inc Example altogether
10613 @unnumberedsubsubsec Putting the function definition together
10615 We have created the parts for the function definition; now we need to
10619 First, the contents of the @code{while} expression:
10623 (while (<= row-number number-of-rows) ; @r{true-or-false-test}
10624 (setq total (+ total row-number))
10625 (setq row-number (1+ row-number))) ; @r{incrementer}
10629 Along with the @code{let} expression varlist, this very nearly
10630 completes the body of the function definition. However, it requires
10631 one final element, the need for which is somewhat subtle.
10633 The final touch is to place the variable @code{total} on a line by
10634 itself after the @code{while} expression. Otherwise, the value returned
10635 by the whole function is the value of the last expression that is
10636 evaluated in the body of the @code{let}, and this is the value
10637 returned by the @code{while}, which is always @code{nil}.
10639 This may not be evident at first sight. It almost looks as if the
10640 incrementing expression is the last expression of the whole function.
10641 But that expression is part of the body of the @code{while}; it is the
10642 last element of the list that starts with the symbol @code{while}.
10643 Moreover, the whole of the @code{while} loop is a list within the body
10647 In outline, the function will look like this:
10651 (defun @var{name-of-function} (@var{argument-list})
10652 "@var{documentation}@dots{}"
10653 (let (@var{varlist})
10654 (while (@var{true-or-false-test})
10655 @var{body-of-while}@dots{} )
10656 @dots{} )) ; @r{Need final expression here.}
10660 The result of evaluating the @code{let} is what is going to be returned
10661 by the @code{defun} since the @code{let} is not embedded within any
10662 containing list, except for the @code{defun} as a whole. However, if
10663 the @code{while} is the last element of the @code{let} expression, the
10664 function will always return @code{nil}. This is not what we want!
10665 Instead, what we want is the value of the variable @code{total}. This
10666 is returned by simply placing the symbol as the last element of the list
10667 starting with @code{let}. It gets evaluated after the preceding
10668 elements of the list are evaluated, which means it gets evaluated after
10669 it has been assigned the correct value for the total.
10671 It may be easier to see this by printing the list starting with
10672 @code{let} all on one line. This format makes it evident that the
10673 @var{varlist} and @code{while} expressions are the second and third
10674 elements of the list starting with @code{let}, and the @code{total} is
10679 (let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total)
10684 Putting everything together, the @code{triangle} function definition
10689 (defun triangle (number-of-rows) ; @r{Version with}
10690 ; @r{ incrementing counter.}
10691 "Add up the number of pebbles in a triangle.
10692 The first row has one pebble, the second row two pebbles,
10693 the third row three pebbles, and so on.
10694 The argument is NUMBER-OF-ROWS."
10699 (while (<= row-number number-of-rows)
10700 (setq total (+ total row-number))
10701 (setq row-number (1+ row-number)))
10707 After you have installed @code{triangle} by evaluating the function, you
10708 can try it out. Here are two examples:
10719 The sum of the first four numbers is 10 and the sum of the first seven
10722 @node Decrementing Loop
10723 @subsection Loop with a Decrementing Counter
10725 Another common way to write a @code{while} loop is to write the test
10726 so that it determines whether a counter is greater than zero. So long
10727 as the counter is greater than zero, the loop is repeated. But when
10728 the counter is equal to or less than zero, the loop is stopped. For
10729 this to work, the counter has to start out greater than zero and then
10730 be made smaller and smaller by a form that is evaluated
10733 The test will be an expression such as @code{(> counter 0)} which
10734 returns @code{t} for true if the value of @code{counter} is greater
10735 than zero, and @code{nil} for false if the value of @code{counter} is
10736 equal to or less than zero. The expression that makes the number
10737 smaller and smaller can be a simple @code{setq} such as @code{(setq
10738 counter (1- counter))}, where @code{1-} is a built-in function in
10739 Emacs Lisp that subtracts 1 from its argument.
10742 The template for a decrementing @code{while} loop looks like this:
10746 (while (> counter 0) ; @r{true-or-false-test}
10748 (setq counter (1- counter))) ; @r{decrementer}
10753 * Decrementing Example:: More pebbles on the beach.
10754 * Dec Example parts:: The parts of the function definition.
10755 * Dec Example altogether:: Putting the function definition together.
10758 @node Decrementing Example
10759 @unnumberedsubsubsec Example with decrementing counter
10761 To illustrate a loop with a decrementing counter, we will rewrite the
10762 @code{triangle} function so the counter decreases to zero.
10764 This is the reverse of the earlier version of the function. In this
10765 case, to find out how many pebbles are needed to make a triangle with
10766 3 rows, add the number of pebbles in the third row, 3, to the number
10767 in the preceding row, 2, and then add the total of those two rows to
10768 the row that precedes them, which is 1.
10770 Likewise, to find the number of pebbles in a triangle with 7 rows, add
10771 the number of pebbles in the seventh row, 7, to the number in the
10772 preceding row, which is 6, and then add the total of those two rows to
10773 the row that precedes them, which is 5, and so on. As in the previous
10774 example, each addition only involves adding two numbers, the total of
10775 the rows already added up and the number of pebbles in the row that is
10776 being added to the total. This process of adding two numbers is
10777 repeated again and again until there are no more pebbles to add.
10779 We know how many pebbles to start with: the number of pebbles in the
10780 last row is equal to the number of rows. If the triangle has seven
10781 rows, the number of pebbles in the last row is 7. Likewise, we know how
10782 many pebbles are in the preceding row: it is one less than the number in
10785 @node Dec Example parts
10786 @unnumberedsubsubsec The parts of the function definition
10788 We start with three variables: the total number of rows in the
10789 triangle; the number of pebbles in a row; and the total number of
10790 pebbles, which is what we want to calculate. These variables can be
10791 named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and
10792 @code{total}, respectively.
10794 Both @code{total} and @code{number-of-pebbles-in-row} are used only
10795 inside the function and are declared with @code{let}. The initial
10796 value of @code{total} should, of course, be zero. However, the
10797 initial value of @code{number-of-pebbles-in-row} should be equal to
10798 the number of rows in the triangle, since the addition will start with
10802 This means that the beginning of the @code{let} expression will look
10808 (number-of-pebbles-in-row number-of-rows))
10813 The total number of pebbles can be found by repeatedly adding the number
10814 of pebbles in a row to the total already found, that is, by repeatedly
10815 evaluating the following expression:
10818 (setq total (+ total number-of-pebbles-in-row))
10822 After the @code{number-of-pebbles-in-row} is added to the @code{total},
10823 the @code{number-of-pebbles-in-row} should be decremented by one, since
10824 the next time the loop repeats, the preceding row will be
10825 added to the total.
10827 The number of pebbles in a preceding row is one less than the number of
10828 pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be
10829 used to compute the number of pebbles in the preceding row. This can be
10830 done with the following expression:
10834 (setq number-of-pebbles-in-row
10835 (1- number-of-pebbles-in-row))
10839 Finally, we know that the @code{while} loop should stop making repeated
10840 additions when there are no pebbles in a row. So the test for
10841 the @code{while} loop is simply:
10844 (while (> number-of-pebbles-in-row 0)
10847 @node Dec Example altogether
10848 @unnumberedsubsubsec Putting the function definition together
10850 We can put these expressions together to create a function definition
10851 that works. However, on examination, we find that one of the local
10852 variables is unneeded!
10855 The function definition looks like this:
10859 ;;; @r{First subtractive version.}
10860 (defun triangle (number-of-rows)
10861 "Add up the number of pebbles in a triangle."
10863 (number-of-pebbles-in-row number-of-rows))
10864 (while (> number-of-pebbles-in-row 0)
10865 (setq total (+ total number-of-pebbles-in-row))
10866 (setq number-of-pebbles-in-row
10867 (1- number-of-pebbles-in-row)))
10872 As written, this function works.
10874 However, we do not need @code{number-of-pebbles-in-row}.
10876 @cindex Argument as local variable
10877 When the @code{triangle} function is evaluated, the symbol
10878 @code{number-of-rows} will be bound to a number, giving it an initial
10879 value. That number can be changed in the body of the function as if
10880 it were a local variable, without any fear that such a change will
10881 effect the value of the variable outside of the function. This is a
10882 very useful characteristic of Lisp; it means that the variable
10883 @code{number-of-rows} can be used anywhere in the function where
10884 @code{number-of-pebbles-in-row} is used.
10887 Here is a second version of the function written a bit more cleanly:
10891 (defun triangle (number) ; @r{Second version.}
10892 "Return sum of numbers 1 through NUMBER inclusive."
10894 (while (> number 0)
10895 (setq total (+ total number))
10896 (setq number (1- number)))
10901 In brief, a properly written @code{while} loop will consist of three parts:
10905 A test that will return false after the loop has repeated itself the
10906 correct number of times.
10909 An expression the evaluation of which will return the value desired
10910 after being repeatedly evaluated.
10913 An expression to change the value passed to the true-or-false-test so
10914 that the test returns false after the loop has repeated itself the right
10918 @node dolist dotimes
10919 @section Save your time: @code{dolist} and @code{dotimes}
10921 In addition to @code{while}, both @code{dolist} and @code{dotimes}
10922 provide for looping. Sometimes these are quicker to write than the
10923 equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, ,
10924 Macros, elisp, The GNU Emacs Lisp Reference Manual}. )
10926 @code{dolist} works like a @code{while} loop that @sc{cdr}s down a
10927 list: @code{dolist} automatically shortens the list each time it
10928 loops---takes the @sc{cdr} of the list---and binds the @sc{car} of
10929 each shorter version of the list to the first of its arguments.
10931 @code{dotimes} loops a specific number of times: you specify the number.
10939 @unnumberedsubsec The @code{dolist} Macro
10942 Suppose, for example, you want to reverse a list, so that
10943 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''.
10946 In practice, you would use the @code{reverse} function, like this:
10950 (setq animals '(gazelle giraffe lion tiger))
10958 Here is how you could reverse the list using a @code{while} loop:
10962 (setq animals '(gazelle giraffe lion tiger))
10964 (defun reverse-list-with-while (list)
10965 "Using while, reverse the order of LIST."
10966 (let (value) ; make sure list starts empty
10968 (setq value (cons (car list) value))
10969 (setq list (cdr list)))
10972 (reverse-list-with-while animals)
10978 And here is how you could use the @code{dolist} macro:
10982 (setq animals '(gazelle giraffe lion tiger))
10984 (defun reverse-list-with-dolist (list)
10985 "Using dolist, reverse the order of LIST."
10986 (let (value) ; make sure list starts empty
10987 (dolist (element list value)
10988 (setq value (cons element value)))))
10990 (reverse-list-with-dolist animals)
10996 In Info, you can place your cursor after the closing parenthesis of
10997 each expression and type @kbd{C-x C-e}; in each case, you should see
11000 (tiger lion giraffe gazelle)
11006 For this example, the existing @code{reverse} function is obviously best.
11007 The @code{while} loop is just like our first example (@pxref{Loop
11008 Example, , A @code{while} Loop and a List}). The @code{while} first
11009 checks whether the list has elements; if so, it constructs a new list
11010 by adding the first element of the list to the existing list (which in
11011 the first iteration of the loop is @code{nil}). Since the second
11012 element is prepended in front of the first element, and the third
11013 element is prepended in front of the second element, the list is reversed.
11015 In the expression using a @code{while} loop,
11016 the @w{@code{(setq list (cdr list))}}
11017 expression shortens the list, so the @code{while} loop eventually
11018 stops. In addition, it provides the @code{cons} expression with a new
11019 first element by creating a new and shorter list at each repetition of
11022 The @code{dolist} expression does very much the same as the
11023 @code{while} expression, except that the @code{dolist} macro does some
11024 of the work you have to do when writing a @code{while} expression.
11026 Like a @code{while} loop, a @code{dolist} loops. What is different is
11027 that it automatically shortens the list each time it loops---it
11028 @sc{cdr}s down the list on its own---and it automatically binds
11029 the @sc{car} of each shorter version of the list to the first of its
11032 In the example, the @sc{car} of each shorter version of the list is
11033 referred to using the symbol @samp{element}, the list itself is called
11034 @samp{list}, and the value returned is called @samp{value}. The
11035 remainder of the @code{dolist} expression is the body.
11037 The @code{dolist} expression binds the @sc{car} of each shorter
11038 version of the list to @code{element} and then evaluates the body of
11039 the expression; and repeats the loop. The result is returned in
11043 @unnumberedsubsec The @code{dotimes} Macro
11046 The @code{dotimes} macro is similar to @code{dolist}, except that it
11047 loops a specific number of times.
11049 The first argument to @code{dotimes} is assigned the numbers 0, 1, 2
11050 and so forth each time around the loop, and the value of the third
11051 argument is returned. You need to provide the value of the second
11052 argument, which is how many times the macro loops.
11055 For example, the following binds the numbers from 0 up to, but not
11056 including, the number 3 to the first argument, @var{number}, and then
11057 constructs a list of the three numbers. (The first number is 0, the
11058 second number is 1, and the third number is 2; this makes a total of
11059 three numbers in all, starting with zero as the first number.)
11063 (let (value) ; otherwise a value is a void variable
11064 (dotimes (number 3 value)
11065 (setq value (cons number value))))
11072 @code{dotimes} returns @code{value}, so the way to use
11073 @code{dotimes} is to operate on some expression @var{number} number of
11074 times and then return the result, either as a list or an atom.
11077 Here is an example of a @code{defun} that uses @code{dotimes} to add
11078 up the number of pebbles in a triangle.
11082 (defun triangle-using-dotimes (number-of-rows)
11083 "Using `dotimes', add up the number of pebbles in a triangle."
11084 (let ((total 0)) ; otherwise a total is a void variable
11085 (dotimes (number number-of-rows total)
11086 (setq total (+ total (1+ number))))))
11088 (triangle-using-dotimes 4)
11096 A recursive function contains code that tells the Lisp interpreter to
11097 call a program that runs exactly like itself, but with slightly
11098 different arguments. The code runs exactly the same because it has
11099 the same name. However, even though the program has the same name, it
11100 is not the same entity. It is different. In the jargon, it is a
11101 different ``instance''.
11103 Eventually, if the program is written correctly, the slightly
11104 different arguments will become sufficiently different from the first
11105 arguments that the final instance will stop.
11108 * Building Robots:: Same model, different serial number ...
11109 * Recursive Definition Parts:: Walk until you stop ...
11110 * Recursion with list:: Using a list as the test whether to recurse.
11111 * Recursive triangle function::
11112 * Recursion with cond::
11113 * Recursive Patterns:: Often used templates.
11114 * No Deferment:: Don't store up work ...
11115 * No deferment solution::
11118 @node Building Robots
11119 @subsection Building Robots: Extending the Metaphor
11120 @cindex Building robots
11121 @cindex Robots, building
11123 It is sometimes helpful to think of a running program as a robot that
11124 does a job. In doing its job, a recursive function calls on a second
11125 robot to help it. The second robot is identical to the first in every
11126 way, except that the second robot helps the first and has been
11127 passed different arguments than the first.
11129 In a recursive function, the second robot may call a third; and the
11130 third may call a fourth, and so on. Each of these is a different
11131 entity; but all are clones.
11133 Since each robot has slightly different instructions---the arguments
11134 will differ from one robot to the next---the last robot should know
11137 Let's expand on the metaphor in which a computer program is a robot.
11139 A function definition provides the blueprints for a robot. When you
11140 install a function definition, that is, when you evaluate a
11141 @code{defun} macro, you install the necessary equipment to build
11142 robots. It is as if you were in a factory, setting up an assembly
11143 line. Robots with the same name are built according to the same
11144 blueprints. So they have the same model number, but a
11145 different serial number.
11147 We often say that a recursive function ``calls itself''. What we mean
11148 is that the instructions in a recursive function cause the Lisp
11149 interpreter to run a different function that has the same name and
11150 does the same job as the first, but with different arguments.
11152 It is important that the arguments differ from one instance to the
11153 next; otherwise, the process will never stop.
11155 @node Recursive Definition Parts
11156 @subsection The Parts of a Recursive Definition
11157 @cindex Parts of a Recursive Definition
11158 @cindex Recursive Definition Parts
11160 A recursive function typically contains a conditional expression which
11165 A true-or-false-test that determines whether the function is called
11166 again, here called the @dfn{do-again-test}.
11169 The name of the function. When this name is called, a new instance of
11170 the function---a new robot, as it were---is created and told what to do.
11173 An expression that returns a different value each time the function is
11174 called, here called the @dfn{next-step-expression}. Consequently, the
11175 argument (or arguments) passed to the new instance of the function
11176 will be different from that passed to the previous instance. This
11177 causes the conditional expression, the @dfn{do-again-test}, to test
11178 false after the correct number of repetitions.
11181 Recursive functions can be much simpler than any other kind of
11182 function. Indeed, when people first start to use them, they often look
11183 so mysteriously simple as to be incomprehensible. Like riding a
11184 bicycle, reading a recursive function definition takes a certain knack
11185 which is hard at first but then seems simple.
11188 There are several different common recursive patterns. A very simple
11189 pattern looks like this:
11193 (defun @var{name-of-recursive-function} (@var{argument-list})
11194 "@var{documentation}@dots{}"
11195 (if @var{do-again-test}
11197 (@var{name-of-recursive-function}
11198 @var{next-step-expression})))
11202 Each time a recursive function is evaluated, a new instance of it is
11203 created and told what to do. The arguments tell the instance what to do.
11205 An argument is bound to the value of the next-step-expression. Each
11206 instance runs with a different value of the next-step-expression.
11208 The value in the next-step-expression is used in the do-again-test.
11210 The value returned by the next-step-expression is passed to the new
11211 instance of the function, which evaluates it (or some
11212 transmogrification of it) to determine whether to continue or stop.
11213 The next-step-expression is designed so that the do-again-test returns
11214 false when the function should no longer be repeated.
11216 The do-again-test is sometimes called the @dfn{stop condition},
11217 since it stops the repetitions when it tests false.
11219 @node Recursion with list
11220 @subsection Recursion with a List
11222 The example of a @code{while} loop that printed the elements of a list
11223 of numbers can be written recursively. Here is the code, including
11224 an expression to set the value of the variable @code{animals} to a list.
11226 If you are reading this in Info in Emacs, you can evaluate this
11227 expression directly in Info. Otherwise, you must copy the example
11228 to the @file{*scratch*} buffer and evaluate each expression there.
11229 Use @kbd{C-u C-x C-e} to evaluate the
11230 @code{(print-elements-recursively animals)} expression so that the
11231 results are printed in the buffer; otherwise the Lisp interpreter will
11232 try to squeeze the results into the one line of the echo area.
11234 Also, place your cursor immediately after the last closing parenthesis
11235 of the @code{print-elements-recursively} function, before the comment.
11236 Otherwise, the Lisp interpreter will try to evaluate the comment.
11238 @findex print-elements-recursively
11241 (setq animals '(gazelle giraffe lion tiger))
11243 (defun print-elements-recursively (list)
11244 "Print each element of LIST on a line of its own.
11246 (when list ; @r{do-again-test}
11247 (print (car list)) ; @r{body}
11248 (print-elements-recursively ; @r{recursive call}
11249 (cdr list)))) ; @r{next-step-expression}
11251 (print-elements-recursively animals)
11255 The @code{print-elements-recursively} function first tests whether
11256 there is any content in the list; if there is, the function prints the
11257 first element of the list, the @sc{car} of the list. Then the
11258 function invokes itself, but gives itself as its argument, not the
11259 whole list, but the second and subsequent elements of the list, the
11260 @sc{cdr} of the list.
11262 Put another way, if the list is not empty, the function invokes
11263 another instance of code that is similar to the initial code, but is a
11264 different thread of execution, with different arguments than the first
11267 Put in yet another way, if the list is not empty, the first robot
11268 assembles a second robot and tells it what to do; the second robot is
11269 a different individual from the first, but is the same model.
11271 When the second evaluation occurs, the @code{when} expression is
11272 evaluated and if true, prints the first element of the list it
11273 receives as its argument (which is the second element of the original
11274 list). Then the function calls itself with the @sc{cdr} of the list
11275 it is invoked with, which (the second time around) is the @sc{cdr} of
11276 the @sc{cdr} of the original list.
11278 Note that although we say that the function ``calls itself'', what we
11279 mean is that the Lisp interpreter assembles and instructs a new
11280 instance of the program. The new instance is a clone of the first,
11281 but is a separate individual.
11283 Each time the function invokes itself, it does so on a
11284 shorter version of the original list. It creates a new instance that
11285 works on a shorter list.
11287 Eventually, the function invokes itself on an empty list. It creates
11288 a new instance whose argument is @code{nil}. The conditional expression
11289 tests the value of @code{list}. Since the value of @code{list} is
11290 @code{nil}, the @code{when} expression tests false so the then-part is
11291 not evaluated. The function as a whole then returns @code{nil}.
11294 When you evaluate the expression @code{(print-elements-recursively
11295 animals)} in the @file{*scratch*} buffer, you see this result:
11311 @node Recursive triangle function
11312 @subsection Recursion in Place of a Counter
11313 @findex triangle-recursively
11316 The @code{triangle} function described in a previous section can also
11317 be written recursively. It looks like this:
11321 (defun triangle-recursively (number)
11322 "Return the sum of the numbers 1 through NUMBER inclusive.
11324 (if (= number 1) ; @r{do-again-test}
11326 (+ number ; @r{else-part}
11327 (triangle-recursively ; @r{recursive call}
11328 (1- number))))) ; @r{next-step-expression}
11330 (triangle-recursively 7)
11335 You can install this function by evaluating it and then try it by
11336 evaluating @code{(triangle-recursively 7)}. (Remember to put your
11337 cursor immediately after the last parenthesis of the function
11338 definition, before the comment.) The function evaluates to 28.
11340 To understand how this function works, let's consider what happens in the
11341 various cases when the function is passed 1, 2, 3, or 4 as the value of
11345 * Recursive Example arg of 1 or 2::
11346 * Recursive Example arg of 3 or 4::
11350 @node Recursive Example arg of 1 or 2
11351 @unnumberedsubsubsec An argument of 1 or 2
11354 First, what happens if the value of the argument is 1?
11356 The function has an @code{if} expression after the documentation
11357 string. It tests whether the value of @code{number} is equal to 1; if
11358 so, Emacs evaluates the then-part of the @code{if} expression, which
11359 returns the number 1 as the value of the function. (A triangle with
11360 one row has one pebble in it.)
11362 Suppose, however, that the value of the argument is 2. In this case,
11363 Emacs evaluates the else-part of the @code{if} expression.
11366 The else-part consists of an addition, the recursive call to
11367 @code{triangle-recursively} and a decrementing action; and it looks like
11371 (+ number (triangle-recursively (1- number)))
11374 When Emacs evaluates this expression, the innermost expression is
11375 evaluated first; then the other parts in sequence. Here are the steps
11379 @item Step 1 @w{ } Evaluate the innermost expression.
11381 The innermost expression is @code{(1- number)} so Emacs decrements the
11382 value of @code{number} from 2 to 1.
11384 @item Step 2 @w{ } Evaluate the @code{triangle-recursively} function.
11386 The Lisp interpreter creates an individual instance of
11387 @code{triangle-recursively}. It does not matter that this function is
11388 contained within itself. Emacs passes the result Step 1 as the
11389 argument used by this instance of the @code{triangle-recursively}
11392 In this case, Emacs evaluates @code{triangle-recursively} with an
11393 argument of 1. This means that this evaluation of
11394 @code{triangle-recursively} returns 1.
11396 @item Step 3 @w{ } Evaluate the value of @code{number}.
11398 The variable @code{number} is the second element of the list that
11399 starts with @code{+}; its value is 2.
11401 @item Step 4 @w{ } Evaluate the @code{+} expression.
11403 The @code{+} expression receives two arguments, the first
11404 from the evaluation of @code{number} (Step 3) and the second from the
11405 evaluation of @code{triangle-recursively} (Step 2).
11407 The result of the addition is the sum of 2 plus 1, and the number 3 is
11408 returned, which is correct. A triangle with two rows has three
11412 @node Recursive Example arg of 3 or 4
11413 @unnumberedsubsubsec An argument of 3 or 4
11415 Suppose that @code{triangle-recursively} is called with an argument of
11419 @item Step 1 @w{ } Evaluate the do-again-test.
11421 The @code{if} expression is evaluated first. This is the do-again
11422 test and returns false, so the else-part of the @code{if} expression
11423 is evaluated. (Note that in this example, the do-again-test causes
11424 the function to call itself when it tests false, not when it tests
11427 @item Step 2 @w{ } Evaluate the innermost expression of the else-part.
11429 The innermost expression of the else-part is evaluated, which decrements
11430 3 to 2. This is the next-step-expression.
11432 @item Step 3 @w{ } Evaluate the @code{triangle-recursively} function.
11434 The number 2 is passed to the @code{triangle-recursively} function.
11436 We already know what happens when Emacs evaluates @code{triangle-recursively} with
11437 an argument of 2. After going through the sequence of actions described
11438 earlier, it returns a value of 3. So that is what will happen here.
11440 @item Step 4 @w{ } Evaluate the addition.
11442 3 will be passed as an argument to the addition and will be added to the
11443 number with which the function was called, which is 3.
11447 The value returned by the function as a whole will be 6.
11449 Now that we know what will happen when @code{triangle-recursively} is
11450 called with an argument of 3, it is evident what will happen if it is
11451 called with an argument of 4:
11455 In the recursive call, the evaluation of
11458 (triangle-recursively (1- 4))
11463 will return the value of evaluating
11466 (triangle-recursively 3)
11470 which is 6 and this value will be added to 4 by the addition in the
11475 The value returned by the function as a whole will be 10.
11477 Each time @code{triangle-recursively} is evaluated, it evaluates a
11478 version of itself---a different instance of itself---with a smaller
11479 argument, until the argument is small enough so that it does not
11482 Note that this particular design for a recursive function
11483 requires that operations be deferred.
11485 Before @code{(triangle-recursively 7)} can calculate its answer, it
11486 must call @code{(triangle-recursively 6)}; and before
11487 @code{(triangle-recursively 6)} can calculate its answer, it must call
11488 @code{(triangle-recursively 5)}; and so on. That is to say, the
11489 calculation that @code{(triangle-recursively 7)} makes must be
11490 deferred until @code{(triangle-recursively 6)} makes its calculation;
11491 and @code{(triangle-recursively 6)} must defer until
11492 @code{(triangle-recursively 5)} completes; and so on.
11494 If each of these instances of @code{triangle-recursively} are thought
11495 of as different robots, the first robot must wait for the second to
11496 complete its job, which must wait until the third completes, and so
11499 There is a way around this kind of waiting, which we will discuss in
11500 @ref{No Deferment, , Recursion without Deferments}.
11502 @node Recursion with cond
11503 @subsection Recursion Example Using @code{cond}
11506 The version of @code{triangle-recursively} described earlier is written
11507 with the @code{if} special form. It can also be written using another
11508 special form called @code{cond}. The name of the special form
11509 @code{cond} is an abbreviation of the word @samp{conditional}.
11511 Although the @code{cond} special form is not used as often in the
11512 Emacs Lisp sources as @code{if}, it is used often enough to justify
11516 The template for a @code{cond} expression looks like this:
11526 where the @var{body} is a series of lists.
11529 Written out more fully, the template looks like this:
11534 (@var{first-true-or-false-test} @var{first-consequent})
11535 (@var{second-true-or-false-test} @var{second-consequent})
11536 (@var{third-true-or-false-test} @var{third-consequent})
11541 When the Lisp interpreter evaluates the @code{cond} expression, it
11542 evaluates the first element (the @sc{car} or true-or-false-test) of
11543 the first expression in a series of expressions within the body of the
11546 If the true-or-false-test returns @code{nil} the rest of that
11547 expression, the consequent, is skipped and the true-or-false-test of the
11548 next expression is evaluated. When an expression is found whose
11549 true-or-false-test returns a value that is not @code{nil}, the
11550 consequent of that expression is evaluated. The consequent can be one
11551 or more expressions. If the consequent consists of more than one
11552 expression, the expressions are evaluated in sequence and the value of
11553 the last one is returned. If the expression does not have a consequent,
11554 the value of the true-or-false-test is returned.
11556 If none of the true-or-false-tests test true, the @code{cond} expression
11557 returns @code{nil}.
11560 Written using @code{cond}, the @code{triangle} function looks like this:
11564 (defun triangle-using-cond (number)
11565 (cond ((<= number 0) 0)
11568 (+ number (triangle-using-cond (1- number))))))
11573 In this example, the @code{cond} returns 0 if the number is less than or
11574 equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+
11575 number (triangle-using-cond (1- number)))} if the number is greater than
11578 @node Recursive Patterns
11579 @subsection Recursive Patterns
11580 @cindex Recursive Patterns
11582 Here are three common recursive patterns. Each involves a list.
11583 Recursion does not need to involve lists, but Lisp is designed for lists
11584 and this provides a sense of its primal capabilities.
11593 @unnumberedsubsubsec Recursive Pattern: @emph{every}
11594 @cindex Every, type of recursive pattern
11595 @cindex Recursive pattern - every
11597 In the @code{every} recursive pattern, an action is performed on every
11601 The basic pattern is:
11605 If a list be empty, return @code{nil}.
11607 Else, act on the beginning of the list (the @sc{car} of the list)
11610 through a recursive call by the function on the rest (the
11611 @sc{cdr}) of the list,
11613 and, optionally, combine the acted-on element, using @code{cons},
11614 with the results of acting on the rest.
11619 Here is an example:
11623 (defun square-each (numbers-list)
11624 "Square each of a NUMBERS LIST, recursively."
11625 (if (not numbers-list) ; do-again-test
11628 (* (car numbers-list) (car numbers-list))
11629 (square-each (cdr numbers-list))))) ; next-step-expression
11633 (square-each '(1 2 3))
11640 If @code{numbers-list} is empty, do nothing. But if it has content,
11641 construct a list combining the square of the first number in the list
11642 with the result of the recursive call.
11644 (The example follows the pattern exactly: @code{nil} is returned if
11645 the numbers' list is empty. In practice, you would write the
11646 conditional so it carries out the action when the numbers' list is not
11649 The @code{print-elements-recursively} function (@pxref{Recursion with
11650 list, , Recursion with a List}) is another example of an @code{every}
11651 pattern, except in this case, rather than bring the results together
11652 using @code{cons}, we print each element of output.
11655 The @code{print-elements-recursively} function looks like this:
11659 (setq animals '(gazelle giraffe lion tiger))
11663 (defun print-elements-recursively (list)
11664 "Print each element of LIST on a line of its own.
11666 (when list ; @r{do-again-test}
11667 (print (car list)) ; @r{body}
11668 (print-elements-recursively ; @r{recursive call}
11669 (cdr list)))) ; @r{next-step-expression}
11671 (print-elements-recursively animals)
11676 The pattern for @code{print-elements-recursively} is:
11680 When the list is empty, do nothing.
11682 But when the list has at least one element,
11685 act on the beginning of the list (the @sc{car} of the list),
11687 and make a recursive call on the rest (the @sc{cdr}) of the list.
11692 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
11693 @cindex Accumulate, type of recursive pattern
11694 @cindex Recursive pattern - accumulate
11696 Another recursive pattern is called the @code{accumulate} pattern. In
11697 the @code{accumulate} recursive pattern, an action is performed on
11698 every element of a list and the result of that action is accumulated
11699 with the results of performing the action on the other elements.
11701 This is very like the @code{every} pattern using @code{cons}, except that
11702 @code{cons} is not used, but some other combiner.
11709 If a list be empty, return zero or some other constant.
11711 Else, act on the beginning of the list (the @sc{car} of the list),
11714 and combine that acted-on element, using @code{+} or
11715 some other combining function, with
11717 a recursive call by the function on the rest (the @sc{cdr}) of the list.
11722 Here is an example:
11726 (defun add-elements (numbers-list)
11727 "Add the elements of NUMBERS-LIST together."
11728 (if (not numbers-list)
11730 (+ (car numbers-list) (add-elements (cdr numbers-list)))))
11734 (add-elements '(1 2 3 4))
11739 @xref{Files List, , Making a List of Files}, for an example of the
11740 accumulate pattern.
11743 @unnumberedsubsubsec Recursive Pattern: @emph{keep}
11744 @cindex Keep, type of recursive pattern
11745 @cindex Recursive pattern - keep
11747 A third recursive pattern is called the @code{keep} pattern.
11748 In the @code{keep} recursive pattern, each element of a list is tested;
11749 the element is acted on and the results are kept only if the element
11752 Again, this is very like the @code{every} pattern, except the element is
11753 skipped unless it meets a criterion.
11756 The pattern has three parts:
11760 If a list be empty, return @code{nil}.
11762 Else, if the beginning of the list (the @sc{car} of the list) passes
11766 act on that element and combine it, using @code{cons} with
11768 a recursive call by the function on the rest (the @sc{cdr}) of the list.
11771 Otherwise, if the beginning of the list (the @sc{car} of the list) fails
11775 skip on that element,
11777 and, recursively call the function on the rest (the @sc{cdr}) of the list.
11782 Here is an example that uses @code{cond}:
11786 (defun keep-three-letter-words (word-list)
11787 "Keep three letter words in WORD-LIST."
11789 ;; First do-again-test: stop-condition
11790 ((not word-list) nil)
11792 ;; Second do-again-test: when to act
11793 ((eq 3 (length (symbol-name (car word-list))))
11794 ;; combine acted-on element with recursive call on shorter list
11795 (cons (car word-list) (keep-three-letter-words (cdr word-list))))
11797 ;; Third do-again-test: when to skip element;
11798 ;; recursively call shorter list with next-step expression
11799 (t (keep-three-letter-words (cdr word-list)))))
11803 (keep-three-letter-words '(one two three four five six))
11804 @result{} (one two six)
11808 It goes without saying that you need not use @code{nil} as the test for
11809 when to stop; and you can, of course, combine these patterns.
11812 @subsection Recursion without Deferments
11813 @cindex Deferment in recursion
11814 @cindex Recursion without Deferments
11816 Let's consider again what happens with the @code{triangle-recursively}
11817 function. We will find that the intermediate calculations are
11818 deferred until all can be done.
11821 Here is the function definition:
11825 (defun triangle-recursively (number)
11826 "Return the sum of the numbers 1 through NUMBER inclusive.
11828 (if (= number 1) ; @r{do-again-test}
11830 (+ number ; @r{else-part}
11831 (triangle-recursively ; @r{recursive call}
11832 (1- number))))) ; @r{next-step-expression}
11836 What happens when we call this function with a argument of 7?
11838 The first instance of the @code{triangle-recursively} function adds
11839 the number 7 to the value returned by a second instance of
11840 @code{triangle-recursively}, an instance that has been passed an
11841 argument of 6. That is to say, the first calculation is:
11844 (+ 7 (triangle-recursively 6))
11848 The first instance of @code{triangle-recursively}---you may want to
11849 think of it as a little robot---cannot complete its job. It must hand
11850 off the calculation for @code{(triangle-recursively 6)} to a second
11851 instance of the program, to a second robot. This second individual is
11852 completely different from the first one; it is, in the jargon, a
11853 ``different instantiation''. Or, put another way, it is a different
11854 robot. It is the same model as the first; it calculates triangle
11855 numbers recursively; but it has a different serial number.
11857 And what does @code{(triangle-recursively 6)} return? It returns the
11858 number 6 added to the value returned by evaluating
11859 @code{triangle-recursively} with an argument of 5. Using the robot
11860 metaphor, it asks yet another robot to help it.
11866 (+ 7 6 (triangle-recursively 5))
11870 And what happens next?
11873 (+ 7 6 5 (triangle-recursively 4))
11876 Each time @code{triangle-recursively} is called, except for the last
11877 time, it creates another instance of the program---another robot---and
11878 asks it to make a calculation.
11881 Eventually, the full addition is set up and performed:
11887 This design for the function defers the calculation of the first step
11888 until the second can be done, and defers that until the third can be
11889 done, and so on. Each deferment means the computer must remember what
11890 is being waited on. This is not a problem when there are only a few
11891 steps, as in this example. But it can be a problem when there are
11894 @node No deferment solution
11895 @subsection No Deferment Solution
11896 @cindex No deferment solution
11897 @cindex Solution without deferment
11899 The solution to the problem of deferred operations is to write in a
11900 manner that does not defer operations@footnote{The phrase @dfn{tail
11901 recursive} is used to describe such a process, one that uses
11902 constant space.}. This requires
11903 writing to a different pattern, often one that involves writing two
11904 function definitions, an initialization function and a helper
11907 The initialization function sets up the job; the helper function
11911 Here are the two function definitions for adding up numbers. They are
11912 so simple, I find them hard to understand.
11916 (defun triangle-initialization (number)
11917 "Return the sum of the numbers 1 through NUMBER inclusive.
11918 This is the initialization component of a two function
11919 duo that uses recursion."
11920 (triangle-recursive-helper 0 0 number))
11926 (defun triangle-recursive-helper (sum counter number)
11927 "Return SUM, using COUNTER, through NUMBER inclusive.
11928 This is the helper component of a two function duo
11929 that uses recursion."
11930 (if (> counter number)
11932 (triangle-recursive-helper (+ sum counter) ; @r{sum}
11933 (1+ counter) ; @r{counter}
11934 number))) ; @r{number}
11939 Install both function definitions by evaluating them, then call
11940 @code{triangle-initialization} with 2 rows:
11944 (triangle-initialization 2)
11949 The initialization function calls the first instance of the helper
11950 function with three arguments: zero, zero, and a number which is the
11951 number of rows in the triangle.
11953 The first two arguments passed to the helper function are
11954 initialization values. These values are changed when
11955 @code{triangle-recursive-helper} invokes new instances.@footnote{The
11956 jargon is mildly confusing: @code{triangle-recursive-helper} uses a
11957 process that is iterative in a procedure that is recursive. The
11958 process is called iterative because the computer need only record the
11959 three values, @code{sum}, @code{counter}, and @code{number}; the
11960 procedure is recursive because the function calls itself. On the
11961 other hand, both the process and the procedure used by
11962 @code{triangle-recursively} are called recursive. The word
11963 ``recursive'' has different meanings in the two contexts.}
11965 Let's see what happens when we have a triangle that has one row. (This
11966 triangle will have one pebble in it!)
11969 @code{triangle-initialization} will call its helper with
11970 the arguments @w{@code{0 0 1}}. That function will run the conditional
11971 test whether @code{(> counter number)}:
11979 and find that the result is false, so it will invoke
11980 the else-part of the @code{if} clause:
11984 (triangle-recursive-helper
11985 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
11986 (1+ counter) ; @r{increment counter} @result{} @r{counter}
11987 number) ; @r{number stays the same}
11993 which will first compute:
11997 (triangle-recursive-helper (+ 0 0) ; @r{sum}
11998 (1+ 0) ; @r{counter}
12002 (triangle-recursive-helper 0 1 1)
12006 Again, @code{(> counter number)} will be false, so again, the Lisp
12007 interpreter will evaluate @code{triangle-recursive-helper}, creating a
12008 new instance with new arguments.
12011 This new instance will be;
12015 (triangle-recursive-helper
12016 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
12017 (1+ counter) ; @r{increment counter} @result{} @r{counter}
12018 number) ; @r{number stays the same}
12022 (triangle-recursive-helper 1 2 1)
12026 In this case, the @code{(> counter number)} test will be true! So the
12027 instance will return the value of the sum, which will be 1, as
12030 Now, let's pass @code{triangle-initialization} an argument
12031 of 2, to find out how many pebbles there are in a triangle with two rows.
12033 That function calls @code{(triangle-recursive-helper 0 0 2)}.
12036 In stages, the instances called will be:
12040 @r{sum counter number}
12041 (triangle-recursive-helper 0 1 2)
12043 (triangle-recursive-helper 1 2 2)
12045 (triangle-recursive-helper 3 3 2)
12049 When the last instance is called, the @code{(> counter number)} test
12050 will be true, so the instance will return the value of @code{sum},
12053 This kind of pattern helps when you are writing functions that can use
12054 many resources in a computer.
12057 @node Looping exercise
12058 @section Looping Exercise
12062 Write a function similar to @code{triangle} in which each row has a
12063 value which is the square of the row number. Use a @code{while} loop.
12066 Write a function similar to @code{triangle} that multiplies instead of
12070 Rewrite these two functions recursively. Rewrite these functions
12073 @c comma in printed title causes problem in Info cross reference
12075 Write a function for Texinfo mode that creates an index entry at the
12076 beginning of a paragraph for every @samp{@@dfn} within the paragraph.
12077 (In a Texinfo file, @samp{@@dfn} marks a definition. This book is
12078 written in Texinfo.)
12080 Many of the functions you will need are described in two of the
12081 previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing
12082 Text}, and @ref{Yanking, , Yanking Text Back}. If you use
12083 @code{forward-paragraph} to put the index entry at the beginning of
12084 the paragraph, you will have to use @w{@kbd{C-h f}}
12085 (@code{describe-function}) to find out how to make the command go
12088 For more information, see
12090 @ref{Indicating, , Indicating Definitions, texinfo}.
12093 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to
12094 a Texinfo manual in the current directory. Or, if you are on the
12096 @uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
12099 ``Indicating Definitions, Commands, etc.''@: in @cite{Texinfo, The GNU
12100 Documentation Format}.
12104 @node Regexp Search
12105 @chapter Regular Expression Searches
12106 @cindex Searches, illustrating
12107 @cindex Regular expression searches
12108 @cindex Patterns, searching for
12109 @cindex Motion by sentence and paragraph
12110 @cindex Sentences, movement by
12111 @cindex Paragraphs, movement by
12113 Regular expression searches are used extensively in GNU Emacs. The
12114 two functions, @code{forward-sentence} and @code{forward-paragraph},
12115 illustrate these searches well. They use regular expressions to find
12116 where to move point. The phrase ``regular expression'' is often written
12119 Regular expression searches are described in @ref{Regexp Search, ,
12120 Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in
12121 @ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference
12122 Manual}. In writing this chapter, I am presuming that you have at
12123 least a mild acquaintance with them. The major point to remember is
12124 that regular expressions permit you to search for patterns as well as
12125 for literal strings of characters. For example, the code in
12126 @code{forward-sentence} searches for the pattern of possible
12127 characters that could mark the end of a sentence, and moves point to
12130 Before looking at the code for the @code{forward-sentence} function, it
12131 is worth considering what the pattern that marks the end of a sentence
12132 must be. The pattern is discussed in the next section; following that
12133 is a description of the regular expression search function,
12134 @code{re-search-forward}. The @code{forward-sentence} function
12135 is described in the section following. Finally, the
12136 @code{forward-paragraph} function is described in the last section of
12137 this chapter. @code{forward-paragraph} is a complex function that
12138 introduces several new features.
12141 * sentence-end:: The regular expression for @code{sentence-end}.
12142 * re-search-forward:: Very similar to @code{search-forward}.
12143 * forward-sentence:: A straightforward example of regexp search.
12144 * forward-paragraph:: A somewhat complex example.
12145 * etags:: How to create your own @file{TAGS} table.
12147 * re-search Exercises::
12151 @section The Regular Expression for @code{sentence-end}
12152 @findex sentence-end
12154 The symbol @code{sentence-end} is bound to the pattern that marks the
12155 end of a sentence. What should this regular expression be?
12157 Clearly, a sentence may be ended by a period, a question mark, or an
12158 exclamation mark. Indeed, in English, only clauses that end with one
12159 of those three characters should be considered the end of a sentence.
12160 This means that the pattern should include the character set:
12166 However, we do not want @code{forward-sentence} merely to jump to a
12167 period, a question mark, or an exclamation mark, because such a character
12168 might be used in the middle of a sentence. A period, for example, is
12169 used after abbreviations. So other information is needed.
12171 According to convention, you type two spaces after every sentence, but
12172 only one space after a period, a question mark, or an exclamation mark in
12173 the body of a sentence. So a period, a question mark, or an exclamation
12174 mark followed by two spaces is a good indicator of an end of sentence.
12175 However, in a file, the two spaces may instead be a tab or the end of a
12176 line. This means that the regular expression should include these three
12177 items as alternatives.
12180 This group of alternatives will look like this:
12191 Here, @samp{$} indicates the end of the line, and I have pointed out
12192 where the tab and two spaces are inserted in the expression. Both are
12193 inserted by putting the actual characters into the expression.
12195 Two backslashes, @samp{\\}, are required before the parentheses and
12196 vertical bars: the first backslash quotes the following backslash in
12197 Emacs; and the second indicates that the following character, the
12198 parenthesis or the vertical bar, is special.
12201 Also, a sentence may be followed by one or more carriage returns, like
12212 Like tabs and spaces, a carriage return is inserted into a regular
12213 expression by inserting it literally. The asterisk indicates that the
12214 @key{RET} is repeated zero or more times.
12216 But a sentence end does not consist only of a period, a question mark or
12217 an exclamation mark followed by appropriate space: a closing quotation
12218 mark or a closing brace of some kind may precede the space. Indeed more
12219 than one such mark or brace may precede the space. These require a
12220 expression that looks like this:
12226 In this expression, the first @samp{]} is the first character in the
12227 expression; the second character is @samp{"}, which is preceded by a
12228 @samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last
12229 three characters are @samp{'}, @samp{)}, and @samp{@}}.
12231 All this suggests what the regular expression pattern for matching the
12232 end of a sentence should be; and, indeed, if we evaluate
12233 @code{sentence-end} we find that it returns the following value:
12238 @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[
12244 (Well, not in GNU Emacs 22; that is because of an effort to make the
12245 process simpler and to handle more glyphs and languages. When the
12246 value of @code{sentence-end} is @code{nil}, then use the value defined
12247 by the function @code{sentence-end}. (Here is a use of the difference
12248 between a value and a function in Emacs Lisp.) The function returns a
12249 value constructed from the variables @code{sentence-end-base},
12250 @code{sentence-end-double-space}, @code{sentence-end-without-period},
12251 and @code{sentence-end-without-space}. The critical variable is
12252 @code{sentence-end-base}; its global value is similar to the one
12253 described above but it also contains two additional quotation marks.
12254 These have differing degrees of curliness. The
12255 @code{sentence-end-without-period} variable, when true, tells Emacs
12256 that a sentence may end without a period, such as text in Thai.)
12260 (Note that here the @key{TAB}, two spaces, and @key{RET} are shown
12261 literally in the pattern.)
12263 This regular expression can be deciphered as follows:
12267 The first part of the pattern is the three characters, a period, a question
12268 mark and an exclamation mark, within square brackets. The pattern must
12269 begin with one or other of these characters.
12272 The second part of the pattern is the group of closing braces and
12273 quotation marks, which can appear zero or more times. These may follow
12274 the period, question mark or exclamation mark. In a regular expression,
12275 the backslash, @samp{\}, followed by the double quotation mark,
12276 @samp{"}, indicates the class of string-quote characters. Usually, the
12277 double quotation mark is the only character in this class. The
12278 asterisk, @samp{*}, indicates that the items in the previous group (the
12279 group surrounded by square brackets, @samp{[]}) may be repeated zero or
12282 @item \\($\\| \\| \\)
12283 The third part of the pattern is one or other of: either the end of a
12284 line, or two blank spaces, or a tab. The double back-slashes are used
12285 to prevent Emacs from reading the parentheses and vertical bars as part
12286 of the search pattern; the parentheses are used to mark the group and
12287 the vertical bars are used to indicated that the patterns to either side
12288 of them are alternatives. The dollar sign is used to indicate the end
12289 of a line and both the two spaces and the tab are each inserted as is to
12290 indicate what they are.
12293 Finally, the last part of the pattern indicates that the end of the line
12294 or the whitespace following the period, question mark or exclamation
12295 mark may, but need not, be followed by one or more carriage returns. In
12296 the pattern, the carriage return is inserted as an actual carriage
12297 return between square brackets but here it is shown as @key{RET}.
12301 @node re-search-forward
12302 @section The @code{re-search-forward} Function
12303 @findex re-search-forward
12305 The @code{re-search-forward} function is very like the
12306 @code{search-forward} function. (@xref{search-forward, , The
12307 @code{search-forward} Function}.)
12309 @code{re-search-forward} searches for a regular expression. If the
12310 search is successful, it leaves point immediately after the last
12311 character in the target. If the search is backwards, it leaves point
12312 just before the first character in the target. You may tell
12313 @code{re-search-forward} to return @code{t} for true. (Moving point
12314 is therefore a side effect.)
12316 Like @code{search-forward}, the @code{re-search-forward} function takes
12321 The first argument is the regular expression that the function searches
12322 for. The regular expression will be a string between quotation marks.
12325 The optional second argument limits how far the function will search; it is a
12326 bound, which is specified as a position in the buffer.
12329 The optional third argument specifies how the function responds to
12330 failure: @code{nil} as the third argument causes the function to
12331 signal an error (and print a message) when the search fails; any other
12332 value causes it to return @code{nil} if the search fails and @code{t}
12333 if the search succeeds.
12336 The optional fourth argument is the repeat count. A negative repeat
12337 count causes @code{re-search-forward} to search backwards.
12341 The template for @code{re-search-forward} looks like this:
12345 (re-search-forward "@var{regular-expression}"
12346 @var{limit-of-search}
12347 @var{what-to-do-if-search-fails}
12348 @var{repeat-count})
12352 The second, third, and fourth arguments are optional. However, if you
12353 want to pass a value to either or both of the last two arguments, you
12354 must also pass a value to all the preceding arguments. Otherwise, the
12355 Lisp interpreter will mistake which argument you are passing the value
12359 In the @code{forward-sentence} function, the regular expression will be
12360 the value of the variable @code{sentence-end}. In simple form, that is:
12364 "[.?!][]\"')@}]*\\($\\| \\| \\)[
12370 The limit of the search will be the end of the paragraph (since a
12371 sentence cannot go beyond a paragraph). If the search fails, the
12372 function will return @code{nil}; and the repeat count will be provided
12373 by the argument to the @code{forward-sentence} function.
12375 @node forward-sentence
12376 @section @code{forward-sentence}
12377 @findex forward-sentence
12379 The command to move the cursor forward a sentence is a straightforward
12380 illustration of how to use regular expression searches in Emacs Lisp.
12381 Indeed, the function looks longer and more complicated than it is; this
12382 is because the function is designed to go backwards as well as forwards;
12383 and, optionally, over more than one sentence. The function is usually
12384 bound to the key command @kbd{M-e}.
12387 * Complete forward-sentence::
12388 * fwd-sentence while loops:: Two @code{while} loops.
12389 * fwd-sentence re-search:: A regular expression search.
12393 @node Complete forward-sentence
12394 @unnumberedsubsec Complete @code{forward-sentence} function definition
12398 Here is the code for @code{forward-sentence}:
12403 (defun forward-sentence (&optional arg)
12404 "Move forward to next end of sentence. With argument, repeat.
12405 With negative argument, move backward repeatedly to start of sentence.
12407 The variable `sentence-end' is a regular expression that matches ends of
12408 sentences. Also, every paragraph boundary terminates sentences as well."
12412 (or arg (setq arg 1))
12413 (let ((opoint (point))
12414 (sentence-end (sentence-end)))
12416 (let ((pos (point))
12417 (par-beg (save-excursion (start-of-paragraph-text) (point))))
12418 (if (and (re-search-backward sentence-end par-beg t)
12419 (or (< (match-end 0) pos)
12420 (re-search-backward sentence-end par-beg t)))
12421 (goto-char (match-end 0))
12422 (goto-char par-beg)))
12423 (setq arg (1+ arg)))
12427 (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
12428 (if (re-search-forward sentence-end par-end t)
12429 (skip-chars-backward " \t\n")
12430 (goto-char par-end)))
12431 (setq arg (1- arg)))
12432 (constrain-to-field nil opoint t)))
12440 (defun forward-sentence (&optional arg)
12441 "Move forward to next sentence-end. With argument, repeat.
12442 With negative argument, move backward repeatedly to sentence-beginning.
12443 Sentence ends are identified by the value of sentence-end
12444 treated as a regular expression. Also, every paragraph boundary
12445 terminates sentences as well."
12449 (or arg (setq arg 1))
12452 (save-excursion (start-of-paragraph-text) (point))))
12453 (if (re-search-backward
12454 (concat sentence-end "[^ \t\n]") par-beg t)
12455 (goto-char (1- (match-end 0)))
12456 (goto-char par-beg)))
12457 (setq arg (1+ arg)))
12460 (save-excursion (end-of-paragraph-text) (point))))
12461 (if (re-search-forward sentence-end par-end t)
12462 (skip-chars-backward " \t\n")
12463 (goto-char par-end)))
12464 (setq arg (1- arg))))
12469 The function looks long at first sight and it is best to look at its
12470 skeleton first, and then its muscle. The way to see the skeleton is to
12471 look at the expressions that start in the left-most columns:
12475 (defun forward-sentence (&optional arg)
12476 "@var{documentation}@dots{}"
12478 (or arg (setq arg 1))
12479 (let ((opoint (point)) (sentence-end (sentence-end)))
12481 (let ((pos (point))
12482 (par-beg (save-excursion (start-of-paragraph-text) (point))))
12483 @var{rest-of-body-of-while-loop-when-going-backwards}
12485 (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
12486 @var{rest-of-body-of-while-loop-when-going-forwards}
12487 @var{handle-forms-and-equivalent}
12491 This looks much simpler! The function definition consists of
12492 documentation, an @code{interactive} expression, an @code{or}
12493 expression, a @code{let} expression, and @code{while} loops.
12495 Let's look at each of these parts in turn.
12497 We note that the documentation is thorough and understandable.
12499 The function has an @code{interactive "p"} declaration. This means
12500 that the processed prefix argument, if any, is passed to the
12501 function as its argument. (This will be a number.) If the function
12502 is not passed an argument (it is optional) then the argument
12503 @code{arg} will be bound to 1.
12505 When @code{forward-sentence} is called non-interactively without an
12506 argument, @code{arg} is bound to @code{nil}. The @code{or} expression
12507 handles this. What it does is either leave the value of @code{arg} as
12508 it is, but only if @code{arg} is bound to a value; or it sets the
12509 value of @code{arg} to 1, in the case when @code{arg} is bound to
12512 Next is a @code{let}. That specifies the values of two local
12513 variables, @code{opoint} and @code{sentence-end}. The local value of
12514 point, from before the search, is used in the
12515 @code{constrain-to-field} function which handles forms and
12516 equivalents. The @code{sentence-end} variable is set by the
12517 @code{sentence-end} function.
12519 @node fwd-sentence while loops
12520 @unnumberedsubsec The @code{while} loops
12522 Two @code{while} loops follow. The first @code{while} has a
12523 true-or-false-test that tests true if the prefix argument for
12524 @code{forward-sentence} is a negative number. This is for going
12525 backwards. The body of this loop is similar to the body of the second
12526 @code{while} clause, but it is not exactly the same. We will skip
12527 this @code{while} loop and concentrate on the second @code{while}
12531 The second @code{while} loop is for moving point forward. Its skeleton
12536 (while (> arg 0) ; @r{true-or-false-test}
12538 (if (@var{true-or-false-test})
12541 (setq arg (1- arg)))) ; @code{while} @r{loop decrementer}
12545 The @code{while} loop is of the decrementing kind.
12546 (@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It
12547 has a true-or-false-test that tests true so long as the counter (in
12548 this case, the variable @code{arg}) is greater than zero; and it has a
12549 decrementer that subtracts 1 from the value of the counter every time
12552 If no prefix argument is given to @code{forward-sentence}, which is
12553 the most common way the command is used, this @code{while} loop will
12554 run once, since the value of @code{arg} will be 1.
12556 The body of the @code{while} loop consists of a @code{let} expression,
12557 which creates and binds a local variable, and has, as its body, an
12558 @code{if} expression.
12561 The body of the @code{while} loop looks like this:
12566 (save-excursion (end-of-paragraph-text) (point))))
12567 (if (re-search-forward sentence-end par-end t)
12568 (skip-chars-backward " \t\n")
12569 (goto-char par-end)))
12573 The @code{let} expression creates and binds the local variable
12574 @code{par-end}. As we shall see, this local variable is designed to
12575 provide a bound or limit to the regular expression search. If the
12576 search fails to find a proper sentence ending in the paragraph, it will
12577 stop on reaching the end of the paragraph.
12579 But first, let us examine how @code{par-end} is bound to the value of
12580 the end of the paragraph. What happens is that the @code{let} sets the
12581 value of @code{par-end} to the value returned when the Lisp interpreter
12582 evaluates the expression
12586 (save-excursion (end-of-paragraph-text) (point))
12591 In this expression, @code{(end-of-paragraph-text)} moves point to the
12592 end of the paragraph, @code{(point)} returns the value of point, and then
12593 @code{save-excursion} restores point to its original position. Thus,
12594 the @code{let} binds @code{par-end} to the value returned by the
12595 @code{save-excursion} expression, which is the position of the end of
12596 the paragraph. (The @code{end-of-paragraph-text} function uses
12597 @code{forward-paragraph}, which we will discuss shortly.)
12600 Emacs next evaluates the body of the @code{let}, which is an @code{if}
12601 expression that looks like this:
12605 (if (re-search-forward sentence-end par-end t) ; @r{if-part}
12606 (skip-chars-backward " \t\n") ; @r{then-part}
12607 (goto-char par-end))) ; @r{else-part}
12611 The @code{if} tests whether its first argument is true and if so,
12612 evaluates its then-part; otherwise, the Emacs Lisp interpreter
12613 evaluates the else-part. The true-or-false-test of the @code{if}
12614 expression is the regular expression search.
12616 It may seem odd to have what looks like the real work of
12617 the @code{forward-sentence} function buried here, but this is a common
12618 way this kind of operation is carried out in Lisp.
12620 @node fwd-sentence re-search
12621 @unnumberedsubsec The regular expression search
12623 The @code{re-search-forward} function searches for the end of the
12624 sentence, that is, for the pattern defined by the @code{sentence-end}
12625 regular expression. If the pattern is found---if the end of the sentence is
12626 found---then the @code{re-search-forward} function does two things:
12630 The @code{re-search-forward} function carries out a side effect, which
12631 is to move point to the end of the occurrence found.
12634 The @code{re-search-forward} function returns a value of true. This is
12635 the value received by the @code{if}, and means that the search was
12640 The side effect, the movement of point, is completed before the
12641 @code{if} function is handed the value returned by the successful
12642 conclusion of the search.
12644 When the @code{if} function receives the value of true from a successful
12645 call to @code{re-search-forward}, the @code{if} evaluates the then-part,
12646 which is the expression @code{(skip-chars-backward " \t\n")}. This
12647 expression moves backwards over any blank spaces, tabs or carriage
12648 returns until a printed character is found and then leaves point after
12649 the character. Since point has already been moved to the end of the
12650 pattern that marks the end of the sentence, this action leaves point
12651 right after the closing printed character of the sentence, which is
12654 On the other hand, if the @code{re-search-forward} function fails to
12655 find a pattern marking the end of the sentence, the function returns
12656 false. The false then causes the @code{if} to evaluate its third
12657 argument, which is @code{(goto-char par-end)}: it moves point to the
12658 end of the paragraph.
12660 (And if the text is in a form or equivalent, and point may not move
12661 fully, then the @code{constrain-to-field} function comes into play.)
12663 Regular expression searches are exceptionally useful and the pattern
12664 illustrated by @code{re-search-forward}, in which the search is the
12665 test of an @code{if} expression, is handy. You will see or write code
12666 incorporating this pattern often.
12668 @node forward-paragraph
12669 @section @code{forward-paragraph}: a Goldmine of Functions
12670 @findex forward-paragraph
12674 (defun forward-paragraph (&optional arg)
12675 "Move forward to end of paragraph.
12676 With argument ARG, do it ARG times;
12677 a negative argument ARG = -N means move backward N paragraphs.
12679 A line which `paragraph-start' matches either separates paragraphs
12680 \(if `paragraph-separate' matches it also) or is the first line of a paragraph.
12681 A paragraph end is the beginning of a line which is not part of the paragraph
12682 to which the end of the previous line belongs, or the end of the buffer.
12683 Returns the count of paragraphs left to move."
12685 (or arg (setq arg 1))
12686 (let* ((opoint (point))
12687 (fill-prefix-regexp
12688 (and fill-prefix (not (equal fill-prefix ""))
12689 (not paragraph-ignore-fill-prefix)
12690 (regexp-quote fill-prefix)))
12691 ;; Remove ^ from paragraph-start and paragraph-sep if they are there.
12692 ;; These regexps shouldn't be anchored, because we look for them
12693 ;; starting at the left-margin. This allows paragraph commands to
12694 ;; work normally with indented text.
12695 ;; This hack will not find problem cases like "whatever\\|^something".
12696 (parstart (if (and (not (equal "" paragraph-start))
12697 (equal ?^ (aref paragraph-start 0)))
12698 (substring paragraph-start 1)
12700 (parsep (if (and (not (equal "" paragraph-separate))
12701 (equal ?^ (aref paragraph-separate 0)))
12702 (substring paragraph-separate 1)
12703 paragraph-separate))
12705 (if fill-prefix-regexp
12706 (concat parsep "\\|"
12707 fill-prefix-regexp "[ \t]*$")
12709 ;; This is used for searching.
12710 (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)"))
12712 (while (and (< arg 0) (not (bobp)))
12713 (if (and (not (looking-at parsep))
12714 (re-search-backward "^\n" (max (1- (point)) (point-min)) t)
12715 (looking-at parsep))
12716 (setq arg (1+ arg))
12717 (setq start (point))
12718 ;; Move back over paragraph-separating lines.
12719 (forward-char -1) (beginning-of-line)
12720 (while (and (not (bobp))
12721 (progn (move-to-left-margin)
12722 (looking-at parsep)))
12726 (setq arg (1+ arg))
12727 ;; Go to end of the previous (non-separating) line.
12729 ;; Search back for line that starts or separates paragraphs.
12730 (if (if fill-prefix-regexp
12731 ;; There is a fill prefix; it overrides parstart.
12732 (let (multiple-lines)
12733 (while (and (progn (beginning-of-line) (not (bobp)))
12734 (progn (move-to-left-margin)
12735 (not (looking-at parsep)))
12736 (looking-at fill-prefix-regexp))
12737 (unless (= (point) start)
12738 (setq multiple-lines t))
12740 (move-to-left-margin)
12741 ;; This deleted code caused a long hanging-indent line
12742 ;; not to be filled together with the following lines.
12743 ;; ;; Don't move back over a line before the paragraph
12744 ;; ;; which doesn't start with fill-prefix
12745 ;; ;; unless that is the only line we've moved over.
12746 ;; (and (not (looking-at fill-prefix-regexp))
12748 ;; (forward-line 1))
12750 (while (and (re-search-backward sp-parstart nil 1)
12751 (setq found-start t)
12752 ;; Found a candidate, but need to check if it is a
12754 (progn (setq start (point))
12755 (move-to-left-margin)
12756 (not (looking-at parsep)))
12757 (not (and (looking-at parstart)
12758 (or (not use-hard-newlines)
12761 (1- start) 'hard)))))
12762 (setq found-start nil)
12767 ;; Move forward over paragraph separators.
12768 ;; We know this cannot reach the place we started
12769 ;; because we know we moved back over a non-separator.
12770 (while (and (not (eobp))
12771 (progn (move-to-left-margin)
12772 (looking-at parsep)))
12774 ;; If line before paragraph is just margin, back up to there.
12776 (if (> (current-column) (current-left-margin))
12778 (skip-chars-backward " \t")
12780 (forward-line 1))))
12781 ;; No starter or separator line => use buffer beg.
12782 (goto-char (point-min))))))
12784 (while (and (> arg 0) (not (eobp)))
12785 ;; Move forward over separator lines...
12786 (while (and (not (eobp))
12787 (progn (move-to-left-margin) (not (eobp)))
12788 (looking-at parsep))
12790 (unless (eobp) (setq arg (1- arg)))
12791 ;; ... and one more line.
12793 (if fill-prefix-regexp
12794 ;; There is a fill prefix; it overrides parstart.
12795 (while (and (not (eobp))
12796 (progn (move-to-left-margin) (not (eobp)))
12797 (not (looking-at parsep))
12798 (looking-at fill-prefix-regexp))
12800 (while (and (re-search-forward sp-parstart nil 1)
12801 (progn (setq start (match-beginning 0))
12804 (progn (move-to-left-margin)
12805 (not (looking-at parsep)))
12806 (or (not (looking-at parstart))
12807 (and use-hard-newlines
12808 (not (get-text-property (1- start) 'hard)))))
12810 (if (< (point) (point-max))
12811 (goto-char start))))
12812 (constrain-to-field nil opoint t)
12813 ;; Return the number of steps that could not be done.
12817 The @code{forward-paragraph} function moves point forward to the end
12818 of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a
12819 number of functions that are important in themselves, including
12820 @code{let*}, @code{match-beginning}, and @code{looking-at}.
12822 The function definition for @code{forward-paragraph} is considerably
12823 longer than the function definition for @code{forward-sentence}
12824 because it works with a paragraph, each line of which may begin with a
12827 A fill prefix consists of a string of characters that are repeated at
12828 the beginning of each line. For example, in Lisp code, it is a
12829 convention to start each line of a paragraph-long comment with
12830 @samp{;;; }. In Text mode, four blank spaces make up another common
12831 fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , ,
12832 emacs, The GNU Emacs Manual}, for more information about fill
12835 The existence of a fill prefix means that in addition to being able to
12836 find the end of a paragraph whose lines begin on the left-most
12837 column, the @code{forward-paragraph} function must be able to find the
12838 end of a paragraph when all or many of the lines in the buffer begin
12839 with the fill prefix.
12841 Moreover, it is sometimes practical to ignore a fill prefix that
12842 exists, especially when blank lines separate paragraphs.
12843 This is an added complication.
12846 * forward-paragraph in brief:: Key parts of the function definition.
12847 * fwd-para let:: The @code{let*} expression.
12848 * fwd-para while:: The forward motion @code{while} loop.
12852 @node forward-paragraph in brief
12853 @unnumberedsubsec Shortened @code{forward-paragraph} function definition
12856 Rather than print all of the @code{forward-paragraph} function, we
12857 will only print parts of it. Read without preparation, the function
12861 In outline, the function looks like this:
12865 (defun forward-paragraph (&optional arg)
12866 "@var{documentation}@dots{}"
12868 (or arg (setq arg 1))
12871 (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code}
12873 (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code}
12878 The first parts of the function are routine: the function's argument
12879 list consists of one optional argument. Documentation follows.
12881 The lower case @samp{p} in the @code{interactive} declaration means
12882 that the processed prefix argument, if any, is passed to the function.
12883 This will be a number, and is the repeat count of how many paragraphs
12884 point will move. The @code{or} expression in the next line handles
12885 the common case when no argument is passed to the function, which occurs
12886 if the function is called from other code rather than interactively.
12887 This case was described earlier. (@xref{forward-sentence, The
12888 @code{forward-sentence} function}.) Now we reach the end of the
12889 familiar part of this function.
12892 @unnumberedsubsec The @code{let*} expression
12894 The next line of the @code{forward-paragraph} function begins a
12895 @code{let*} expression. This is a different than @code{let}. The
12896 symbol is @code{let*} not @code{let}.
12899 The @code{let*} special form is like @code{let} except that Emacs sets
12900 each variable in sequence, one after another, and variables in the
12901 latter part of the varlist can make use of the values to which Emacs
12902 set variables in the earlier part of the varlist.
12905 ( refappend save-excursion, , code save-excursion in code append-to-buffer .)
12908 (@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.)
12910 In the @code{let*} expression in this function, Emacs binds a total of
12911 seven variables: @code{opoint}, @code{fill-prefix-regexp},
12912 @code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and
12913 @code{found-start}.
12915 The variable @code{parsep} appears twice, first, to remove instances
12916 of @samp{^}, and second, to handle fill prefixes.
12918 The variable @code{opoint} is just the value of @code{point}. As you
12919 can guess, it is used in a @code{constrain-to-field} expression, just
12920 as in @code{forward-sentence}.
12922 The variable @code{fill-prefix-regexp} is set to the value returned by
12923 evaluating the following list:
12928 (not (equal fill-prefix ""))
12929 (not paragraph-ignore-fill-prefix)
12930 (regexp-quote fill-prefix))
12935 This is an expression whose first element is the @code{and} special form.
12937 As we learned earlier (@pxref{kill-new function, , The @code{kill-new}
12938 function}), the @code{and} special form evaluates each of its
12939 arguments until one of the arguments returns a value of @code{nil}, in
12940 which case the @code{and} expression returns @code{nil}; however, if
12941 none of the arguments returns a value of @code{nil}, the value
12942 resulting from evaluating the last argument is returned. (Since such
12943 a value is not @code{nil}, it is considered true in Lisp.) In other
12944 words, an @code{and} expression returns a true value only if all its
12945 arguments are true.
12948 In this case, the variable @code{fill-prefix-regexp} is bound to a
12949 non-@code{nil} value only if the following four expressions produce a
12950 true (i.e., a non-@code{nil}) value when they are evaluated; otherwise,
12951 @code{fill-prefix-regexp} is bound to @code{nil}.
12955 When this variable is evaluated, the value of the fill prefix, if any,
12956 is returned. If there is no fill prefix, this variable returns
12959 @item (not (equal fill-prefix "")
12960 This expression checks whether an existing fill prefix is an empty
12961 string, that is, a string with no characters in it. An empty string is
12962 not a useful fill prefix.
12964 @item (not paragraph-ignore-fill-prefix)
12965 This expression returns @code{nil} if the variable
12966 @code{paragraph-ignore-fill-prefix} has been turned on by being set to a
12967 true value such as @code{t}.
12969 @item (regexp-quote fill-prefix)
12970 This is the last argument to the @code{and} special form. If all the
12971 arguments to the @code{and} are true, the value resulting from
12972 evaluating this expression will be returned by the @code{and} expression
12973 and bound to the variable @code{fill-prefix-regexp},
12976 @findex regexp-quote
12978 The result of evaluating this @code{and} expression successfully is that
12979 @code{fill-prefix-regexp} will be bound to the value of
12980 @code{fill-prefix} as modified by the @code{regexp-quote} function.
12981 What @code{regexp-quote} does is read a string and return a regular
12982 expression that will exactly match the string and match nothing else.
12983 This means that @code{fill-prefix-regexp} will be set to a value that
12984 will exactly match the fill prefix if the fill prefix exists.
12985 Otherwise, the variable will be set to @code{nil}.
12987 The next two local variables in the @code{let*} expression are
12988 designed to remove instances of @samp{^} from @code{parstart} and
12989 @code{parsep}, the local variables which indicate the paragraph start
12990 and the paragraph separator. The next expression sets @code{parsep}
12991 again. That is to handle fill prefixes.
12993 This is the setting that requires the definition call @code{let*}
12994 rather than @code{let}. The true-or-false-test for the @code{if}
12995 depends on whether the variable @code{fill-prefix-regexp} evaluates to
12996 @code{nil} or some other value.
12998 If @code{fill-prefix-regexp} does not have a value, Emacs evaluates
12999 the else-part of the @code{if} expression and binds @code{parsep} to
13000 its local value. (@code{parsep} is a regular expression that matches
13001 what separates paragraphs.)
13003 But if @code{fill-prefix-regexp} does have a value, Emacs evaluates
13004 the then-part of the @code{if} expression and binds @code{parsep} to a
13005 regular expression that includes the @code{fill-prefix-regexp} as part
13008 Specifically, @code{parsep} is set to the original value of the
13009 paragraph separate regular expression concatenated with an alternative
13010 expression that consists of the @code{fill-prefix-regexp} followed by
13011 optional whitespace to the end of the line. The whitespace is defined
13012 by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the
13013 regexp as an alternative to @code{parsep}.
13015 According to a comment in the code, the next local variable,
13016 @code{sp-parstart}, is used for searching, and then the final two,
13017 @code{start} and @code{found-start}, are set to @code{nil}.
13019 Now we get into the body of the @code{let*}. The first part of the body
13020 of the @code{let*} deals with the case when the function is given a
13021 negative argument and is therefore moving backwards. We will skip this
13024 @node fwd-para while
13025 @unnumberedsubsec The forward motion @code{while} loop
13027 The second part of the body of the @code{let*} deals with forward
13028 motion. It is a @code{while} loop that repeats itself so long as the
13029 value of @code{arg} is greater than zero. In the most common use of
13030 the function, the value of the argument is 1, so the body of the
13031 @code{while} loop is evaluated exactly once, and the cursor moves
13032 forward one paragraph.
13035 (while (and (> arg 0) (not (eobp)))
13037 ;; Move forward over separator lines...
13038 (while (and (not (eobp))
13039 (progn (move-to-left-margin) (not (eobp)))
13040 (looking-at parsep))
13042 (unless (eobp) (setq arg (1- arg)))
13043 ;; ... and one more line.
13046 (if fill-prefix-regexp
13047 ;; There is a fill prefix; it overrides parstart.
13048 (while (and (not (eobp))
13049 (progn (move-to-left-margin) (not (eobp)))
13050 (not (looking-at parsep))
13051 (looking-at fill-prefix-regexp))
13054 (while (and (re-search-forward sp-parstart nil 1)
13055 (progn (setq start (match-beginning 0))
13058 (progn (move-to-left-margin)
13059 (not (looking-at parsep)))
13060 (or (not (looking-at parstart))
13061 (and use-hard-newlines
13062 (not (get-text-property (1- start) 'hard)))))
13065 (if (< (point) (point-max))
13066 (goto-char start))))
13069 This part handles three situations: when point is between paragraphs,
13070 when there is a fill prefix and when there is no fill prefix.
13073 The @code{while} loop looks like this:
13077 ;; @r{going forwards and not at the end of the buffer}
13078 (while (and (> arg 0) (not (eobp)))
13080 ;; @r{between paragraphs}
13081 ;; Move forward over separator lines...
13082 (while (and (not (eobp))
13083 (progn (move-to-left-margin) (not (eobp)))
13084 (looking-at parsep))
13086 ;; @r{This decrements the loop}
13087 (unless (eobp) (setq arg (1- arg)))
13088 ;; ... and one more line.
13093 (if fill-prefix-regexp
13094 ;; There is a fill prefix; it overrides parstart;
13095 ;; we go forward line by line
13096 (while (and (not (eobp))
13097 (progn (move-to-left-margin) (not (eobp)))
13098 (not (looking-at parsep))
13099 (looking-at fill-prefix-regexp))
13104 ;; There is no fill prefix;
13105 ;; we go forward character by character
13106 (while (and (re-search-forward sp-parstart nil 1)
13107 (progn (setq start (match-beginning 0))
13110 (progn (move-to-left-margin)
13111 (not (looking-at parsep)))
13112 (or (not (looking-at parstart))
13113 (and use-hard-newlines
13114 (not (get-text-property (1- start) 'hard)))))
13119 ;; and if there is no fill prefix and if we are not at the end,
13120 ;; go to whatever was found in the regular expression search
13122 (if (< (point) (point-max))
13123 (goto-char start))))
13128 We can see that this is a decrementing counter @code{while} loop,
13129 using the expression @code{(setq arg (1- arg))} as the decrementer.
13130 That expression is not far from the @code{while}, but is hidden in
13131 another Lisp macro, an @code{unless} macro. Unless we are at the end
13132 of the buffer---that is what the @code{eobp} function determines; it
13133 is an abbreviation of @samp{End Of Buffer P}---we decrease the value
13134 of @code{arg} by one.
13136 (If we are at the end of the buffer, we cannot go forward any more and
13137 the next loop of the @code{while} expression will test false since the
13138 test is an @code{and} with @code{(not (eobp))}. The @code{not}
13139 function means exactly as you expect; it is another name for
13140 @code{null}, a function that returns true when its argument is false.)
13142 Interestingly, the loop count is not decremented until we leave the
13143 space between paragraphs, unless we come to the end of buffer or stop
13144 seeing the local value of the paragraph separator.
13146 That second @code{while} also has a @code{(move-to-left-margin)}
13147 expression. The function is self-explanatory. It is inside a
13148 @code{progn} expression and not the last element of its body, so it is
13149 only invoked for its side effect, which is to move point to the left
13150 margin of the current line.
13153 The @code{looking-at} function is also self-explanatory; it returns
13154 true if the text after point matches the regular expression given as
13157 The rest of the body of the loop looks difficult at first, but makes
13158 sense as you come to understand it.
13161 First consider what happens if there is a fill prefix:
13165 (if fill-prefix-regexp
13166 ;; There is a fill prefix; it overrides parstart;
13167 ;; we go forward line by line
13168 (while (and (not (eobp))
13169 (progn (move-to-left-margin) (not (eobp)))
13170 (not (looking-at parsep))
13171 (looking-at fill-prefix-regexp))
13177 This expression moves point forward line by line so long
13178 as four conditions are true:
13182 Point is not at the end of the buffer.
13185 We can move to the left margin of the text and are
13186 not at the end of the buffer.
13189 The text following point does not separate paragraphs.
13192 The pattern following point is the fill prefix regular expression.
13195 The last condition may be puzzling, until you remember that point was
13196 moved to the beginning of the line early in the @code{forward-paragraph}
13197 function. This means that if the text has a fill prefix, the
13198 @code{looking-at} function will see it.
13201 Consider what happens when there is no fill prefix.
13205 (while (and (re-search-forward sp-parstart nil 1)
13206 (progn (setq start (match-beginning 0))
13209 (progn (move-to-left-margin)
13210 (not (looking-at parsep)))
13211 (or (not (looking-at parstart))
13212 (and use-hard-newlines
13213 (not (get-text-property (1- start) 'hard)))))
13219 This @code{while} loop has us searching forward for
13220 @code{sp-parstart}, which is the combination of possible whitespace
13221 with the local value of the start of a paragraph or of a paragraph
13222 separator. (The latter two are within an expression starting
13223 @code{\(?:} so that they are not referenced by the
13224 @code{match-beginning} function.)
13227 The two expressions,
13231 (setq start (match-beginning 0))
13237 mean go to the start of the text matched by the regular expression
13240 The @code{(match-beginning 0)} expression is new. It returns a number
13241 specifying the location of the start of the text that was matched by
13244 The @code{match-beginning} function is used here because of a
13245 characteristic of a forward search: a successful forward search,
13246 regardless of whether it is a plain search or a regular expression
13247 search, moves point to the end of the text that is found. In this
13248 case, a successful search moves point to the end of the pattern for
13249 @code{sp-parstart}.
13251 However, we want to put point at the end of the current paragraph, not
13252 somewhere else. Indeed, since the search possibly includes the
13253 paragraph separator, point may end up at the beginning of the next one
13254 unless we use an expression that includes @code{match-beginning}.
13256 @findex match-beginning
13257 When given an argument of 0, @code{match-beginning} returns the
13258 position that is the start of the text matched by the most recent
13259 search. In this case, the most recent search looks for
13260 @code{sp-parstart}. The @code{(match-beginning 0)} expression returns
13261 the beginning position of that pattern, rather than the end position
13264 (Incidentally, when passed a positive number as an argument, the
13265 @code{match-beginning} function returns the location of point at that
13266 parenthesized expression in the last search unless that parenthesized
13267 expression begins with @code{\(?:}. I don't know why @code{\(?:}
13268 appears here since the argument is 0.)
13271 The last expression when there is no fill prefix is
13275 (if (< (point) (point-max))
13276 (goto-char start))))
13281 This says that if there is no fill prefix and if we are not at the
13282 end, point should move to the beginning of whatever was found by the
13283 regular expression search for @code{sp-parstart}.
13285 The full definition for the @code{forward-paragraph} function not only
13286 includes code for going forwards, but also code for going backwards.
13288 If you are reading this inside of GNU Emacs and you want to see the
13289 whole function, you can type @kbd{C-h f} (@code{describe-function})
13290 and the name of the function. This gives you the function
13291 documentation and the name of the library containing the function's
13292 source. Place point over the name of the library and press the RET
13293 key; you will be taken directly to the source. (Be sure to install
13294 your sources! Without them, you are like a person who tries to drive
13295 a car with his eyes shut!)
13298 @section Create Your Own @file{TAGS} File
13300 @cindex @file{TAGS} file, create own
13302 Besides @kbd{C-h f} (@code{describe-function}), another way to see the
13303 source of a function is to type @kbd{M-.} (@code{find-tag}) and the
13304 name of the function when prompted for it. This is a good habit to
13305 get into. The @kbd{M-.} (@code{find-tag}) command takes you directly
13306 to the source for a function, variable, or node. The function depends
13307 on tags tables to tell it where to go.
13309 If the @code{find-tag} function first asks you for the name of a
13310 @file{TAGS} table, give it the name of a @file{TAGS} file such as
13311 @file{/usr/local/src/emacs/src/TAGS}. (The exact path to your
13312 @file{TAGS} file depends on how your copy of Emacs was installed. I
13313 just told you the location that provides both my C and my Emacs Lisp
13316 You can also create your own @file{TAGS} file for directories that
13319 You often need to build and install tags tables yourself. They are
13320 not built automatically. A tags table is called a @file{TAGS} file;
13321 the name is in upper case letters.
13323 You can create a @file{TAGS} file by calling the @code{etags} program
13324 that comes as a part of the Emacs distribution. Usually, @code{etags}
13325 is compiled and installed when Emacs is built. (@code{etags} is not
13326 an Emacs Lisp function or a part of Emacs; it is a C program.)
13329 To create a @file{TAGS} file, first switch to the directory in which
13330 you want to create the file. In Emacs you can do this with the
13331 @kbd{M-x cd} command, or by visiting a file in the directory, or by
13332 listing the directory with @kbd{C-x d} (@code{dired}). Then run the
13333 compile command, with @w{@code{etags *.el}} as the command to execute
13336 M-x compile RET etags *.el RET
13340 to create a @file{TAGS} file for Emacs Lisp.
13342 For example, if you have a large number of files in your
13343 @file{~/emacs} directory, as I do---I have 137 @file{.el} files in it,
13344 of which I load 12---you can create a @file{TAGS} file for the Emacs
13345 Lisp files in that directory.
13348 The @code{etags} program takes all the usual shell wildcards. For
13349 example, if you have two directories for which you want a single
13350 @file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where
13351 @file{../elisp/} is the second directory:
13354 M-x compile RET etags *.el ../elisp/*.el RET
13361 M-x compile RET etags --help RET
13365 to see a list of the options accepted by @code{etags} as well as a
13366 list of supported languages.
13368 The @code{etags} program handles more than 20 languages, including
13369 Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java,
13370 LaTeX, Pascal, Perl, PostScript, Python, TeX, Texinfo, makefiles, and
13371 most assemblers. The program has no switches for specifying the
13372 language; it recognizes the language in an input file according to its
13373 file name and contents.
13375 @file{etags} is very helpful when you are writing code yourself and
13376 want to refer back to functions you have already written. Just run
13377 @code{etags} again at intervals as you write new functions, so they
13378 become part of the @file{TAGS} file.
13380 If you think an appropriate @file{TAGS} file already exists for what
13381 you want, but do not know where it is, you can use the @code{locate}
13382 program to attempt to find it.
13384 Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list
13385 for you the full path names of all your @file{TAGS} files. On my
13386 system, this command lists 34 @file{TAGS} files. On the other hand, a
13387 plain vanilla system I recently installed did not contain any
13390 If the tags table you want has been created, you can use the @code{M-x
13391 visit-tags-table} command to specify it. Otherwise, you will need to
13392 create the tag table yourself and then use @code{M-x
13395 @subsubheading Building Tags in the Emacs sources
13396 @cindex Building Tags in the Emacs sources
13397 @cindex Tags in the Emacs sources
13400 The GNU Emacs sources come with a @file{Makefile} that contains a
13401 sophisticated @code{etags} command that creates, collects, and merges
13402 tags tables from all over the Emacs sources and puts the information
13403 into one @file{TAGS} file in the @file{src/} directory. (The
13404 @file{src/} directory is below the top level of your Emacs directory.)
13407 To build this @file{TAGS} file, go to the top level of your Emacs
13408 source directory and run the compile command @code{make tags}:
13411 M-x compile RET make tags RET
13415 (The @code{make tags} command works well with the GNU Emacs sources,
13416 as well as with some other source packages.)
13418 For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs
13421 @node Regexp Review
13424 Here is a brief summary of some recently introduced functions.
13428 Repeatedly evaluate the body of the expression so long as the first
13429 element of the body tests true. Then return @code{nil}. (The
13430 expression is evaluated only for its side effects.)
13439 (insert (format "foo is %d.\n" foo))
13440 (setq foo (1- foo))))
13442 @result{} foo is 2.
13449 (The @code{insert} function inserts its arguments at point; the
13450 @code{format} function returns a string formatted from its arguments
13451 the way @code{message} formats its arguments; @code{\n} produces a new
13454 @item re-search-forward
13455 Search for a pattern, and if the pattern is found, move point to rest
13459 Takes four arguments, like @code{search-forward}:
13463 A regular expression that specifies the pattern to search for.
13464 (Remember to put quotation marks around this argument!)
13467 Optionally, the limit of the search.
13470 Optionally, what to do if the search fails, return @code{nil} or an
13474 Optionally, how many times to repeat the search; if negative, the
13475 search goes backwards.
13479 Bind some variables locally to particular values,
13480 and then evaluate the remaining arguments, returning the value of the
13481 last one. While binding the local variables, use the local values of
13482 variables bound earlier, if any.
13491 (message "`bar' is %d." bar))
13492 @result{} ‘bar’ is 21.
13496 @item match-beginning
13497 Return the position of the start of the text found by the last regular
13501 Return @code{t} for true if the text after point matches the argument,
13502 which should be a regular expression.
13505 Return @code{t} for true if point is at the end of the accessible part
13506 of a buffer. The end of the accessible part is the end of the buffer
13507 if the buffer is not narrowed; it is the end of the narrowed part if
13508 the buffer is narrowed.
13512 @node re-search Exercises
13513 @section Exercises with @code{re-search-forward}
13517 Write a function to search for a regular expression that matches two
13518 or more blank lines in sequence.
13521 Write a function to search for duplicated words, such as ``the the''.
13522 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
13523 Manual}, for information on how to write a regexp (a regular
13524 expression) to match a string that is composed of two identical
13525 halves. You can devise several regexps; some are better than others.
13526 The function I use is described in an appendix, along with several
13527 regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}.
13530 @node Counting Words
13531 @chapter Counting via Repetition and Regexps
13532 @cindex Repetition for word counting
13533 @cindex Regular expressions for word counting
13535 Repetition and regular expression searches are powerful tools that you
13536 often use when you write code in Emacs Lisp. This chapter illustrates
13537 the use of regular expression searches through the construction of
13538 word count commands using @code{while} loops and recursion.
13541 * Why Count Words::
13542 * @value{COUNT-WORDS}:: Use a regexp, but find a problem.
13543 * recursive-count-words:: Start with case of no words in region.
13544 * Counting Exercise::
13548 @node Why Count Words
13549 @unnumberedsec Counting words
13552 The standard Emacs distribution contains functions for counting the
13553 number of lines and words within a region.
13555 Certain types of writing ask you to count words. Thus, if you write
13556 an essay, you may be limited to 800 words; if you write a novel, you
13557 may discipline yourself to write 1000 words a day. It seems odd, but
13558 for a long time, Emacs lacked a word count command. Perhaps people used
13559 Emacs mostly for code or types of documentation that did not require
13560 word counts; or perhaps they restricted themselves to the operating
13561 system word count command, @code{wc}. Alternatively, people may have
13562 followed the publishers' convention and computed a word count by
13563 dividing the number of characters in a document by five.
13565 There are many ways to implement a command to count words. Here are
13566 some examples, which you may wish to compare with the standard Emacs
13567 command, @code{count-words-region}.
13569 @node @value{COUNT-WORDS}
13570 @section The @code{@value{COUNT-WORDS}} Function
13571 @findex @value{COUNT-WORDS}
13573 A word count command could count words in a line, paragraph, region,
13574 or buffer. What should the command cover? You could design the
13575 command to count the number of words in a complete buffer. However,
13576 the Emacs tradition encourages flexibility---you may want to count
13577 words in just a section, rather than all of a buffer. So it makes
13578 more sense to design the command to count the number of words in a
13579 region. Once you have a command to count words in a region, you can,
13580 if you wish, count words in a whole buffer by marking it with
13581 @w{@kbd{C-x h}} (@code{mark-whole-buffer}).
13583 Clearly, counting words is a repetitive act: starting from the
13584 beginning of the region, you count the first word, then the second
13585 word, then the third word, and so on, until you reach the end of the
13586 region. This means that word counting is ideally suited to recursion
13587 or to a @code{while} loop.
13590 * Design @value{COUNT-WORDS}:: The definition using a @code{while} loop.
13591 * Whitespace Bug:: The Whitespace Bug in @code{@value{COUNT-WORDS}}.
13595 @node Design @value{COUNT-WORDS}
13596 @unnumberedsubsec Designing @code{@value{COUNT-WORDS}}
13599 First, we will implement the word count command with a @code{while}
13600 loop, then with recursion. The command will, of course, be
13604 The template for an interactive function definition is, as always:
13608 (defun @var{name-of-function} (@var{argument-list})
13609 "@var{documentation}@dots{}"
13610 (@var{interactive-expression}@dots{})
13615 What we need to do is fill in the slots.
13617 The name of the function should be self-explanatory and similar to the
13618 existing @code{count-lines-region} name. This makes the name easier
13619 to remember. @code{count-words-region} is the obvious choice. Since
13620 that name is now used for the standard Emacs command to count words, we
13621 will name our implementation @code{@value{COUNT-WORDS}}.
13623 The function counts words within a region. This means that the
13624 argument list must contain symbols that are bound to the two
13625 positions, the beginning and end of the region. These two positions
13626 can be called @samp{beginning} and @samp{end} respectively. The first
13627 line of the documentation should be a single sentence, since that is
13628 all that is printed as documentation by a command such as
13629 @code{apropos}. The interactive expression will be of the form
13630 @samp{(interactive "r")}, since that will cause Emacs to pass the
13631 beginning and end of the region to the function's argument list. All
13634 The body of the function needs to be written to do three tasks:
13635 first, to set up conditions under which the @code{while} loop can
13636 count words, second, to run the @code{while} loop, and third, to send
13637 a message to the user.
13639 When a user calls @code{@value{COUNT-WORDS}}, point may be at the
13640 beginning or the end of the region. However, the counting process
13641 must start at the beginning of the region. This means we will want
13642 to put point there if it is not already there. Executing
13643 @code{(goto-char beginning)} ensures this. Of course, we will want to
13644 return point to its expected position when the function finishes its
13645 work. For this reason, the body must be enclosed in a
13646 @code{save-excursion} expression.
13648 The central part of the body of the function consists of a
13649 @code{while} loop in which one expression jumps point forward word by
13650 word, and another expression counts those jumps. The true-or-false-test
13651 of the @code{while} loop should test true so long as point should jump
13652 forward, and false when point is at the end of the region.
13654 We could use @code{(forward-word 1)} as the expression for moving point
13655 forward word by word, but it is easier to see what Emacs identifies as a
13656 ``word'' if we use a regular expression search.
13658 A regular expression search that finds the pattern for which it is
13659 searching leaves point after the last character matched. This means
13660 that a succession of successful word searches will move point forward
13663 As a practical matter, we want the regular expression search to jump
13664 over whitespace and punctuation between words as well as over the
13665 words themselves. A regexp that refuses to jump over interword
13666 whitespace would never jump more than one word! This means that
13667 the regexp should include the whitespace and punctuation that follows
13668 a word, if any, as well as the word itself. (A word may end a buffer
13669 and not have any following whitespace or punctuation, so that part of
13670 the regexp must be optional.)
13672 Thus, what we want for the regexp is a pattern defining one or more
13673 word constituent characters followed, optionally, by one or more
13674 characters that are not word constituents. The regular expression for
13682 The buffer's syntax table determines which characters are and are not
13683 word constituents. For more information about syntax,
13684 @pxref{Syntax Tables, , Syntax Tables, elisp, The GNU Emacs Lisp
13688 The search expression looks like this:
13691 (re-search-forward "\\w+\\W*")
13695 (Note that paired backslashes precede the @samp{w} and @samp{W}. A
13696 single backslash has special meaning to the Emacs Lisp interpreter.
13697 It indicates that the following character is interpreted differently
13698 than usual. For example, the two characters, @samp{\n}, stand for
13699 @samp{newline}, rather than for a backslash followed by @samp{n}. Two
13700 backslashes in a row stand for an ordinary, unspecial backslash, so
13701 Emacs Lisp interpreter ends of seeing a single backslash followed by a
13702 letter. So it discovers the letter is special.)
13704 We need a counter to count how many words there are; this variable
13705 must first be set to 0 and then incremented each time Emacs goes
13706 around the @code{while} loop. The incrementing expression is simply:
13709 (setq count (1+ count))
13712 Finally, we want to tell the user how many words there are in the
13713 region. The @code{message} function is intended for presenting this
13714 kind of information to the user. The message has to be phrased so
13715 that it reads properly regardless of how many words there are in the
13716 region: we don't want to say that ``there are 1 words in the region''.
13717 The conflict between singular and plural is ungrammatical. We can
13718 solve this problem by using a conditional expression that evaluates
13719 different messages depending on the number of words in the region.
13720 There are three possibilities: no words in the region, one word in the
13721 region, and more than one word. This means that the @code{cond}
13722 special form is appropriate.
13725 All this leads to the following function definition:
13729 ;;; @r{First version; has bugs!}
13730 (defun @value{COUNT-WORDS} (beginning end)
13731 "Print number of words in the region.
13732 Words are defined as at least one word-constituent
13733 character followed by at least one character that
13734 is not a word-constituent. The buffer's syntax
13735 table determines which characters these are."
13737 (message "Counting words in region ... ")
13741 ;;; @r{1. Set up appropriate conditions.}
13743 (goto-char beginning)
13748 ;;; @r{2. Run the} while @r{loop.}
13749 (while (< (point) end)
13750 (re-search-forward "\\w+\\W*")
13751 (setq count (1+ count)))
13755 ;;; @r{3. Send a message to the user.}
13756 (cond ((zerop count)
13758 "The region does NOT have any words."))
13761 "The region has 1 word."))
13764 "The region has %d words." count))))))
13769 As written, the function works, but not in all circumstances.
13771 @node Whitespace Bug
13772 @subsection The Whitespace Bug in @code{@value{COUNT-WORDS}}
13774 The @code{@value{COUNT-WORDS}} command described in the preceding
13775 section has two bugs, or rather, one bug with two manifestations.
13776 First, if you mark a region containing only whitespace in the middle
13777 of some text, the @code{@value{COUNT-WORDS}} command tells you that the
13778 region contains one word! Second, if you mark a region containing
13779 only whitespace at the end of the buffer or the accessible portion of
13780 a narrowed buffer, the command displays an error message that looks
13784 Search failed: "\\w+\\W*"
13787 If you are reading this in Info in GNU Emacs, you can test for these
13790 First, evaluate the function in the usual manner to install it.
13792 Here is a copy of the definition. Place your cursor after the closing
13793 parenthesis and type @kbd{C-x C-e} to install it.
13797 ;; @r{First version; has bugs!}
13798 (defun @value{COUNT-WORDS} (beginning end)
13799 "Print number of words in the region.
13800 Words are defined as at least one word-constituent character followed
13801 by at least one character that is not a word-constituent. The buffer's
13802 syntax table determines which characters these are."
13806 (message "Counting words in region ... ")
13810 ;;; @r{1. Set up appropriate conditions.}
13812 (goto-char beginning)
13817 ;;; @r{2. Run the} while @r{loop.}
13818 (while (< (point) end)
13819 (re-search-forward "\\w+\\W*")
13820 (setq count (1+ count)))
13824 ;;; @r{3. Send a message to the user.}
13825 (cond ((zerop count)
13826 (message "The region does NOT have any words."))
13827 ((= 1 count) (message "The region has 1 word."))
13828 (t (message "The region has %d words." count))))))
13834 If you wish, you can also install this keybinding by evaluating it:
13837 (global-set-key "\C-c=" '@value{COUNT-WORDS})
13840 To conduct the first test, set mark and point to the beginning and end
13841 of the following line and then type @kbd{C-c =} (or @kbd{M-x
13842 @value{COUNT-WORDS}} if you have not bound @kbd{C-c =}):
13849 Emacs will tell you, correctly, that the region has three words.
13851 Repeat the test, but place mark at the beginning of the line and place
13852 point just @emph{before} the word @samp{one}. Again type the command
13853 @kbd{C-c =} (or @kbd{M-x @value{COUNT-WORDS}}). Emacs should tell you
13854 that the region has no words, since it is composed only of the
13855 whitespace at the beginning of the line. But instead Emacs tells you
13856 that the region has one word!
13858 For the third test, copy the sample line to the end of the
13859 @file{*scratch*} buffer and then type several spaces at the end of the
13860 line. Place mark right after the word @samp{three} and point at the
13861 end of line. (The end of the line will be the end of the buffer.)
13862 Type @kbd{C-c =} (or @kbd{M-x @value{COUNT-WORDS}}) as you did before.
13863 Again, Emacs should tell you that the region has no words, since it is
13864 composed only of the whitespace at the end of the line. Instead,
13865 Emacs displays an error message saying @samp{Search failed}.
13867 The two bugs stem from the same problem.
13869 Consider the first manifestation of the bug, in which the command
13870 tells you that the whitespace at the beginning of the line contains
13871 one word. What happens is this: The @code{M-x @value{COUNT-WORDS}}
13872 command moves point to the beginning of the region. The @code{while}
13873 tests whether the value of point is smaller than the value of
13874 @code{end}, which it is. Consequently, the regular expression search
13875 looks for and finds the first word. It leaves point after the word.
13876 @code{count} is set to one. The @code{while} loop repeats; but this
13877 time the value of point is larger than the value of @code{end}, the
13878 loop is exited; and the function displays a message saying the number
13879 of words in the region is one. In brief, the regular expression
13880 search looks for and finds the word even though it is outside
13883 In the second manifestation of the bug, the region is whitespace at
13884 the end of the buffer. Emacs says @samp{Search failed}. What happens
13885 is that the true-or-false-test in the @code{while} loop tests true, so
13886 the search expression is executed. But since there are no more words
13887 in the buffer, the search fails.
13889 In both manifestations of the bug, the search extends or attempts to
13890 extend outside of the region.
13892 The solution is to limit the search to the region---this is a fairly
13893 simple action, but as you may have come to expect, it is not quite as
13894 simple as you might think.
13896 As we have seen, the @code{re-search-forward} function takes a search
13897 pattern as its first argument. But in addition to this first,
13898 mandatory argument, it accepts three optional arguments. The optional
13899 second argument bounds the search. The optional third argument, if
13900 @code{t}, causes the function to return @code{nil} rather than signal
13901 an error if the search fails. The optional fourth argument is a
13902 repeat count. (In Emacs, you can see a function's documentation by
13903 typing @kbd{C-h f}, the name of the function, and then @key{RET}.)
13905 In the @code{@value{COUNT-WORDS}} definition, the value of the end of
13906 the region is held by the variable @code{end} which is passed as an
13907 argument to the function. Thus, we can add @code{end} as an argument
13908 to the regular expression search expression:
13911 (re-search-forward "\\w+\\W*" end)
13914 However, if you make only this change to the @code{@value{COUNT-WORDS}}
13915 definition and then test the new version of the definition on a
13916 stretch of whitespace, you will receive an error message saying
13917 @samp{Search failed}.
13919 What happens is this: the search is limited to the region, and fails
13920 as you expect because there are no word-constituent characters in the
13921 region. Since it fails, we receive an error message. But we do not
13922 want to receive an error message in this case; we want to receive the
13923 message ``The region does NOT have any words.''
13925 The solution to this problem is to provide @code{re-search-forward}
13926 with a third argument of @code{t}, which causes the function to return
13927 @code{nil} rather than signal an error if the search fails.
13929 However, if you make this change and try it, you will see the message
13930 ``Counting words in region ... '' and @dots{} you will keep on seeing
13931 that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}).
13933 Here is what happens: the search is limited to the region, as before,
13934 and it fails because there are no word-constituent characters in the
13935 region, as expected. Consequently, the @code{re-search-forward}
13936 expression returns @code{nil}. It does nothing else. In particular,
13937 it does not move point, which it does as a side effect if it finds the
13938 search target. After the @code{re-search-forward} expression returns
13939 @code{nil}, the next expression in the @code{while} loop is evaluated.
13940 This expression increments the count. Then the loop repeats. The
13941 true-or-false-test tests true because the value of point is still less
13942 than the value of end, since the @code{re-search-forward} expression
13943 did not move point. @dots{} and the cycle repeats @dots{}
13945 The @code{@value{COUNT-WORDS}} definition requires yet another
13946 modification, to cause the true-or-false-test of the @code{while} loop
13947 to test false if the search fails. Put another way, there are two
13948 conditions that must be satisfied in the true-or-false-test before the
13949 word count variable is incremented: point must still be within the
13950 region and the search expression must have found a word to count.
13952 Since both the first condition and the second condition must be true
13953 together, the two expressions, the region test and the search
13954 expression, can be joined with an @code{and} special form and embedded in
13955 the @code{while} loop as the true-or-false-test, like this:
13958 (and (< (point) end) (re-search-forward "\\w+\\W*" end t))
13961 @c colon in printed section title causes problem in Info cross reference
13962 @c also trouble with an overfull hbox
13965 (For information about @code{and}, see
13966 @ref{kill-new function, , The @code{kill-new} function}.)
13970 (@xref{kill-new function, , The @code{kill-new} function}, for
13971 information about @code{and}.)
13974 The @code{re-search-forward} expression returns @code{t} if the search
13975 succeeds and as a side effect moves point. Consequently, as words are
13976 found, point is moved through the region. When the search expression
13977 fails to find another word, or when point reaches the end of the
13978 region, the true-or-false-test tests false, the @code{while} loop
13979 exits, and the @code{@value{COUNT-WORDS}} function displays one or
13980 other of its messages.
13982 After incorporating these final changes, the @code{@value{COUNT-WORDS}}
13983 works without bugs (or at least, without bugs that I have found!).
13984 Here is what it looks like:
13988 ;;; @r{Final version:} @code{while}
13989 (defun @value{COUNT-WORDS} (beginning end)
13990 "Print number of words in the region."
13992 (message "Counting words in region ... ")
13996 ;;; @r{1. Set up appropriate conditions.}
13999 (goto-char beginning)
14003 ;;; @r{2. Run the} while @r{loop.}
14004 (while (and (< (point) end)
14005 (re-search-forward "\\w+\\W*" end t))
14006 (setq count (1+ count)))
14010 ;;; @r{3. Send a message to the user.}
14011 (cond ((zerop count)
14013 "The region does NOT have any words."))
14016 "The region has 1 word."))
14019 "The region has %d words." count))))))
14023 @node recursive-count-words
14024 @section Count Words Recursively
14025 @cindex Count words recursively
14026 @cindex Recursively counting words
14027 @cindex Words, counted recursively
14029 You can write the function for counting words recursively as well as
14030 with a @code{while} loop. Let's see how this is done.
14032 First, we need to recognize that the @code{@value{COUNT-WORDS}}
14033 function has three jobs: it sets up the appropriate conditions for
14034 counting to occur; it counts the words in the region; and it sends a
14035 message to the user telling how many words there are.
14037 If we write a single recursive function to do everything, we will
14038 receive a message for every recursive call. If the region contains 13
14039 words, we will receive thirteen messages, one right after the other.
14040 We don't want this! Instead, we must write two functions to do the
14041 job, one of which (the recursive function) will be used inside of the
14042 other. One function will set up the conditions and display the
14043 message; the other will return the word count.
14045 Let us start with the function that causes the message to be displayed.
14046 We can continue to call this @code{@value{COUNT-WORDS}}.
14048 This is the function that the user will call. It will be interactive.
14049 Indeed, it will be similar to our previous versions of this
14050 function, except that it will call @code{recursive-count-words} to
14051 determine how many words are in the region.
14054 We can readily construct a template for this function, based on our
14059 ;; @r{Recursive version; uses regular expression search}
14060 (defun @value{COUNT-WORDS} (beginning end)
14061 "@var{documentation}@dots{}"
14062 (@var{interactive-expression}@dots{})
14066 ;;; @r{1. Set up appropriate conditions.}
14067 (@var{explanatory message})
14068 (@var{set-up functions}@dots{}
14072 ;;; @r{2. Count the words.}
14073 @var{recursive call}
14077 ;;; @r{3. Send a message to the user.}
14078 @var{message providing word count}))
14082 The definition looks straightforward, except that somehow the count
14083 returned by the recursive call must be passed to the message
14084 displaying the word count. A little thought suggests that this can be
14085 done by making use of a @code{let} expression: we can bind a variable
14086 in the varlist of a @code{let} expression to the number of words in
14087 the region, as returned by the recursive call; and then the
14088 @code{cond} expression, using binding, can display the value to the
14091 Often, one thinks of the binding within a @code{let} expression as
14092 somehow secondary to the primary work of a function. But in this
14093 case, what you might consider the primary job of the function,
14094 counting words, is done within the @code{let} expression.
14097 Using @code{let}, the function definition looks like this:
14101 (defun @value{COUNT-WORDS} (beginning end)
14102 "Print number of words in the region."
14107 ;;; @r{1. Set up appropriate conditions.}
14108 (message "Counting words in region ... ")
14110 (goto-char beginning)
14114 ;;; @r{2. Count the words.}
14115 (let ((count (recursive-count-words end)))
14119 ;;; @r{3. Send a message to the user.}
14120 (cond ((zerop count)
14122 "The region does NOT have any words."))
14125 "The region has 1 word."))
14128 "The region has %d words." count))))))
14132 Next, we need to write the recursive counting function.
14134 A recursive function has at least three parts: the do-again-test, the
14135 next-step-expression, and the recursive call.
14137 The do-again-test determines whether the function will or will not be
14138 called again. Since we are counting words in a region and can use a
14139 function that moves point forward for every word, the do-again-test
14140 can check whether point is still within the region. The do-again-test
14141 should find the value of point and determine whether point is before,
14142 at, or after the value of the end of the region. We can use the
14143 @code{point} function to locate point. Clearly, we must pass the
14144 value of the end of the region to the recursive counting function as an
14147 In addition, the do-again-test should also test whether the search finds a
14148 word. If it does not, the function should not call itself again.
14150 The next-step-expression changes a value so that when the recursive
14151 function is supposed to stop calling itself, it stops. More
14152 precisely, the next-step-expression changes a value so that at the
14153 right time, the do-again-test stops the recursive function from
14154 calling itself again. In this case, the next-step-expression can be
14155 the expression that moves point forward, word by word.
14157 The third part of a recursive function is the recursive call.
14159 Somewhere, we also need a part that does the work of the
14160 function, a part that does the counting. A vital part!
14163 But already, we have an outline of the recursive counting function:
14167 (defun recursive-count-words (region-end)
14168 "@var{documentation}@dots{}"
14169 @var{do-again-test}
14170 @var{next-step-expression}
14171 @var{recursive call})
14175 Now we need to fill in the slots. Let's start with the simplest cases
14176 first: if point is at or beyond the end of the region, there cannot
14177 be any words in the region, so the function should return zero.
14178 Likewise, if the search fails, there are no words to count, so the
14179 function should return zero.
14181 On the other hand, if point is within the region and the search
14182 succeeds, the function should call itself again.
14185 Thus, the do-again-test should look like this:
14189 (and (< (point) region-end)
14190 (re-search-forward "\\w+\\W*" region-end t))
14194 Note that the search expression is part of the do-again-test---the
14195 function returns @code{t} if its search succeeds and @code{nil} if it
14196 fails. (@xref{Whitespace Bug, , The Whitespace Bug in
14197 @code{@value{COUNT-WORDS}}}, for an explanation of how
14198 @code{re-search-forward} works.)
14200 The do-again-test is the true-or-false test of an @code{if} clause.
14201 Clearly, if the do-again-test succeeds, the then-part of the @code{if}
14202 clause should call the function again; but if it fails, the else-part
14203 should return zero since either point is outside the region or the
14204 search failed because there were no words to find.
14206 But before considering the recursive call, we need to consider the
14207 next-step-expression. What is it? Interestingly, it is the search
14208 part of the do-again-test.
14210 In addition to returning @code{t} or @code{nil} for the
14211 do-again-test, @code{re-search-forward} moves point forward as a side
14212 effect of a successful search. This is the action that changes the
14213 value of point so that the recursive function stops calling itself
14214 when point completes its movement through the region. Consequently,
14215 the @code{re-search-forward} expression is the next-step-expression.
14218 In outline, then, the body of the @code{recursive-count-words}
14219 function looks like this:
14223 (if @var{do-again-test-and-next-step-combined}
14225 @var{recursive-call-returning-count}
14231 How to incorporate the mechanism that counts?
14233 If you are not used to writing recursive functions, a question like
14234 this can be troublesome. But it can and should be approached
14237 We know that the counting mechanism should be associated in some way
14238 with the recursive call. Indeed, since the next-step-expression moves
14239 point forward by one word, and since a recursive call is made for
14240 each word, the counting mechanism must be an expression that adds one
14241 to the value returned by a call to @code{recursive-count-words}.
14244 Consider several cases:
14248 If there are two words in the region, the function should return
14249 a value resulting from adding one to the value returned when it counts
14250 the first word, plus the number returned when it counts the remaining
14251 words in the region, which in this case is one.
14254 If there is one word in the region, the function should return
14255 a value resulting from adding one to the value returned when it counts
14256 that word, plus the number returned when it counts the remaining
14257 words in the region, which in this case is zero.
14260 If there are no words in the region, the function should return zero.
14263 From the sketch we can see that the else-part of the @code{if} returns
14264 zero for the case of no words. This means that the then-part of the
14265 @code{if} must return a value resulting from adding one to the value
14266 returned from a count of the remaining words.
14269 The expression will look like this, where @code{1+} is a function that
14270 adds one to its argument.
14273 (1+ (recursive-count-words region-end))
14277 The whole @code{recursive-count-words} function will then look like
14282 (defun recursive-count-words (region-end)
14283 "@var{documentation}@dots{}"
14285 ;;; @r{1. do-again-test}
14286 (if (and (< (point) region-end)
14287 (re-search-forward "\\w+\\W*" region-end t))
14291 ;;; @r{2. then-part: the recursive call}
14292 (1+ (recursive-count-words region-end))
14294 ;;; @r{3. else-part}
14300 Let's examine how this works:
14302 If there are no words in the region, the else part of the @code{if}
14303 expression is evaluated and consequently the function returns zero.
14305 If there is one word in the region, the value of point is less than
14306 the value of @code{region-end} and the search succeeds. In this case,
14307 the true-or-false-test of the @code{if} expression tests true, and the
14308 then-part of the @code{if} expression is evaluated. The counting
14309 expression is evaluated. This expression returns a value (which will
14310 be the value returned by the whole function) that is the sum of one
14311 added to the value returned by a recursive call.
14313 Meanwhile, the next-step-expression has caused point to jump over the
14314 first (and in this case only) word in the region. This means that
14315 when @code{(recursive-count-words region-end)} is evaluated a second
14316 time, as a result of the recursive call, the value of point will be
14317 equal to or greater than the value of region end. So this time,
14318 @code{recursive-count-words} will return zero. The zero will be added
14319 to one, and the original evaluation of @code{recursive-count-words}
14320 will return one plus zero, which is one, which is the correct amount.
14322 Clearly, if there are two words in the region, the first call to
14323 @code{recursive-count-words} returns one added to the value returned
14324 by calling @code{recursive-count-words} on a region containing the
14325 remaining word---that is, it adds one to one, producing two, which is
14326 the correct amount.
14328 Similarly, if there are three words in the region, the first call to
14329 @code{recursive-count-words} returns one added to the value returned
14330 by calling @code{recursive-count-words} on a region containing the
14331 remaining two words---and so on and so on.
14335 With full documentation the two functions look like this:
14339 The recursive function:
14341 @findex recursive-count-words
14344 (defun recursive-count-words (region-end)
14345 "Number of words between point and REGION-END."
14349 ;;; @r{1. do-again-test}
14350 (if (and (< (point) region-end)
14351 (re-search-forward "\\w+\\W*" region-end t))
14355 ;;; @r{2. then-part: the recursive call}
14356 (1+ (recursive-count-words region-end))
14358 ;;; @r{3. else-part}
14369 ;;; @r{Recursive version}
14370 (defun @value{COUNT-WORDS} (beginning end)
14371 "Print number of words in the region.
14375 Words are defined as at least one word-constituent
14376 character followed by at least one character that is
14377 not a word-constituent. The buffer's syntax table
14378 determines which characters these are."
14382 (message "Counting words in region ... ")
14384 (goto-char beginning)
14385 (let ((count (recursive-count-words end)))
14388 (cond ((zerop count)
14390 "The region does NOT have any words."))
14394 (message "The region has 1 word."))
14397 "The region has %d words." count))))))
14401 @node Counting Exercise
14402 @section Exercise: Counting Punctuation
14404 Using a @code{while} loop, write a function to count the number of
14405 punctuation marks in a region---period, comma, semicolon, colon,
14406 exclamation mark, and question mark. Do the same using recursion.
14408 @node Words in a defun
14409 @chapter Counting Words in a @code{defun}
14410 @cindex Counting words in a @code{defun}
14411 @cindex Word counting in a @code{defun}
14413 Our next project is to count the number of words in a function
14414 definition. Clearly, this can be done using some variant of
14415 @code{@value{COUNT-WORDS}}. @xref{Counting Words, , Counting via
14416 Repetition and Regexps}. If we are just going to count the words in
14417 one definition, it is easy enough to mark the definition with the
14418 @kbd{C-M-h} (@code{mark-defun}) command, and then call
14419 @code{@value{COUNT-WORDS}}.
14421 However, I am more ambitious: I want to count the words and symbols in
14422 every definition in the Emacs sources and then print a graph that
14423 shows how many functions there are of each length: how many contain 40
14424 to 49 words or symbols, how many contain 50 to 59 words or symbols,
14425 and so on. I have often been curious how long a typical function is,
14426 and this will tell.
14429 * Divide and Conquer::
14430 * Words and Symbols:: What to count?
14431 * Syntax:: What constitutes a word or symbol?
14432 * count-words-in-defun:: Very like @code{@value{COUNT-WORDS}}.
14433 * Several defuns:: Counting several defuns in a file.
14434 * Find a File:: Do you want to look at a file?
14435 * lengths-list-file:: A list of the lengths of many definitions.
14436 * Several files:: Counting in definitions in different files.
14437 * Several files recursively:: Recursively counting in different files.
14438 * Prepare the data:: Prepare the data for display in a graph.
14442 @node Divide and Conquer
14443 @unnumberedsec Divide and Conquer
14446 Described in one phrase, the histogram project is daunting; but
14447 divided into numerous small steps, each of which we can take one at a
14448 time, the project becomes less fearsome. Let us consider what the
14453 First, write a function to count the words in one definition. This
14454 includes the problem of handling symbols as well as words.
14457 Second, write a function to list the number of words in each function
14458 in a file. This function can use the @code{count-words-in-defun}
14462 Third, write a function to list the number of words in each function
14463 in each of several files. This entails automatically finding the
14464 various files, switching to them, and counting the words in the
14465 definitions within them.
14468 Fourth, write a function to convert the list of numbers that we
14469 created in step three to a form that will be suitable for printing as
14473 Fifth, write a function to print the results as a graph.
14476 This is quite a project! But if we take each step slowly, it will not
14479 @node Words and Symbols
14480 @section What to Count?
14481 @cindex Words and symbols in defun
14483 When we first start thinking about how to count the words in a
14484 function definition, the first question is (or ought to be) what are
14485 we going to count? When we speak of ``words'' with respect to a Lisp
14486 function definition, we are actually speaking, in large part, of
14487 symbols. For example, the following @code{multiply-by-seven}
14488 function contains the five symbols @code{defun},
14489 @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In
14490 addition, in the documentation string, it contains the four words
14491 @samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The
14492 symbol @samp{number} is repeated, so the definition contains a total
14493 of ten words and symbols.
14497 (defun multiply-by-seven (number)
14498 "Multiply NUMBER by seven."
14504 However, if we mark the @code{multiply-by-seven} definition with
14505 @kbd{C-M-h} (@code{mark-defun}), and then call
14506 @code{@value{COUNT-WORDS}} on it, we will find that
14507 @code{@value{COUNT-WORDS}} claims the definition has eleven words, not
14508 ten! Something is wrong!
14510 The problem is twofold: @code{@value{COUNT-WORDS}} does not count the
14511 @samp{*} as a word, and it counts the single symbol,
14512 @code{multiply-by-seven}, as containing three words. The hyphens are
14513 treated as if they were interword spaces rather than intraword
14514 connectors: @samp{multiply-by-seven} is counted as if it were written
14515 @samp{multiply by seven}.
14517 The cause of this confusion is the regular expression search within
14518 the @code{@value{COUNT-WORDS}} definition that moves point forward word
14519 by word. In the canonical version of @code{@value{COUNT-WORDS}}, the
14527 This regular expression is a pattern defining one or more word
14528 constituent characters possibly followed by one or more characters
14529 that are not word constituents. What is meant by ``word constituent
14530 characters'' brings us to the issue of syntax, which is worth a section
14534 @section What Constitutes a Word or Symbol?
14535 @cindex Syntax categories and tables
14537 Emacs treats different characters as belonging to different
14538 @dfn{syntax categories}. For example, the regular expression,
14539 @samp{\\w+}, is a pattern specifying one or more @emph{word
14540 constituent} characters. Word constituent characters are members of
14541 one syntax category. Other syntax categories include the class of
14542 punctuation characters, such as the period and the comma, and the
14543 class of whitespace characters, such as the blank space and the tab
14544 character. (For more information, @pxref{Syntax Tables, , Syntax
14545 Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
14547 Syntax tables specify which characters belong to which categories.
14548 Usually, a hyphen is not specified as a word constituent character.
14549 Instead, it is specified as being in the class of characters that are
14550 part of symbol names but not words. This means that the
14551 @code{@value{COUNT-WORDS}} function treats it in the same way it treats
14552 an interword white space, which is why @code{@value{COUNT-WORDS}}
14553 counts @samp{multiply-by-seven} as three words.
14555 There are two ways to cause Emacs to count @samp{multiply-by-seven} as
14556 one symbol: modify the syntax table or modify the regular expression.
14558 We could redefine a hyphen as a word constituent character by
14559 modifying the syntax table that Emacs keeps for each mode. This
14560 action would serve our purpose, except that a hyphen is merely the
14561 most common character within symbols that is not typically a word
14562 constituent character; there are others, too.
14564 Alternatively, we can redefine the regexp used in the
14565 @code{@value{COUNT-WORDS}} definition so as to include symbols. This
14566 procedure has the merit of clarity, but the task is a little tricky.
14569 The first part is simple enough: the pattern must match at least one
14570 character that is a word or symbol constituent. Thus:
14573 "\\(\\w\\|\\s_\\)+"
14577 The @samp{\\(} is the first part of the grouping construct that
14578 includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated
14579 by the @samp{\\|}. The @samp{\\w} matches any word-constituent
14580 character and the @samp{\\s_} matches any character that is part of a
14581 symbol name but not a word-constituent character. The @samp{+}
14582 following the group indicates that the word or symbol constituent
14583 characters must be matched at least once.
14585 However, the second part of the regexp is more difficult to design.
14586 What we want is to follow the first part with optionally one or more
14587 characters that are not constituents of a word or symbol. At first,
14588 I thought I could define this with the following:
14591 "\\(\\W\\|\\S_\\)*"
14595 The upper case @samp{W} and @samp{S} match characters that are
14596 @emph{not} word or symbol constituents. Unfortunately, this
14597 expression matches any character that is either not a word constituent
14598 or not a symbol constituent. This matches any character!
14600 I then noticed that every word or symbol in my test region was
14601 followed by white space (blank space, tab, or newline). So I tried
14602 placing a pattern to match one or more blank spaces after the pattern
14603 for one or more word or symbol constituents. This failed, too. Words
14604 and symbols are often separated by whitespace, but in actual code
14605 parentheses may follow symbols and punctuation may follow words. So
14606 finally, I designed a pattern in which the word or symbol constituents
14607 are followed optionally by characters that are not white space and
14608 then followed optionally by white space.
14611 Here is the full regular expression:
14614 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14617 @node count-words-in-defun
14618 @section The @code{count-words-in-defun} Function
14619 @cindex Counting words in a @code{defun}
14621 We have seen that there are several ways to write a
14622 @code{count-words-region} function. To write a
14623 @code{count-words-in-defun}, we need merely adapt one of these
14626 The version that uses a @code{while} loop is easy to understand, so I
14627 am going to adapt that. Because @code{count-words-in-defun} will be
14628 part of a more complex program, it need not be interactive and it need
14629 not display a message but just return the count. These considerations
14630 simplify the definition a little.
14632 On the other hand, @code{count-words-in-defun} will be used within a
14633 buffer that contains function definitions. Consequently, it is
14634 reasonable to ask that the function determine whether it is called
14635 when point is within a function definition, and if it is, to return
14636 the count for that definition. This adds complexity to the
14637 definition, but saves us from needing to pass arguments to the
14641 These considerations lead us to prepare the following template:
14645 (defun count-words-in-defun ()
14646 "@var{documentation}@dots{}"
14647 (@var{set up}@dots{}
14648 (@var{while loop}@dots{})
14649 @var{return count})
14654 As usual, our job is to fill in the slots.
14658 We are presuming that this function will be called within a buffer
14659 containing function definitions. Point will either be within a
14660 function definition or not. For @code{count-words-in-defun} to work,
14661 point must move to the beginning of the definition, a counter must
14662 start at zero, and the counting loop must stop when point reaches the
14663 end of the definition.
14665 The @code{beginning-of-defun} function searches backwards for an
14666 opening delimiter such as a @samp{(} at the beginning of a line, and
14667 moves point to that position, or else to the limit of the search. In
14668 practice, this means that @code{beginning-of-defun} moves point to the
14669 beginning of an enclosing or preceding function definition, or else to
14670 the beginning of the buffer. We can use @code{beginning-of-defun} to
14671 place point where we wish to start.
14673 The @code{while} loop requires a counter to keep track of the words or
14674 symbols being counted. A @code{let} expression can be used to create
14675 a local variable for this purpose, and bind it to an initial value of zero.
14677 The @code{end-of-defun} function works like @code{beginning-of-defun}
14678 except that it moves point to the end of the definition.
14679 @code{end-of-defun} can be used as part of an expression that
14680 determines the position of the end of the definition.
14682 The set up for @code{count-words-in-defun} takes shape rapidly: first
14683 we move point to the beginning of the definition, then we create a
14684 local variable to hold the count, and finally, we record the position
14685 of the end of the definition so the @code{while} loop will know when to stop
14689 The code looks like this:
14693 (beginning-of-defun)
14695 (end (save-excursion (end-of-defun) (point))))
14700 The code is simple. The only slight complication is likely to concern
14701 @code{end}: it is bound to the position of the end of the definition
14702 by a @code{save-excursion} expression that returns the value of point
14703 after @code{end-of-defun} temporarily moves it to the end of the
14706 The second part of the @code{count-words-in-defun}, after the set up,
14707 is the @code{while} loop.
14709 The loop must contain an expression that jumps point forward word by
14710 word and symbol by symbol, and another expression that counts the
14711 jumps. The true-or-false-test for the @code{while} loop should test
14712 true so long as point should jump forward, and false when point is at
14713 the end of the definition. We have already redefined the regular
14714 expression for this, so the loop is straightforward:
14718 (while (and (< (point) end)
14720 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t))
14721 (setq count (1+ count)))
14725 The third part of the function definition returns the count of words
14726 and symbols. This part is the last expression within the body of the
14727 @code{let} expression, and can be, very simply, the local variable
14728 @code{count}, which when evaluated returns the count.
14731 Put together, the @code{count-words-in-defun} definition looks like this:
14733 @findex count-words-in-defun
14736 (defun count-words-in-defun ()
14737 "Return the number of words and symbols in a defun."
14738 (beginning-of-defun)
14740 (end (save-excursion (end-of-defun) (point))))
14744 (and (< (point) end)
14746 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14748 (setq count (1+ count)))
14753 How to test this? The function is not interactive, but it is easy to
14754 put a wrapper around the function to make it interactive; we can use
14755 almost the same code as for the recursive version of
14756 @code{@value{COUNT-WORDS}}:
14760 ;;; @r{Interactive version.}
14761 (defun count-words-defun ()
14762 "Number of words and symbols in a function definition."
14765 "Counting words and symbols in function definition ... ")
14768 (let ((count (count-words-in-defun)))
14772 "The definition does NOT have any words or symbols."))
14777 "The definition has 1 word or symbol."))
14780 "The definition has %d words or symbols." count)))))
14786 Let's re-use @kbd{C-c =} as a convenient keybinding:
14789 (global-set-key "\C-c=" 'count-words-defun)
14792 Now we can try out @code{count-words-defun}: install both
14793 @code{count-words-in-defun} and @code{count-words-defun}, and set the
14794 keybinding, and then place the cursor within the following definition:
14798 (defun multiply-by-seven (number)
14799 "Multiply NUMBER by seven."
14806 Success! The definition has 10 words and symbols.
14808 The next problem is to count the numbers of words and symbols in
14809 several definitions within a single file.
14811 @node Several defuns
14812 @section Count Several @code{defuns} Within a File
14814 A file such as @file{simple.el} may have a hundred or more function
14815 definitions within it. Our long term goal is to collect statistics on
14816 many files, but as a first step, our immediate goal is to collect
14817 statistics on one file.
14819 The information will be a series of numbers, each number being the
14820 length of a function definition. We can store the numbers in a list.
14822 We know that we will want to incorporate the information regarding one
14823 file with information about many other files; this means that the
14824 function for counting definition lengths within one file need only
14825 return the list of lengths. It need not and should not display any
14828 The word count commands contain one expression to jump point forward
14829 word by word and another expression to count the jumps. The function
14830 to return the lengths of definitions can be designed to work the same
14831 way, with one expression to jump point forward definition by
14832 definition and another expression to construct the lengths' list.
14834 This statement of the problem makes it elementary to write the
14835 function definition. Clearly, we will start the count at the
14836 beginning of the file, so the first command will be @code{(goto-char
14837 (point-min))}. Next, we start the @code{while} loop; and the
14838 true-or-false test of the loop can be a regular expression search for
14839 the next function definition---so long as the search succeeds, point
14840 is moved forward and then the body of the loop is evaluated. The body
14841 needs an expression that constructs the lengths' list. @code{cons},
14842 the list construction command, can be used to create the list. That
14843 is almost all there is to it.
14846 Here is what this fragment of code looks like:
14850 (goto-char (point-min))
14851 (while (re-search-forward "^(defun" nil t)
14853 (cons (count-words-in-defun) lengths-list)))
14857 What we have left out is the mechanism for finding the file that
14858 contains the function definitions.
14860 In previous examples, we either used this, the Info file, or we
14861 switched back and forth to some other buffer, such as the
14862 @file{*scratch*} buffer.
14864 Finding a file is a new process that we have not yet discussed.
14867 @section Find a File
14868 @cindex Find a File
14870 To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file})
14871 command. This command is almost, but not quite right for the lengths
14875 Let's look at the source for @code{find-file}:
14879 (defun find-file (filename)
14880 "Edit file FILENAME.
14881 Switch to a buffer visiting file FILENAME,
14882 creating one if none already exists."
14883 (interactive "FFind file: ")
14884 (switch-to-buffer (find-file-noselect filename)))
14889 (The most recent version of the @code{find-file} function definition
14890 permits you to specify optional wildcards to visit multiple files; that
14891 makes the definition more complex and we will not discuss it here,
14892 since it is not relevant. You can see its source using either
14893 @kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).)
14897 (defun find-file (filename &optional wildcards)
14898 "Edit file FILENAME.
14899 Switch to a buffer visiting file FILENAME,
14900 creating one if none already exists.
14901 Interactively, the default if you just type RET is the current directory,
14902 but the visited file name is available through the minibuffer history:
14903 type M-n to pull it into the minibuffer.
14905 Interactively, or if WILDCARDS is non-nil in a call from Lisp,
14906 expand wildcards (if any) and visit multiple files. You can
14907 suppress wildcard expansion by setting `find-file-wildcards' to nil.
14909 To visit a file without any kind of conversion and without
14910 automatically choosing a major mode, use \\[find-file-literally]."
14911 (interactive (find-file-read-args "Find file: " nil))
14912 (let ((value (find-file-noselect filename nil nil wildcards)))
14914 (mapcar 'switch-to-buffer (nreverse value))
14915 (switch-to-buffer value))))
14918 The definition I am showing possesses short but complete documentation
14919 and an interactive specification that prompts you for a file name when
14920 you use the command interactively. The body of the definition
14921 contains two functions, @code{find-file-noselect} and
14922 @code{switch-to-buffer}.
14924 According to its documentation as shown by @kbd{C-h f} (the
14925 @code{describe-function} command), the @code{find-file-noselect}
14926 function reads the named file into a buffer and returns the buffer.
14927 (Its most recent version includes an optional @var{wildcards} argument,
14928 too, as well as another to read a file literally and an other you
14929 suppress warning messages. These optional arguments are irrelevant.)
14931 However, the @code{find-file-noselect} function does not select the
14932 buffer in which it puts the file. Emacs does not switch its attention
14933 (or yours if you are using @code{find-file-noselect}) to the selected
14934 buffer. That is what @code{switch-to-buffer} does: it switches the
14935 buffer to which Emacs attention is directed; and it switches the
14936 buffer displayed in the window to the new buffer. We have discussed
14937 buffer switching elsewhere. (@xref{Switching Buffers}.)
14939 In this histogram project, we do not need to display each file on the
14940 screen as the program determines the length of each definition within
14941 it. Instead of employing @code{switch-to-buffer}, we can work with
14942 @code{set-buffer}, which redirects the attention of the computer
14943 program to a different buffer but does not redisplay it on the screen.
14944 So instead of calling on @code{find-file} to do the job, we must write
14945 our own expression.
14947 The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
14949 @node lengths-list-file
14950 @section @code{lengths-list-file} in Detail
14952 The core of the @code{lengths-list-file} function is a @code{while}
14953 loop containing a function to move point forward defun by defun, and
14954 a function to count the number of words and symbols in each defun.
14955 This core must be surrounded by functions that do various other tasks,
14956 including finding the file, and ensuring that point starts out at the
14957 beginning of the file. The function definition looks like this:
14958 @findex lengths-list-file
14962 (defun lengths-list-file (filename)
14963 "Return list of definitions' lengths within FILE.
14964 The returned list is a list of numbers.
14965 Each number is the number of words or
14966 symbols in one function definition."
14969 (message "Working on `%s' ... " filename)
14971 (let ((buffer (find-file-noselect filename))
14973 (set-buffer buffer)
14974 (setq buffer-read-only t)
14976 (goto-char (point-min))
14977 (while (re-search-forward "^(defun" nil t)
14979 (cons (count-words-in-defun) lengths-list)))
14980 (kill-buffer buffer)
14986 The function is passed one argument, the name of the file on which it
14987 will work. It has four lines of documentation, but no interactive
14988 specification. Since people worry that a computer is broken if they
14989 don't see anything going on, the first line of the body is a
14992 The next line contains a @code{save-excursion} that returns Emacs's
14993 attention to the current buffer when the function completes. This is
14994 useful in case you embed this function in another function that
14995 presumes point is restored to the original buffer.
14997 In the varlist of the @code{let} expression, Emacs finds the file and
14998 binds the local variable @code{buffer} to the buffer containing the
14999 file. At the same time, Emacs creates @code{lengths-list} as a local
15002 Next, Emacs switches its attention to the buffer.
15004 In the following line, Emacs makes the buffer read-only. Ideally,
15005 this line is not necessary. None of the functions for counting words
15006 and symbols in a function definition should change the buffer.
15007 Besides, the buffer is not going to be saved, even if it were changed.
15008 This line is entirely the consequence of great, perhaps excessive,
15009 caution. The reason for the caution is that this function and those
15010 it calls work on the sources for Emacs and it is inconvenient if they
15011 are inadvertently modified. It goes without saying that I did not
15012 realize a need for this line until an experiment went awry and started
15013 to modify my Emacs source files @dots{}
15015 Next comes a call to widen the buffer if it is narrowed. This
15016 function is usually not needed---Emacs creates a fresh buffer if none
15017 already exists; but if a buffer visiting the file already exists Emacs
15018 returns that one. In this case, the buffer may be narrowed and must
15019 be widened. If we wanted to be fully user-friendly, we would
15020 arrange to save the restriction and the location of point, but we
15023 The @code{(goto-char (point-min))} expression moves point to the
15024 beginning of the buffer.
15026 Then comes a @code{while} loop in which the work of the function is
15027 carried out. In the loop, Emacs determines the length of each
15028 definition and constructs a lengths' list containing the information.
15030 Emacs kills the buffer after working through it. This is to save
15031 space inside of Emacs. My version of GNU Emacs 19 contained over 300
15032 source files of interest; GNU Emacs 22 contains over a thousand source
15033 files. Another function will apply @code{lengths-list-file} to each
15036 Finally, the last expression within the @code{let} expression is the
15037 @code{lengths-list} variable; its value is returned as the value of
15038 the whole function.
15040 You can try this function by installing it in the usual fashion. Then
15041 place your cursor after the following expression and type @kbd{C-x
15042 C-e} (@code{eval-last-sexp}).
15044 @c !!! 22.1.1 lisp sources location here
15047 "/usr/local/share/emacs/22.1/lisp/emacs-lisp/debug.el")
15051 You may need to change the pathname of the file; the one here is for
15052 GNU Emacs version 22.1. To change the expression, copy it to
15053 the @file{*scratch*} buffer and edit it.
15057 Also, to see the full length of the list, rather than a truncated
15058 version, you may have to evaluate the following:
15059 @c We do not want to insert, so do not mention the zero prefix argument.
15062 (custom-set-variables '(eval-expression-print-length nil))
15066 (@xref{defcustom, , Specifying Variables using @code{defcustom}}.
15067 Then evaluate the @code{lengths-list-file} expression.)
15070 The lengths' list for @file{debug.el} takes less than a second to
15071 produce and looks like this in GNU Emacs 22:
15074 (83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587)
15078 (Using my old machine, the version 19 lengths' list for @file{debug.el}
15079 took seven seconds to produce and looked like this:
15082 (75 41 80 62 20 45 44 68 45 12 34 235)
15086 The newer version of @file{debug.el} contains more defuns than the
15087 earlier one; and my new machine is much faster than the old one.)
15089 Note that the length of the last definition in the file is first in
15092 @node Several files
15093 @section Count Words in @code{defuns} in Different Files
15095 In the previous section, we created a function that returns a list of
15096 the lengths of each definition in a file. Now, we want to define a
15097 function to return a master list of the lengths of the definitions in
15100 Working on each of a list of files is a repetitious act, so we can use
15101 either a @code{while} loop or recursion.
15104 * lengths-list-many-files:: Return a list of the lengths of defuns.
15105 * append:: Attach one list to another.
15109 @node lengths-list-many-files
15110 @unnumberedsubsec Determine the lengths of @code{defuns}
15113 The design using a @code{while} loop is routine. The argument passed
15114 to the function is a list of files. As we saw earlier (@pxref{Loop
15115 Example}), you can write a @code{while} loop so that the body of the
15116 loop is evaluated if such a list contains elements, but to exit the
15117 loop if the list is empty. For this design to work, the body of the
15118 loop must contain an expression that shortens the list each time the
15119 body is evaluated, so that eventually the list is empty. The usual
15120 technique is to set the value of the list to the value of the @sc{cdr}
15121 of the list each time the body is evaluated.
15124 The template looks like this:
15128 (while @var{test-whether-list-is-empty}
15130 @var{set-list-to-cdr-of-list})
15134 Also, we remember that a @code{while} loop returns @code{nil} (the
15135 result of evaluating the true-or-false-test), not the result of any
15136 evaluation within its body. (The evaluations within the body of the
15137 loop are done for their side effects.) However, the expression that
15138 sets the lengths' list is part of the body---and that is the value
15139 that we want returned by the function as a whole. To do this, we
15140 enclose the @code{while} loop within a @code{let} expression, and
15141 arrange that the last element of the @code{let} expression contains
15142 the value of the lengths' list. (@xref{Incrementing Example, , Loop
15143 Example with an Incrementing Counter}.)
15145 @findex lengths-list-many-files
15147 These considerations lead us directly to the function itself:
15151 ;;; @r{Use @code{while} loop.}
15152 (defun lengths-list-many-files (list-of-files)
15153 "Return list of lengths of defuns in LIST-OF-FILES."
15156 (let (lengths-list)
15158 ;;; @r{true-or-false-test}
15159 (while list-of-files
15164 ;;; @r{Generate a lengths' list.}
15166 (expand-file-name (car list-of-files)))))
15170 ;;; @r{Make files' list shorter.}
15171 (setq list-of-files (cdr list-of-files)))
15173 ;;; @r{Return final value of lengths' list.}
15178 @code{expand-file-name} is a built-in function that converts a file
15179 name to the absolute, long, path name form. The function employs the
15180 name of the directory in which the function is called.
15182 @c !!! 22.1.1 lisp sources location here
15184 Thus, if @code{expand-file-name} is called on @code{debug.el} when
15185 Emacs is visiting the
15186 @file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory,
15196 @c !!! 22.1.1 lisp sources location here
15198 /usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el
15201 The only other new element of this function definition is the as yet
15202 unstudied function @code{append}, which merits a short section for
15206 @subsection The @code{append} Function
15209 The @code{append} function attaches one list to another. Thus,
15212 (append '(1 2 3 4) '(5 6 7 8))
15223 This is exactly how we want to attach two lengths' lists produced by
15224 @code{lengths-list-file} to each other. The results contrast with
15228 (cons '(1 2 3 4) '(5 6 7 8))
15233 which constructs a new list in which the first argument to @code{cons}
15234 becomes the first element of the new list:
15237 ((1 2 3 4) 5 6 7 8)
15240 @node Several files recursively
15241 @section Recursively Count Words in Different Files
15243 Besides a @code{while} loop, you can work on each of a list of files
15244 with recursion. A recursive version of @code{lengths-list-many-files}
15245 is short and simple.
15247 The recursive function has the usual parts: the do-again-test, the
15248 next-step-expression, and the recursive call. The do-again-test
15249 determines whether the function should call itself again, which it
15250 will do if the @code{list-of-files} contains any remaining elements;
15251 the next-step-expression resets the @code{list-of-files} to the
15252 @sc{cdr} of itself, so eventually the list will be empty; and the
15253 recursive call calls itself on the shorter list. The complete
15254 function is shorter than this description!
15255 @findex recursive-lengths-list-many-files
15259 (defun recursive-lengths-list-many-files (list-of-files)
15260 "Return list of lengths of each defun in LIST-OF-FILES."
15261 (if list-of-files ; @r{do-again-test}
15264 (expand-file-name (car list-of-files)))
15265 (recursive-lengths-list-many-files
15266 (cdr list-of-files)))))
15271 In a sentence, the function returns the lengths' list for the first of
15272 the @code{list-of-files} appended to the result of calling itself on
15273 the rest of the @code{list-of-files}.
15275 Here is a test of @code{recursive-lengths-list-many-files}, along with
15276 the results of running @code{lengths-list-file} on each of the files
15279 Install @code{recursive-lengths-list-many-files} and
15280 @code{lengths-list-file}, if necessary, and then evaluate the
15281 following expressions. You may need to change the files' pathnames;
15282 those here work when this Info file and the Emacs sources are located
15283 in their customary places. To change the expressions, copy them to
15284 the @file{*scratch*} buffer, edit them, and then evaluate them.
15286 The results are shown after the @samp{@result{}}. (These results are
15287 for files from Emacs version 22.1.1; files from other versions of
15288 Emacs may produce different results.)
15290 @c !!! 22.1.1 lisp sources location here
15293 (cd "/usr/local/share/emacs/22.1.1/")
15295 (lengths-list-file "./lisp/macros.el")
15296 @result{} (283 263 480 90)
15300 (lengths-list-file "./lisp/mail/mailalias.el")
15301 @result{} (38 32 29 95 178 180 321 218 324)
15305 (lengths-list-file "./lisp/makesum.el")
15310 (recursive-lengths-list-many-files
15311 '("./lisp/macros.el"
15312 "./lisp/mail/mailalias.el"
15313 "./lisp/makesum.el"))
15314 @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181)
15318 The @code{recursive-lengths-list-many-files} function produces the
15321 The next step is to prepare the data in the list for display in a graph.
15323 @node Prepare the data
15324 @section Prepare the Data for Display in a Graph
15326 The @code{recursive-lengths-list-many-files} function returns a list
15327 of numbers. Each number records the length of a function definition.
15328 What we need to do now is transform this data into a list of numbers
15329 suitable for generating a graph. The new list will tell how many
15330 functions definitions contain less than 10 words and
15331 symbols, how many contain between 10 and 19 words and symbols, how
15332 many contain between 20 and 29 words and symbols, and so on.
15334 In brief, we need to go through the lengths' list produced by the
15335 @code{recursive-lengths-list-many-files} function and count the number
15336 of defuns within each range of lengths, and produce a list of those
15340 * Data for Display in Detail::
15341 * Sorting:: Sorting lists.
15342 * Files List:: Making a list of files.
15343 * Counting function definitions::
15347 @node Data for Display in Detail
15348 @unnumberedsubsec The Data for Display in Detail
15351 Based on what we have done before, we can readily foresee that it
15352 should not be too hard to write a function that @sc{cdr}s down the
15353 lengths' list, looks at each element, determines which length range it
15354 is in, and increments a counter for that range.
15356 However, before beginning to write such a function, we should consider
15357 the advantages of sorting the lengths' list first, so the numbers are
15358 ordered from smallest to largest. First, sorting will make it easier
15359 to count the numbers in each range, since two adjacent numbers will
15360 either be in the same length range or in adjacent ranges. Second, by
15361 inspecting a sorted list, we can discover the highest and lowest
15362 number, and thereby determine the largest and smallest length range
15366 @subsection Sorting Lists
15369 Emacs contains a function to sort lists, called (as you might guess)
15370 @code{sort}. The @code{sort} function takes two arguments, the list
15371 to be sorted, and a predicate that determines whether the first of
15372 two list elements is less than the second.
15374 As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong
15375 Type Object as an Argument}), a predicate is a function that
15376 determines whether some property is true or false. The @code{sort}
15377 function will reorder a list according to whatever property the
15378 predicate uses; this means that @code{sort} can be used to sort
15379 non-numeric lists by non-numeric criteria---it can, for example,
15380 alphabetize a list.
15383 The @code{<} function is used when sorting a numeric list. For example,
15386 (sort '(4 8 21 17 33 7 21 7) '<)
15394 (4 7 7 8 17 21 21 33)
15398 (Note that in this example, both the arguments are quoted so that the
15399 symbols are not evaluated before being passed to @code{sort} as
15402 Sorting the list returned by the
15403 @code{recursive-lengths-list-many-files} function is straightforward;
15404 it uses the @code{<} function:
15408 In GNU Emacs 22, eval
15410 (cd "/usr/local/share/emacs/22.0.50/")
15412 (recursive-lengths-list-many-files
15413 '("./lisp/macros.el"
15414 "./lisp/mail/mailalias.el"
15415 "./lisp/makesum.el"))
15423 (recursive-lengths-list-many-files
15424 '("./lisp/macros.el"
15425 "./lisp/mailalias.el"
15426 "./lisp/makesum.el"))
15436 (29 32 38 85 90 95 178 180 181 218 263 283 321 324 480)
15440 (Note that in this example, the first argument to @code{sort} is not
15441 quoted, since the expression must be evaluated so as to produce the
15442 list that is passed to @code{sort}.)
15445 @subsection Making a List of Files
15447 The @code{recursive-lengths-list-many-files} function requires a list
15448 of files as its argument. For our test examples, we constructed such
15449 a list by hand; but the Emacs Lisp source directory is too large for
15450 us to do for that. Instead, we will write a function to do the job
15451 for us. In this function, we will use both a @code{while} loop and a
15454 @findex directory-files
15455 We did not have to write a function like this for older versions of
15456 GNU Emacs, since they placed all the @samp{.el} files in one
15457 directory. Instead, we were able to use the @code{directory-files}
15458 function, which lists the names of files that match a specified
15459 pattern within a single directory.
15461 However, recent versions of Emacs place Emacs Lisp files in
15462 sub-directories of the top level @file{lisp} directory. This
15463 re-arrangement eases navigation. For example, all the mail related
15464 files are in a @file{lisp} sub-directory called @file{mail}. But at
15465 the same time, this arrangement forces us to create a file listing
15466 function that descends into the sub-directories.
15468 @findex files-in-below-directory
15469 We can create this function, called @code{files-in-below-directory},
15470 using familiar functions such as @code{car}, @code{nthcdr}, and
15471 @code{substring} in conjunction with an existing function called
15472 @code{directory-files-and-attributes}. This latter function not only
15473 lists all the filenames in a directory, including the names
15474 of sub-directories, but also their attributes.
15476 To restate our goal: to create a function that will enable us
15477 to feed filenames to @code{recursive-lengths-list-many-files}
15478 as a list that looks like this (but with more elements):
15482 ("./lisp/macros.el"
15483 "./lisp/mail/rmail.el"
15484 "./lisp/makesum.el")
15488 The @code{directory-files-and-attributes} function returns a list of
15489 lists. Each of the lists within the main list consists of 13
15490 elements. The first element is a string that contains the name of the
15491 file---which, in GNU/Linux, may be a @dfn{directory file}, that is to
15492 say, a file with the special attributes of a directory. The second
15493 element of the list is @code{t} for a directory, a string
15494 for symbolic link (the string is the name linked to), or @code{nil}.
15496 For example, the first @samp{.el} file in the @file{lisp/} directory
15497 is @file{abbrev.el}. Its name is
15498 @file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a
15499 directory or a symbolic link.
15502 This is how @code{directory-files-and-attributes} lists that file and
15514 (20615 27034 579989 697000)
15516 (20615 26327 734791 805000)
15528 On the other hand, @file{mail/} is a directory within the @file{lisp/}
15529 directory. The beginning of its listing looks like this:
15540 (To learn about the different attributes, look at the documentation of
15541 @code{file-attributes}. Bear in mind that the @code{file-attributes}
15542 function does not list the filename, so its first element is
15543 @code{directory-files-and-attributes}'s second element.)
15545 We will want our new function, @code{files-in-below-directory}, to
15546 list the @samp{.el} files in the directory it is told to check, and in
15547 any directories below that directory.
15549 This gives us a hint on how to construct
15550 @code{files-in-below-directory}: within a directory, the function
15551 should add @samp{.el} filenames to a list; and if, within a directory,
15552 the function comes upon a sub-directory, it should go into that
15553 sub-directory and repeat its actions.
15555 However, we should note that every directory contains a name that
15556 refers to itself, called @file{.} (``dot''), and a name that refers to
15557 its parent directory, called @file{..} (``dot dot''). (In
15558 @file{/}, the root directory, @file{..} refers to itself, since
15559 @file{/} has no parent.) Clearly, we do not want our
15560 @code{files-in-below-directory} function to enter those directories,
15561 since they always lead us, directly or indirectly, to the current
15564 Consequently, our @code{files-in-below-directory} function must do
15569 Check to see whether it is looking at a filename that ends in
15570 @samp{.el}; and if so, add its name to a list.
15573 Check to see whether it is looking at a filename that is the name of a
15574 directory; and if so,
15578 Check to see whether it is looking at @file{.} or @file{..}; and if
15582 Or else, go into that directory and repeat the process.
15586 Let's write a function definition to do these tasks. We will use a
15587 @code{while} loop to move from one filename to another within a
15588 directory, checking what needs to be done; and we will use a recursive
15589 call to repeat the actions on each sub-directory. The recursive
15590 pattern is Accumulate
15591 (@pxref{Accumulate}),
15592 using @code{append} as the combiner.
15595 (directory-files "/usr/local/src/emacs/lisp/" t "\\.el$")
15596 (shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'")
15598 (directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$")
15599 (shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'")
15602 @c /usr/local/share/emacs/22.1.1/lisp/
15605 Here is the function:
15609 (defun files-in-below-directory (directory)
15610 "List the .el files in DIRECTORY and in its sub-directories."
15611 ;; Although the function will be used non-interactively,
15612 ;; it will be easier to test if we make it interactive.
15613 ;; The directory will have a name such as
15614 ;; "/usr/local/share/emacs/22.1.1/lisp/"
15615 (interactive "DDirectory name: ")
15618 (let (el-files-list
15619 (current-directory-list
15620 (directory-files-and-attributes directory t)))
15621 ;; while we are in the current directory
15622 (while current-directory-list
15626 ;; check to see whether filename ends in '.el'
15627 ;; and if so, append its name to a list.
15628 ((equal ".el" (substring (car (car current-directory-list)) -3))
15629 (setq el-files-list
15630 (cons (car (car current-directory-list)) el-files-list)))
15633 ;; check whether filename is that of a directory
15634 ((eq t (car (cdr (car current-directory-list))))
15635 ;; decide whether to skip or recurse
15638 (substring (car (car current-directory-list)) -1))
15639 ;; then do nothing since filename is that of
15640 ;; current directory or parent, "." or ".."
15644 ;; else descend into the directory and repeat the process
15645 (setq el-files-list
15647 (files-in-below-directory
15648 (car (car current-directory-list)))
15650 ;; move to the next filename in the list; this also
15651 ;; shortens the list so the while loop eventually comes to an end
15652 (setq current-directory-list (cdr current-directory-list)))
15653 ;; return the filenames
15658 @c (files-in-below-directory "/usr/local/src/emacs/lisp/")
15659 @c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
15661 The @code{files-in-below-directory} @code{directory-files} function
15662 takes one argument, the name of a directory.
15665 Thus, on my system,
15667 @c (length (files-in-below-directory "/usr/local/src/emacs/lisp/"))
15669 @c !!! 22.1.1 lisp sources location here
15673 (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/"))
15678 tells me that in and below my Lisp sources directory are 1031
15681 @code{files-in-below-directory} returns a list in reverse alphabetical
15682 order. An expression to sort the list in alphabetical order looks
15688 (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
15695 "Test how long it takes to find lengths of all sorted elisp defuns."
15696 (insert "\n" (current-time-string) "\n")
15699 (recursive-lengths-list-many-files
15700 (files-in-below-directory "/usr/local/src/emacs/lisp/"))
15702 (insert (format "%s" (current-time-string))))
15705 @node Counting function definitions
15706 @subsection Counting function definitions
15708 Our immediate goal is to generate a list that tells us how many
15709 function definitions contain fewer than 10 words and symbols, how many
15710 contain between 10 and 19 words and symbols, how many contain between
15711 20 and 29 words and symbols, and so on.
15713 With a sorted list of numbers, this is easy: count how many elements
15714 of the list are smaller than 10, then, after moving past the numbers
15715 just counted, count how many are smaller than 20, then, after moving
15716 past the numbers just counted, count how many are smaller than 30, and
15717 so on. Each of the numbers, 10, 20, 30, 40, and the like, is one
15718 larger than the top of that range. We can call the list of such
15719 numbers the @code{top-of-ranges} list.
15722 If we wished, we could generate this list automatically, but it is
15723 simpler to write a list manually. Here it is:
15724 @vindex top-of-ranges
15728 (defvar top-of-ranges
15731 110 120 130 140 150
15732 160 170 180 190 200
15733 210 220 230 240 250
15734 260 270 280 290 300)
15735 "List specifying ranges for `defuns-per-range'.")
15739 To change the ranges, we edit this list.
15741 Next, we need to write the function that creates the list of the
15742 number of definitions within each range. Clearly, this function must
15743 take the @code{sorted-lengths} and the @code{top-of-ranges} lists
15746 The @code{defuns-per-range} function must do two things again and
15747 again: it must count the number of definitions within a range
15748 specified by the current top-of-range value; and it must shift to the
15749 next higher value in the @code{top-of-ranges} list after counting the
15750 number of definitions in the current range. Since each of these
15751 actions is repetitive, we can use @code{while} loops for the job.
15752 One loop counts the number of definitions in the range defined by the
15753 current top-of-range value, and the other loop selects each of the
15754 top-of-range values in turn.
15756 Several entries of the @code{sorted-lengths} list are counted for each
15757 range; this means that the loop for the @code{sorted-lengths} list
15758 will be inside the loop for the @code{top-of-ranges} list, like a
15759 small gear inside a big gear.
15761 The inner loop counts the number of definitions within the range. It
15762 is a simple counting loop of the type we have seen before.
15763 (@xref{Incrementing Loop, , A loop with an incrementing counter}.)
15764 The true-or-false test of the loop tests whether the value from the
15765 @code{sorted-lengths} list is smaller than the current value of the
15766 top of the range. If it is, the function increments the counter and
15767 tests the next value from the @code{sorted-lengths} list.
15770 The inner loop looks like this:
15774 (while @var{length-element-smaller-than-top-of-range}
15775 (setq number-within-range (1+ number-within-range))
15776 (setq sorted-lengths (cdr sorted-lengths)))
15780 The outer loop must start with the lowest value of the
15781 @code{top-of-ranges} list, and then be set to each of the succeeding
15782 higher values in turn. This can be done with a loop like this:
15786 (while top-of-ranges
15787 @var{body-of-loop}@dots{}
15788 (setq top-of-ranges (cdr top-of-ranges)))
15793 Put together, the two loops look like this:
15797 (while top-of-ranges
15799 ;; @r{Count the number of elements within the current range.}
15800 (while @var{length-element-smaller-than-top-of-range}
15801 (setq number-within-range (1+ number-within-range))
15802 (setq sorted-lengths (cdr sorted-lengths)))
15804 ;; @r{Move to next range.}
15805 (setq top-of-ranges (cdr top-of-ranges)))
15809 In addition, in each circuit of the outer loop, Emacs should record
15810 the number of definitions within that range (the value of
15811 @code{number-within-range}) in a list. We can use @code{cons} for
15812 this purpose. (@xref{cons, , @code{cons}}.)
15814 The @code{cons} function works fine, except that the list it
15815 constructs will contain the number of definitions for the highest
15816 range at its beginning and the number of definitions for the lowest
15817 range at its end. This is because @code{cons} attaches new elements
15818 of the list to the beginning of the list, and since the two loops are
15819 working their way through the lengths' list from the lower end first,
15820 the @code{defuns-per-range-list} will end up largest number first.
15821 But we will want to print our graph with smallest values first and the
15822 larger later. The solution is to reverse the order of the
15823 @code{defuns-per-range-list}. We can do this using the
15824 @code{nreverse} function, which reverses the order of a list.
15831 (nreverse '(1 2 3 4))
15842 Note that the @code{nreverse} function is destructive---that is,
15843 it changes the list to which it is applied; this contrasts with the
15844 @code{car} and @code{cdr} functions, which are non-destructive. In
15845 this case, we do not want the original @code{defuns-per-range-list},
15846 so it does not matter that it is destroyed. (The @code{reverse}
15847 function provides a reversed copy of a list, leaving the original list
15852 Put all together, the @code{defuns-per-range} looks like this:
15856 (defun defuns-per-range (sorted-lengths top-of-ranges)
15857 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
15858 (let ((top-of-range (car top-of-ranges))
15859 (number-within-range 0)
15860 defuns-per-range-list)
15865 (while top-of-ranges
15871 ;; @r{Need number for numeric test.}
15872 (car sorted-lengths)
15873 (< (car sorted-lengths) top-of-range))
15877 ;; @r{Count number of definitions within current range.}
15878 (setq number-within-range (1+ number-within-range))
15879 (setq sorted-lengths (cdr sorted-lengths)))
15881 ;; @r{Exit inner loop but remain within outer loop.}
15885 (setq defuns-per-range-list
15886 (cons number-within-range defuns-per-range-list))
15887 (setq number-within-range 0) ; @r{Reset count to zero.}
15891 ;; @r{Move to next range.}
15892 (setq top-of-ranges (cdr top-of-ranges))
15893 ;; @r{Specify next top of range value.}
15894 (setq top-of-range (car top-of-ranges)))
15898 ;; @r{Exit outer loop and count the number of defuns larger than}
15899 ;; @r{ the largest top-of-range value.}
15900 (setq defuns-per-range-list
15902 (length sorted-lengths)
15903 defuns-per-range-list))
15907 ;; @r{Return a list of the number of definitions within each range,}
15908 ;; @r{ smallest to largest.}
15909 (nreverse defuns-per-range-list)))
15915 The function is straightforward except for one subtle feature. The
15916 true-or-false test of the inner loop looks like this:
15920 (and (car sorted-lengths)
15921 (< (car sorted-lengths) top-of-range))
15927 instead of like this:
15930 (< (car sorted-lengths) top-of-range)
15933 The purpose of the test is to determine whether the first item in the
15934 @code{sorted-lengths} list is less than the value of the top of the
15937 The simple version of the test works fine unless the
15938 @code{sorted-lengths} list has a @code{nil} value. In that case, the
15939 @code{(car sorted-lengths)} expression function returns
15940 @code{nil}. The @code{<} function cannot compare a number to
15941 @code{nil}, which is an empty list, so Emacs signals an error and
15942 stops the function from attempting to continue to execute.
15944 The @code{sorted-lengths} list always becomes @code{nil} when the
15945 counter reaches the end of the list. This means that any attempt to
15946 use the @code{defuns-per-range} function with the simple version of
15947 the test will fail.
15949 We solve the problem by using the @code{(car sorted-lengths)}
15950 expression in conjunction with the @code{and} expression. The
15951 @code{(car sorted-lengths)} expression returns a non-@code{nil}
15952 value so long as the list has at least one number within it, but
15953 returns @code{nil} if the list is empty. The @code{and} expression
15954 first evaluates the @code{(car sorted-lengths)} expression, and
15955 if it is @code{nil}, returns false @emph{without} evaluating the
15956 @code{<} expression. But if the @code{(car sorted-lengths)}
15957 expression returns a non-@code{nil} value, the @code{and} expression
15958 evaluates the @code{<} expression, and returns that value as the value
15959 of the @code{and} expression.
15961 @c colon in printed section title causes problem in Info cross reference
15962 This way, we avoid an error.
15965 (For information about @code{and}, see
15966 @ref{kill-new function, , The @code{kill-new} function}.)
15970 (@xref{kill-new function, , The @code{kill-new} function}, for
15971 information about @code{and}.)
15974 Here is a short test of the @code{defuns-per-range} function. First,
15975 evaluate the expression that binds (a shortened)
15976 @code{top-of-ranges} list to the list of values, then evaluate the
15977 expression for binding the @code{sorted-lengths} list, and then
15978 evaluate the @code{defuns-per-range} function.
15982 ;; @r{(Shorter list than we will use later.)}
15983 (setq top-of-ranges
15984 '(110 120 130 140 150
15985 160 170 180 190 200))
15987 (setq sorted-lengths
15988 '(85 86 110 116 122 129 154 176 179 200 265 300 300))
15990 (defuns-per-range sorted-lengths top-of-ranges)
15996 The list returned looks like this:
15999 (2 2 2 0 0 1 0 2 0 0 4)
16003 Indeed, there are two elements of the @code{sorted-lengths} list
16004 smaller than 110, two elements between 110 and 119, two elements
16005 between 120 and 129, and so on. There are four elements with a value
16008 @c The next step is to turn this numbers' list into a graph.
16009 @node Readying a Graph
16010 @chapter Readying a Graph
16011 @cindex Readying a graph
16012 @cindex Graph prototype
16013 @cindex Prototype graph
16014 @cindex Body of graph
16016 Our goal is to construct a graph showing the numbers of function
16017 definitions of various lengths in the Emacs lisp sources.
16019 As a practical matter, if you were creating a graph, you would
16020 probably use a program such as @code{gnuplot} to do the job.
16021 (@code{gnuplot} is nicely integrated into GNU Emacs.) In this case,
16022 however, we create one from scratch, and in the process we will
16023 re-acquaint ourselves with some of what we learned before and learn
16026 In this chapter, we will first write a simple graph printing function.
16027 This first definition will be a @dfn{prototype}, a rapidly written
16028 function that enables us to reconnoiter this unknown graph-making
16029 territory. We will discover dragons, or find that they are myth.
16030 After scouting the terrain, we will feel more confident and enhance
16031 the function to label the axes automatically.
16034 * Columns of a graph::
16035 * graph-body-print:: How to print the body of a graph.
16036 * recursive-graph-body-print::
16038 * Line Graph Exercise::
16042 @node Columns of a graph
16043 @unnumberedsec Printing the Columns of a Graph
16046 Since Emacs is designed to be flexible and work with all kinds of
16047 terminals, including character-only terminals, the graph will need to
16048 be made from one of the typewriter symbols. An asterisk will do; as
16049 we enhance the graph-printing function, we can make the choice of
16050 symbol a user option.
16052 We can call this function @code{graph-body-print}; it will take a
16053 @code{numbers-list} as its only argument. At this stage, we will not
16054 label the graph, but only print its body.
16056 The @code{graph-body-print} function inserts a vertical column of
16057 asterisks for each element in the @code{numbers-list}. The height of
16058 each line is determined by the value of that element of the
16059 @code{numbers-list}.
16061 Inserting columns is a repetitive act; that means that this function can
16062 be written either with a @code{while} loop or recursively.
16064 Our first challenge is to discover how to print a column of asterisks.
16065 Usually, in Emacs, we print characters onto a screen horizontally,
16066 line by line, by typing. We have two routes we can follow: write our
16067 own column-insertion function or discover whether one exists in Emacs.
16069 To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
16070 command. This command is like the @kbd{C-h a} (@code{command-apropos})
16071 command, except that the latter finds only those functions that are
16072 commands. The @kbd{M-x apropos} command lists all symbols that match
16073 a regular expression, including functions that are not interactive.
16076 What we want to look for is some command that prints or inserts
16077 columns. Very likely, the name of the function will contain either
16078 the word ``print'' or the word ``insert'' or the word ``column''.
16079 Therefore, we can simply type @kbd{M-x apropos RET
16080 print\|insert\|column RET} and look at the result. On my system, this
16081 command once took quite some time, and then produced a list of 79
16082 functions and variables. Now it does not take much time at all and
16083 produces a list of 211 functions and variables. Scanning down the
16084 list, the only function that looks as if it might do the job is
16085 @code{insert-rectangle}.
16088 Indeed, this is the function we want; its documentation says:
16093 Insert text of RECTANGLE with upper left corner at point.
16094 RECTANGLE's first line is inserted at point,
16095 its second line is inserted at a point vertically under point, etc.
16096 RECTANGLE should be a list of strings.
16097 After this command, the mark is at the upper left corner
16098 and point is at the lower right corner.
16102 We can run a quick test, to make sure it does what we expect of it.
16104 Here is the result of placing the cursor after the
16105 @code{insert-rectangle} expression and typing @kbd{C-u C-x C-e}
16106 (@code{eval-last-sexp}). The function inserts the strings
16107 @samp{"first"}, @samp{"second"}, and @samp{"third"} at and below
16108 point. Also the function returns @code{nil}.
16112 (insert-rectangle '("first" "second" "third"))first
16119 Of course, we won't be inserting the text of the
16120 @code{insert-rectangle} expression itself into the buffer in which we
16121 are making the graph, but will call the function from our program. We
16122 shall, however, have to make sure that point is in the buffer at the
16123 place where the @code{insert-rectangle} function will insert its
16126 If you are reading this in Info, you can see how this works by
16127 switching to another buffer, such as the @file{*scratch*} buffer,
16128 placing point somewhere in the buffer, typing @kbd{M-:}, typing the
16129 @code{insert-rectangle} expression into the minibuffer at the prompt,
16130 and then typing @key{RET}. This causes Emacs to evaluate the
16131 expression in the minibuffer, but to use as the value of point the
16132 position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the
16133 keybinding for @code{eval-expression}. Also, @code{nil} does not
16134 appear in the @file{*scratch*} buffer since the expression is
16135 evaluated in the minibuffer.)
16137 We find when we do this that point ends up at the end of the last
16138 inserted line---that is to say, this function moves point as a
16139 side-effect. If we were to repeat the command, with point at this
16140 position, the next insertion would be below and to the right of the
16141 previous insertion. We don't want this! If we are going to make a
16142 bar graph, the columns need to be beside each other.
16144 So we discover that each cycle of the column-inserting @code{while}
16145 loop must reposition point to the place we want it, and that place
16146 will be at the top, not the bottom, of the column. Moreover, we
16147 remember that when we print a graph, we do not expect all the columns
16148 to be the same height. This means that the top of each column may be
16149 at a different height from the previous one. We cannot simply
16150 reposition point to the same line each time, but moved over to the
16151 right---or perhaps we can@dots{}
16153 We are planning to make the columns of the bar graph out of asterisks.
16154 The number of asterisks in the column is the number specified by the
16155 current element of the @code{numbers-list}. We need to construct a
16156 list of asterisks of the right length for each call to
16157 @code{insert-rectangle}. If this list consists solely of the requisite
16158 number of asterisks, then we will have to position point the right number
16159 of lines above the base for the graph to print correctly. This could
16162 Alternatively, if we can figure out some way to pass
16163 @code{insert-rectangle} a list of the same length each time, then we
16164 can place point on the same line each time, but move it over one
16165 column to the right for each new column. If we do this, however, some
16166 of the entries in the list passed to @code{insert-rectangle} must be
16167 blanks rather than asterisks. For example, if the maximum height of
16168 the graph is 5, but the height of the column is 3, then
16169 @code{insert-rectangle} requires an argument that looks like this:
16172 (" " " " "*" "*" "*")
16175 This last proposal is not so difficult, so long as we can determine
16176 the column height. There are two ways for us to specify the column
16177 height: we can arbitrarily state what it will be, which would work
16178 fine for graphs of that height; or we can search through the list of
16179 numbers and use the maximum height of the list as the maximum height
16180 of the graph. If the latter operation were difficult, then the former
16181 procedure would be easiest, but there is a function built into Emacs
16182 that determines the maximum of its arguments. We can use that
16183 function. The function is called @code{max} and it returns the
16184 largest of all its arguments, which must be numbers. Thus, for
16192 returns 7. (A corresponding function called @code{min} returns the
16193 smallest of all its arguments.)
16197 However, we cannot simply call @code{max} on the @code{numbers-list};
16198 the @code{max} function expects numbers as its argument, not a list of
16199 numbers. Thus, the following expression,
16202 (max '(3 4 6 5 7 3))
16207 produces the following error message;
16210 Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3)
16214 We need a function that passes a list of arguments to a function.
16215 This function is @code{apply}. This function applies its first
16216 argument (a function) to its remaining arguments, the last of which
16223 (apply 'max 3 4 7 3 '(4 8 5))
16229 (Incidentally, I don't know how you would learn of this function
16230 without a book such as this. It is possible to discover other
16231 functions, like @code{search-forward} or @code{insert-rectangle}, by
16232 guessing at a part of their names and then using @code{apropos}. Even
16233 though its base in metaphor is clear---apply its first argument to
16234 the rest---I doubt a novice would come up with that particular word
16235 when using @code{apropos} or other aid. Of course, I could be wrong;
16236 after all, the function was first named by someone who had to invent
16239 The second and subsequent arguments to @code{apply} are optional, so
16240 we can use @code{apply} to call a function and pass the elements of a
16241 list to it, like this, which also returns 8:
16244 (apply 'max '(4 8 5))
16247 This latter way is how we will use @code{apply}. The
16248 @code{recursive-lengths-list-many-files} function returns a numbers'
16249 list to which we can apply @code{max} (we could also apply @code{max} to
16250 the sorted numbers' list; it does not matter whether the list is
16254 Hence, the operation for finding the maximum height of the graph is this:
16257 (setq max-graph-height (apply 'max numbers-list))
16260 Now we can return to the question of how to create a list of strings
16261 for a column of the graph. Told the maximum height of the graph
16262 and the number of asterisks that should appear in the column, the
16263 function should return a list of strings for the
16264 @code{insert-rectangle} command to insert.
16266 Each column is made up of asterisks or blanks. Since the function is
16267 passed the value of the height of the column and the number of
16268 asterisks in the column, the number of blanks can be found by
16269 subtracting the number of asterisks from the height of the column.
16270 Given the number of blanks and the number of asterisks, two
16271 @code{while} loops can be used to construct the list:
16275 ;;; @r{First version.}
16276 (defun column-of-graph (max-graph-height actual-height)
16277 "Return list of strings that is one column of a graph."
16278 (let ((insert-list nil)
16279 (number-of-top-blanks
16280 (- max-graph-height actual-height)))
16284 ;; @r{Fill in asterisks.}
16285 (while (> actual-height 0)
16286 (setq insert-list (cons "*" insert-list))
16287 (setq actual-height (1- actual-height)))
16291 ;; @r{Fill in blanks.}
16292 (while (> number-of-top-blanks 0)
16293 (setq insert-list (cons " " insert-list))
16294 (setq number-of-top-blanks
16295 (1- number-of-top-blanks)))
16299 ;; @r{Return whole list.}
16304 If you install this function and then evaluate the following
16305 expression you will see that it returns the list as desired:
16308 (column-of-graph 5 3)
16316 (" " " " "*" "*" "*")
16319 As written, @code{column-of-graph} contains a major flaw: the symbols
16320 used for the blank and for the marked entries in the column are
16321 hard-coded as a space and asterisk. This is fine for a prototype,
16322 but you, or another user, may wish to use other symbols. For example,
16323 in testing the graph function, you may want to use a period in place
16324 of the space, to make sure the point is being repositioned properly
16325 each time the @code{insert-rectangle} function is called; or you might
16326 want to substitute a @samp{+} sign or other symbol for the asterisk.
16327 You might even want to make a graph-column that is more than one
16328 display column wide. The program should be more flexible. The way to
16329 do that is to replace the blank and the asterisk with two variables
16330 that we can call @code{graph-blank} and @code{graph-symbol} and define
16331 those variables separately.
16333 Also, the documentation is not well written. These considerations
16334 lead us to the second version of the function:
16338 (defvar graph-symbol "*"
16339 "String used as symbol in graph, usually an asterisk.")
16343 (defvar graph-blank " "
16344 "String used as blank in graph, usually a blank space.
16345 graph-blank must be the same number of columns wide
16351 (For an explanation of @code{defvar}, see
16352 @ref{defvar, , Initializing a Variable with @code{defvar}}.)
16356 ;;; @r{Second version.}
16357 (defun column-of-graph (max-graph-height actual-height)
16358 "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols.
16362 The graph-symbols are contiguous entries at the end
16364 The list will be inserted as one column of a graph.
16365 The strings are either graph-blank or graph-symbol."
16369 (let ((insert-list nil)
16370 (number-of-top-blanks
16371 (- max-graph-height actual-height)))
16375 ;; @r{Fill in @code{graph-symbols}.}
16376 (while (> actual-height 0)
16377 (setq insert-list (cons graph-symbol insert-list))
16378 (setq actual-height (1- actual-height)))
16382 ;; @r{Fill in @code{graph-blanks}.}
16383 (while (> number-of-top-blanks 0)
16384 (setq insert-list (cons graph-blank insert-list))
16385 (setq number-of-top-blanks
16386 (1- number-of-top-blanks)))
16388 ;; @r{Return whole list.}
16393 If we wished, we could rewrite @code{column-of-graph} a third time to
16394 provide optionally for a line graph as well as for a bar graph. This
16395 would not be hard to do. One way to think of a line graph is that it
16396 is no more than a bar graph in which the part of each bar that is
16397 below the top is blank. To construct a column for a line graph, the
16398 function first constructs a list of blanks that is one shorter than
16399 the value, then it uses @code{cons} to attach a graph symbol to the
16400 list; then it uses @code{cons} again to attach the top blanks to
16403 It is easy to see how to write such a function, but since we don't
16404 need it, we will not do it. But the job could be done, and if it were
16405 done, it would be done with @code{column-of-graph}. Even more
16406 important, it is worth noting that few changes would have to be made
16407 anywhere else. The enhancement, if we ever wish to make it, is
16410 Now, finally, we come to our first actual graph printing function.
16411 This prints the body of a graph, not the labels for the vertical and
16412 horizontal axes, so we can call this @code{graph-body-print}.
16414 @node graph-body-print
16415 @section The @code{graph-body-print} Function
16416 @findex graph-body-print
16418 After our preparation in the preceding section, the
16419 @code{graph-body-print} function is straightforward. The function
16420 will print column after column of asterisks and blanks, using the
16421 elements of a numbers' list to specify the number of asterisks in each
16422 column. This is a repetitive act, which means we can use a
16423 decrementing @code{while} loop or recursive function for the job. In
16424 this section, we will write the definition using a @code{while} loop.
16426 The @code{column-of-graph} function requires the height of the graph
16427 as an argument, so we should determine and record that as a local variable.
16429 This leads us to the following template for the @code{while} loop
16430 version of this function:
16434 (defun graph-body-print (numbers-list)
16435 "@var{documentation}@dots{}"
16436 (let ((height @dots{}
16441 (while numbers-list
16442 @var{insert-columns-and-reposition-point}
16443 (setq numbers-list (cdr numbers-list)))))
16448 We need to fill in the slots of the template.
16450 Clearly, we can use the @code{(apply 'max numbers-list)} expression to
16451 determine the height of the graph.
16453 The @code{while} loop will cycle through the @code{numbers-list} one
16454 element at a time. As it is shortened by the @code{(setq numbers-list
16455 (cdr numbers-list))} expression, the @sc{car} of each instance of the
16456 list is the value of the argument for @code{column-of-graph}.
16458 At each cycle of the @code{while} loop, the @code{insert-rectangle}
16459 function inserts the list returned by @code{column-of-graph}. Since
16460 the @code{insert-rectangle} function moves point to the lower right of
16461 the inserted rectangle, we need to save the location of point at the
16462 time the rectangle is inserted, move back to that position after the
16463 rectangle is inserted, and then move horizontally to the next place
16464 from which @code{insert-rectangle} is called.
16466 If the inserted columns are one character wide, as they will be if
16467 single blanks and asterisks are used, the repositioning command is
16468 simply @code{(forward-char 1)}; however, the width of a column may be
16469 greater than one. This means that the repositioning command should be
16470 written @code{(forward-char symbol-width)}. The @code{symbol-width}
16471 itself is the length of a @code{graph-blank} and can be found using
16472 the expression @code{(length graph-blank)}. The best place to bind
16473 the @code{symbol-width} variable to the value of the width of graph
16474 column is in the varlist of the @code{let} expression.
16477 These considerations lead to the following function definition:
16481 (defun graph-body-print (numbers-list)
16482 "Print a bar graph of the NUMBERS-LIST.
16483 The numbers-list consists of the Y-axis values."
16485 (let ((height (apply 'max numbers-list))
16486 (symbol-width (length graph-blank))
16491 (while numbers-list
16492 (setq from-position (point))
16494 (column-of-graph height (car numbers-list)))
16495 (goto-char from-position)
16496 (forward-char symbol-width)
16499 ;; @r{Draw graph column by column.}
16501 (setq numbers-list (cdr numbers-list)))
16504 ;; @r{Place point for X axis labels.}
16505 (forward-line height)
16512 The one unexpected expression in this function is the
16513 @w{@code{(sit-for 0)}} expression in the @code{while} loop. This
16514 expression makes the graph printing operation more interesting to
16515 watch than it would be otherwise. The expression causes Emacs to
16516 @dfn{sit} or do nothing for a zero length of time and then redraw the
16517 screen. Placed here, it causes Emacs to redraw the screen column by
16518 column. Without it, Emacs would not redraw the screen until the
16521 We can test @code{graph-body-print} with a short list of numbers.
16525 Install @code{graph-symbol}, @code{graph-blank},
16526 @code{column-of-graph}, which are in
16528 @ref{Readying a Graph, , Readying a Graph},
16531 @ref{Columns of a graph},
16533 and @code{graph-body-print}.
16537 Copy the following expression:
16540 (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3))
16544 Switch to the @file{*scratch*} buffer and place the cursor where you
16545 want the graph to start.
16548 Type @kbd{M-:} (@code{eval-expression}).
16551 Yank the @code{graph-body-print} expression into the minibuffer
16552 with @kbd{C-y} (@code{yank)}.
16555 Press @key{RET} to evaluate the @code{graph-body-print} expression.
16559 Emacs will print a graph like this:
16573 @node recursive-graph-body-print
16574 @section The @code{recursive-graph-body-print} Function
16575 @findex recursive-graph-body-print
16577 The @code{graph-body-print} function may also be written recursively.
16578 The recursive solution is divided into two parts: an outside wrapper
16579 that uses a @code{let} expression to determine the values of several
16580 variables that need only be found once, such as the maximum height of
16581 the graph, and an inside function that is called recursively to print
16585 The wrapper is uncomplicated:
16589 (defun recursive-graph-body-print (numbers-list)
16590 "Print a bar graph of the NUMBERS-LIST.
16591 The numbers-list consists of the Y-axis values."
16592 (let ((height (apply 'max numbers-list))
16593 (symbol-width (length graph-blank))
16595 (recursive-graph-body-print-internal
16602 The recursive function is a little more difficult. It has four parts:
16603 the do-again-test, the printing code, the recursive call, and the
16604 next-step-expression. The do-again-test is a @code{when}
16605 expression that determines whether the @code{numbers-list} contains
16606 any remaining elements; if it does, the function prints one column of
16607 the graph using the printing code and calls itself again. The
16608 function calls itself again according to the value produced by the
16609 next-step-expression which causes the call to act on a shorter
16610 version of the @code{numbers-list}.
16614 (defun recursive-graph-body-print-internal
16615 (numbers-list height symbol-width)
16616 "Print a bar graph.
16617 Used within recursive-graph-body-print function."
16622 (setq from-position (point))
16624 (column-of-graph height (car numbers-list)))
16627 (goto-char from-position)
16628 (forward-char symbol-width)
16629 (sit-for 0) ; @r{Draw graph column by column.}
16630 (recursive-graph-body-print-internal
16631 (cdr numbers-list) height symbol-width)))
16636 After installation, this expression can be tested; here is a sample:
16639 (recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1))
16643 Here is what @code{recursive-graph-body-print} produces:
16657 Either of these two functions, @code{graph-body-print} or
16658 @code{recursive-graph-body-print}, create the body of a graph.
16661 @section Need for Printed Axes
16663 A graph needs printed axes, so you can orient yourself. For a do-once
16664 project, it may be reasonable to draw the axes by hand using Emacs's
16665 Picture mode; but a graph drawing function may be used more than once.
16667 For this reason, I have written enhancements to the basic
16668 @code{print-graph-body} function that automatically print labels for
16669 the horizontal and vertical axes. Since the label printing functions
16670 do not contain much new material, I have placed their description in
16671 an appendix. @xref{Full Graph, , A Graph with Labeled Axes}.
16673 @node Line Graph Exercise
16676 Write a line graph version of the graph printing functions.
16678 @node Emacs Initialization
16679 @chapter Your @file{.emacs} File
16680 @cindex @file{.emacs} file
16681 @cindex Customizing your @file{.emacs} file
16682 @cindex Initialization file
16684 ``You don't have to like Emacs to like it''---this seemingly
16685 paradoxical statement is the secret of GNU Emacs. The plain, out-of-the-box
16686 Emacs is a generic tool. Most people who use it customize
16687 it to suit themselves.
16689 GNU Emacs is mostly written in Emacs Lisp; this means that by writing
16690 expressions in Emacs Lisp you can change or extend Emacs.
16693 * Default Configuration::
16694 * Site-wide Init:: You can write site-wide init files.
16695 * defcustom:: Emacs will write code for you.
16696 * Beginning init File:: How to write a @file{.emacs} init file.
16697 * Text and Auto-fill:: Automatically wrap lines.
16698 * Mail Aliases:: Use abbreviations for email addresses.
16699 * Indent Tabs Mode:: Don't use tabs with @TeX{}
16700 * Keybindings:: Create some personal keybindings.
16701 * Keymaps:: More about key binding.
16702 * Loading Files:: Load (i.e., evaluate) files automatically.
16703 * Autoload:: Make functions available.
16704 * Simple Extension:: Define a function; bind it to a key.
16705 * X11 Colors:: Colors in X.
16707 * Mode Line:: How to customize your mode line.
16711 @node Default Configuration
16712 @unnumberedsec Emacs's Default Configuration
16715 There are those who appreciate Emacs's default configuration. After
16716 all, Emacs starts you in C mode when you edit a C file, starts you in
16717 Fortran mode when you edit a Fortran file, and starts you in
16718 Fundamental mode when you edit an unadorned file. This all makes
16719 sense, if you do not know who is going to use Emacs. Who knows what a
16720 person hopes to do with an unadorned file? Fundamental mode is the
16721 right default for such a file, just as C mode is the right default for
16722 editing C code. (Enough programming languages have syntaxes
16723 that enable them to share or nearly share features, so C mode is
16724 now provided by CC mode, the C Collection.)
16726 But when you do know who is going to use Emacs---you,
16727 yourself---then it makes sense to customize Emacs.
16729 For example, I seldom want Fundamental mode when I edit an
16730 otherwise undistinguished file; I want Text mode. This is why I
16731 customize Emacs: so it suits me.
16733 You can customize and extend Emacs by writing or adapting a
16734 @file{~/.emacs} file. This is your personal initialization file; its
16735 contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You
16736 may also add @file{.el} to @file{~/.emacs} and call it a
16737 @file{~/.emacs.el} file. In the past, you were forbidden to type the
16738 extra keystrokes that the name @file{~/.emacs.el} requires, but now
16739 you may. The new format is consistent with the Emacs Lisp file
16740 naming conventions; the old format saves typing.}
16742 A @file{~/.emacs} file contains Emacs Lisp code. You can write this
16743 code yourself; or you can use Emacs's @code{customize} feature to write
16744 the code for you. You can combine your own expressions and
16745 auto-written Customize expressions in your @file{.emacs} file.
16747 (I myself prefer to write my own expressions, except for those,
16748 particularly fonts, that I find easier to manipulate using the
16749 @code{customize} command. I combine the two methods.)
16751 Most of this chapter is about writing expressions yourself. It
16752 describes a simple @file{.emacs} file; for more information, see
16753 @ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and
16754 @ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference
16757 @node Site-wide Init
16758 @section Site-wide Initialization Files
16760 @cindex @file{default.el} init file
16761 @cindex @file{site-init.el} init file
16762 @cindex @file{site-load.el} init file
16763 In addition to your personal initialization file, Emacs automatically
16764 loads various site-wide initialization files, if they exist. These
16765 have the same form as your @file{.emacs} file, but are loaded by
16768 Two site-wide initialization files, @file{site-load.el} and
16769 @file{site-init.el}, are loaded into Emacs and then dumped if a
16770 dumped version of Emacs is created, as is most common. (Dumped
16771 copies of Emacs load more quickly. However, once a file is loaded and
16772 dumped, a change to it does not lead to a change in Emacs unless you
16773 load it yourself or re-dump Emacs. @xref{Building Emacs, , Building
16774 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the
16775 @file{INSTALL} file.)
16777 Three other site-wide initialization files are loaded automatically
16778 each time you start Emacs, if they exist. These are
16779 @file{site-start.el}, which is loaded @emph{before} your @file{.emacs}
16780 file, and @file{default.el}, and the terminal type file, which are both
16781 loaded @emph{after} your @file{.emacs} file.
16783 Settings and definitions in your @file{.emacs} file will overwrite
16784 conflicting settings and definitions in a @file{site-start.el} file,
16785 if it exists; but the settings and definitions in a @file{default.el}
16786 or terminal type file will overwrite those in your @file{.emacs} file.
16787 (You can prevent interference from a terminal type file by setting
16788 @code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A
16789 Simple Extension}.)
16791 @c Rewritten to avoid overfull hbox.
16792 The @file{INSTALL} file that comes in the distribution contains
16793 descriptions of the @file{site-init.el} and @file{site-load.el} files.
16795 The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files
16796 control loading. These files are in the @file{lisp} directory of the
16797 Emacs distribution and are worth perusing.
16799 The @file{loaddefs.el} file contains a good many suggestions as to
16800 what to put into your own @file{.emacs} file, or into a site-wide
16801 initialization file.
16804 @section Specifying Variables using @code{defcustom}
16807 You can specify variables using @code{defcustom} so that you and
16808 others can then use Emacs's @code{customize} feature to set their
16809 values. (You cannot use @code{customize} to write function
16810 definitions; but you can write @code{defuns} in your @file{.emacs}
16811 file. Indeed, you can write any Lisp expression in your @file{.emacs}
16814 The @code{customize} feature depends on the @code{defcustom} macro.
16815 Although you can use @code{defvar} or @code{setq} for variables that
16816 users set, the @code{defcustom} macro is designed for the job.
16818 You can use your knowledge of @code{defvar} for writing the
16819 first three arguments for @code{defcustom}. The first argument to
16820 @code{defcustom} is the name of the variable. The second argument is
16821 the variable's initial value, if any; and this value is set only if
16822 the value has not already been set. The third argument is the
16825 The fourth and subsequent arguments to @code{defcustom} specify types
16826 and options; these are not featured in @code{defvar}. (These
16827 arguments are optional.)
16829 Each of these arguments consists of a keyword followed by a value.
16830 Each keyword starts with the colon character @samp{:}.
16833 For example, the customizable user option variable
16834 @code{text-mode-hook} looks like this:
16838 (defcustom text-mode-hook nil
16839 "Normal hook run when entering Text mode and many related modes."
16841 :options '(turn-on-auto-fill flyspell-mode)
16847 The name of the variable is @code{text-mode-hook}; it has no default
16848 value; and its documentation string tells you what it does.
16850 The @code{:type} keyword tells Emacs the kind of data to which
16851 @code{text-mode-hook} should be set and how to display the value in a
16852 Customization buffer.
16854 The @code{:options} keyword specifies a suggested list of values for
16855 the variable. Usually, @code{:options} applies to a hook.
16856 The list is only a suggestion; it is not exclusive; a person who sets
16857 the variable may set it to other values; the list shown following the
16858 @code{:options} keyword is intended to offer convenient choices to a
16861 Finally, the @code{:group} keyword tells the Emacs Customization
16862 command in which group the variable is located. This tells where to
16865 The @code{defcustom} macro recognizes more than a dozen keywords.
16866 For more information, see @ref{Customization, , Writing Customization
16867 Definitions, elisp, The GNU Emacs Lisp Reference Manual}.
16869 Consider @code{text-mode-hook} as an example.
16871 There are two ways to customize this variable. You can use the
16872 customization command or write the appropriate expressions yourself.
16875 Using the customization command, you can type:
16882 and find that the group for editing files of text is called ``Text''.
16883 Enter that group. Text Mode Hook is the first member. You can click
16884 on its various options, such as @code{turn-on-auto-fill}, to set the
16885 values. After you click on the button to
16888 Save for Future Sessions
16892 Emacs will write an expression into your @file{.emacs} file.
16893 It will look like this:
16897 (custom-set-variables
16898 ;; custom-set-variables was added by Custom.
16899 ;; If you edit it by hand, you could mess it up, so be careful.
16900 ;; Your init file should contain only one such instance.
16901 ;; If there is more than one, they won't work right.
16902 '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
16907 (The @code{text-mode-hook-identify} function tells
16908 @code{toggle-text-mode-auto-fill} which buffers are in Text mode.
16909 It comes on automatically.)
16911 The @code{custom-set-variables} function works somewhat differently
16912 than a @code{setq}. While I have never learned the differences, I
16913 modify the @code{custom-set-variables} expressions in my @file{.emacs}
16914 file by hand: I make the changes in what appears to me to be a
16915 reasonable manner and have not had any problems. Others prefer to use
16916 the Customization command and let Emacs do the work for them.
16918 Another @code{custom-set-@dots{}} function is @code{custom-set-faces}.
16919 This function sets the various font faces. Over time, I have set a
16920 considerable number of faces. Some of the time, I re-set them using
16921 @code{customize}; other times, I simply edit the
16922 @code{custom-set-faces} expression in my @file{.emacs} file itself.
16924 The second way to customize your @code{text-mode-hook} is to set it
16925 yourself in your @file{.emacs} file using code that has nothing to do
16926 with the @code{custom-set-@dots{}} functions.
16929 When you do this, and later use @code{customize}, you will see a
16933 CHANGED outside Customize; operating on it here may be unreliable.
16937 This message is only a warning. If you click on the button to
16940 Save for Future Sessions
16944 Emacs will write a @code{custom-set-@dots{}} expression near the end
16945 of your @file{.emacs} file that will be evaluated after your
16946 hand-written expression. It will, therefore, overrule your
16947 hand-written expression. No harm will be done. When you do this,
16948 however, be careful to remember which expression is active; if you
16949 forget, you may confuse yourself.
16951 So long as you remember where the values are set, you will have no
16952 trouble. In any event, the values are always set in your
16953 initialization file, which is usually called @file{.emacs}.
16955 I myself use @code{customize} for hardly anything. Mostly, I write
16956 expressions myself.
16960 Incidentally, to be more complete concerning defines: @code{defsubst}
16961 defines an inline function. The syntax is just like that of
16962 @code{defun}. @code{defconst} defines a symbol as a constant. The
16963 intent is that neither programs nor users should ever change a value
16964 set by @code{defconst}. (You can change it; the value set is a
16965 variable; but please do not.)
16967 @node Beginning init File
16968 @section Beginning a @file{.emacs} File
16969 @cindex @file{.emacs} file, beginning of
16971 When you start Emacs, it loads your @file{.emacs} file unless you tell
16972 it not to by specifying @samp{-q} on the command line. (The
16973 @code{emacs -q} command gives you a plain, out-of-the-box Emacs.)
16975 A @file{.emacs} file contains Lisp expressions. Often, these are no
16976 more than expressions to set values; sometimes they are function
16979 @xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs
16980 Manual}, for a short description of initialization files.
16982 This chapter goes over some of the same ground, but is a walk among
16983 extracts from a complete, long-used @file{.emacs} file---my own.
16985 The first part of the file consists of comments: reminders to myself.
16986 By now, of course, I remember these things, but when I started, I did
16992 ;;;; Bob's .emacs file
16993 ; Robert J. Chassell
16994 ; 26 September 1985
16999 Look at that date! I started this file a long time ago. I have been
17000 adding to it ever since.
17004 ; Each section in this file is introduced by a
17005 ; line beginning with four semicolons; and each
17006 ; entry is introduced by a line beginning with
17007 ; three semicolons.
17012 This describes the usual conventions for comments in Emacs Lisp.
17013 Everything on a line that follows a semicolon is a comment. Two,
17014 three, and four semicolons are used as subsection and section markers.
17015 (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for
17016 more about comments.)
17021 ; Control-h is the help key;
17022 ; after typing control-h, type a letter to
17023 ; indicate the subject about which you want help.
17024 ; For an explanation of the help facility,
17025 ; type control-h two times in a row.
17030 Just remember: type @kbd{C-h} two times for help.
17034 ; To find out about any mode, type control-h m
17035 ; while in that mode. For example, to find out
17036 ; about mail mode, enter mail mode and then type
17042 ``Mode help'', as I call this, is very helpful. Usually, it tells you
17043 all you need to know.
17045 Of course, you don't need to include comments like these in your
17046 @file{.emacs} file. I included them in mine because I kept forgetting
17047 about Mode help or the conventions for comments---but I was able to
17048 remember to look here to remind myself.
17050 @node Text and Auto-fill
17051 @section Text and Auto Fill Mode
17053 Now we come to the part that turns on Text mode and
17058 ;;; Text mode and Auto Fill mode
17059 ;; The next two lines put Emacs into Text mode
17060 ;; and Auto Fill mode, and are for writers who
17061 ;; want to start writing prose rather than code.
17062 (setq-default major-mode 'text-mode)
17063 (add-hook 'text-mode-hook 'turn-on-auto-fill)
17067 Here is the first part of this @file{.emacs} file that does something
17068 besides remind a forgetful human!
17070 The first of the two lines in parentheses tells Emacs to turn on Text
17071 mode when you find a file, @emph{unless} that file should go into some
17072 other mode, such as C mode.
17074 @cindex Per-buffer, local variables list
17075 @cindex Local variables list, per-buffer,
17076 @cindex Automatic mode selection
17077 @cindex Mode selection, automatic
17078 When Emacs reads a file, it looks at the extension to the file name,
17079 if any. (The extension is the part that comes after a @samp{.}.) If
17080 the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns
17081 on C mode. Also, Emacs looks at first nonblank line of the file; if
17082 the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs
17083 possesses a list of extensions and specifications that it uses
17084 automatically. In addition, Emacs looks near the last page for a
17085 per-buffer, local variables list, if any.
17088 @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU
17091 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
17095 See sections ``How Major Modes are Chosen'' and ``Local Variables in
17096 Files'' in @cite{The GNU Emacs Manual}.
17099 Now, back to the @file{.emacs} file.
17102 Here is the line again; how does it work?
17104 @cindex Text Mode turned on
17106 (setq major-mode 'text-mode)
17110 This line is a short, but complete Emacs Lisp expression.
17112 We are already familiar with @code{setq}. It sets the following variable,
17113 @code{major-mode}, to the subsequent value, which is @code{text-mode}.
17114 The single-quote before @code{text-mode} tells Emacs to deal directly
17115 with the @code{text-mode} symbol, not with whatever it might stand for.
17116 @xref{set & setq, , Setting the Value of a Variable},
17117 for a reminder of how @code{setq} works.
17118 The main point is that there is no difference between the procedure you
17119 use to set a value in your @file{.emacs} file and the procedure you use
17120 anywhere else in Emacs.
17123 Here is the next line:
17125 @cindex Auto Fill mode turned on
17128 (add-hook 'text-mode-hook 'turn-on-auto-fill)
17132 In this line, the @code{add-hook} command adds
17133 @code{turn-on-auto-fill} to the variable.
17135 @code{turn-on-auto-fill} is the name of a program, that, you guessed
17136 it!, turns on Auto Fill mode.
17138 Every time Emacs turns on Text mode, Emacs runs the commands hooked
17139 onto Text mode. So every time Emacs turns on Text mode, Emacs also
17140 turns on Auto Fill mode.
17142 In brief, the first line causes Emacs to enter Text mode when you edit a
17143 file, unless the file name extension, a first non-blank line, or local
17144 variables to tell Emacs otherwise.
17146 Text mode among other actions, sets the syntax table to work
17147 conveniently for writers. In Text mode, Emacs considers an apostrophe
17148 as part of a word like a letter; but Emacs does not consider a period
17149 or a space as part of a word. Thus, @kbd{M-f} moves you over
17150 @samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after
17151 the @samp{t} of @samp{it's}.
17153 The second line causes Emacs to turn on Auto Fill mode when it turns
17154 on Text mode. In Auto Fill mode, Emacs automatically breaks a line
17155 that is too wide and brings the excessively wide part of the line down
17156 to the next line. Emacs breaks lines between words, not within them.
17158 When Auto Fill mode is turned off, lines continue to the right as you
17159 type them. Depending on how you set the value of
17160 @code{truncate-lines}, the words you type either disappear off the
17161 right side of the screen, or else are shown, in a rather ugly and
17162 unreadable manner, as a continuation line on the screen.
17165 In addition, in this part of my @file{.emacs} file, I tell the Emacs
17166 fill commands to insert two spaces after a colon:
17169 (setq colon-double-space t)
17173 @section Mail Aliases
17175 Here is a @code{setq} that turns on mail aliases, along with more
17181 ; To enter mail mode, type 'C-x m'
17182 ; To enter RMAIL (for reading mail),
17184 (setq mail-aliases t)
17188 @cindex Mail aliases
17190 This @code{setq} command sets the value of the variable
17191 @code{mail-aliases} to @code{t}. Since @code{t} means true, the line
17192 says, in effect, ``Yes, use mail aliases.''
17194 Mail aliases are convenient short names for long email addresses or
17195 for lists of email addresses. The file where you keep your aliases
17196 is @file{~/.mailrc}. You write an alias like this:
17199 alias geo george@@foobar.wiz.edu
17203 When you write a message to George, address it to @samp{geo}; the
17204 mailer will automatically expand @samp{geo} to the full address.
17206 @node Indent Tabs Mode
17207 @section Indent Tabs Mode
17208 @cindex Tabs, preventing
17209 @findex indent-tabs-mode
17211 By default, Emacs inserts tabs in place of multiple spaces when it
17212 formats a region. (For example, you might indent many lines of text
17213 all at once with the @code{indent-region} command.) Tabs look fine on
17214 a terminal or with ordinary printing, but they produce badly indented
17215 output when you use @TeX{} or Texinfo since @TeX{} ignores tabs.
17218 The following turns off Indent Tabs mode:
17222 ;;; Prevent Extraneous Tabs
17223 (setq-default indent-tabs-mode nil)
17227 Note that this line uses @code{setq-default} rather than the
17228 @code{setq} command that we have seen before. The @code{setq-default}
17229 command sets values only in buffers that do not have their own local
17230 values for the variable.
17233 @xref{Just Spaces, , Tabs vs.@: Spaces, emacs, The GNU Emacs Manual}.
17235 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
17239 See sections ``Tabs vs.@: Spaces'' and ``Local Variables in
17240 Files'' in @cite{The GNU Emacs Manual}.
17245 @section Some Keybindings
17247 Now for some personal keybindings:
17251 ;;; Compare windows
17252 (global-set-key "\C-cw" 'compare-windows)
17256 @findex compare-windows
17257 @code{compare-windows} is a nifty command that compares the text in
17258 your current window with text in the next window. It makes the
17259 comparison by starting at point in each window, moving over text in
17260 each window as far as they match. I use this command all the time.
17262 This also shows how to set a key globally, for all modes.
17264 @cindex Setting a key globally
17265 @cindex Global set key
17266 @cindex Key setting globally
17267 @findex global-set-key
17268 The command is @code{global-set-key}. It is followed by the
17269 keybinding. In a @file{.emacs} file, the keybinding is written as
17270 shown: @code{\C-c} stands for Control-C, which means to press the
17271 control key and the @key{c} key at the same time. The @code{w} means
17272 to press the @key{w} key. The keybinding is surrounded by double
17273 quotation marks. In documentation, you would write this as
17274 @w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as
17275 @kbd{M-c}, rather than a @key{CTRL} key, you would write
17276 @w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, ,
17277 Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for
17280 The command invoked by the keys is @code{compare-windows}. Note that
17281 @code{compare-windows} is preceded by a single-quote; otherwise, Emacs
17282 would first try to evaluate the symbol to determine its value.
17284 These three things, the double quotation marks, the backslash before
17285 the @samp{C}, and the single-quote are necessary parts of
17286 keybinding that I tend to forget. Fortunately, I have come to
17287 remember that I should look at my existing @file{.emacs} file, and
17288 adapt what is there.
17290 As for the keybinding itself: @kbd{C-c w}. This combines the prefix
17291 key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This
17292 set of keys, @kbd{C-c} followed by a single character, is strictly
17293 reserved for individuals' own use. (I call these @dfn{own} keys, since
17294 these are for my own use.) You should always be able to create such a
17295 keybinding for your own use without stomping on someone else's
17296 keybinding. If you ever write an extension to Emacs, please avoid
17297 taking any of these keys for public use. Create a key like @kbd{C-c
17298 C-w} instead. Otherwise, we will run out of own keys.
17301 Here is another keybinding, with a comment:
17305 ;;; Keybinding for 'occur'
17306 ; I use occur a lot, so let's bind it to a key:
17307 (global-set-key "\C-co" 'occur)
17312 The @code{occur} command shows all the lines in the current buffer
17313 that contain a match for a regular expression. Matching lines are
17314 shown in a buffer called @file{*Occur*}. That buffer serves as a menu
17315 to jump to occurrences.
17317 @findex global-unset-key
17318 @cindex Unbinding key
17319 @cindex Key unbinding
17321 Here is how to unbind a key, so it does not
17327 (global-unset-key "\C-xf")
17331 There is a reason for this unbinding: I found I inadvertently typed
17332 @w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a
17333 file, as I intended, I accidentally set the width for filled text,
17334 almost always to a width I did not want. Since I hardly ever reset my
17335 default width, I simply unbound the key.
17337 @findex list-buffers, @r{rebound}
17338 @findex buffer-menu, @r{bound to key}
17340 The following rebinds an existing key:
17344 ;;; Rebind 'C-x C-b' for 'buffer-menu'
17345 (global-set-key "\C-x\C-b" 'buffer-menu)
17349 By default, @kbd{C-x C-b} runs the
17350 @code{list-buffers} command. This command lists
17351 your buffers in @emph{another} window. Since I
17352 almost always want to do something in that
17353 window, I prefer the @code{buffer-menu}
17354 command, which not only lists the buffers,
17355 but moves point into that window.
17360 @cindex Rebinding keys
17362 Emacs uses @dfn{keymaps} to record which keys call which commands.
17363 When you use @code{global-set-key} to set the keybinding for a single
17364 command in all parts of Emacs, you are specifying the keybinding in
17365 @code{current-global-map}.
17367 Specific modes, such as C mode or Text mode, have their own keymaps;
17368 the mode-specific keymaps override the global map that is shared by
17371 The @code{global-set-key} function binds, or rebinds, the global
17372 keymap. For example, the following binds the key @kbd{C-x C-b} to the
17373 function @code{buffer-menu}:
17376 (global-set-key "\C-x\C-b" 'buffer-menu)
17379 Mode-specific keymaps are bound using the @code{define-key} function,
17380 which takes a specific keymap as an argument, as well as the key and
17381 the command. For example, my @file{.emacs} file contains the
17382 following expression to bind the @code{texinfo-insert-@@group} command
17383 to @kbd{C-c C-c g}:
17387 (define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group)
17392 The @code{texinfo-insert-@@group} function itself is a little extension
17393 to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I
17394 use this command all the time and prefer to type the three strokes
17395 @kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}.
17396 (@samp{@@group} and its matching @samp{@@end group} are commands that
17397 keep all enclosed text together on one page; many multi-line examples
17398 in this book are surrounded by @samp{@@group @dots{} @@end group}.)
17401 Here is the @code{texinfo-insert-@@group} function definition:
17405 (defun texinfo-insert-@@group ()
17406 "Insert the string @@group in a Texinfo buffer."
17408 (beginning-of-line)
17409 (insert "@@group\n"))
17413 (Of course, I could have used Abbrev mode to save typing, rather than
17414 write a function to insert a word; but I prefer key strokes consistent
17415 with other Texinfo mode key bindings.)
17417 You will see numerous @code{define-key} expressions in
17418 @file{loaddefs.el} as well as in the various mode libraries, such as
17419 @file{cc-mode.el} and @file{lisp-mode.el}.
17421 @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs
17422 Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp
17423 Reference Manual}, for more information about keymaps.
17425 @node Loading Files
17426 @section Loading Files
17427 @cindex Loading files
17430 Many people in the GNU Emacs community have written extensions to
17431 Emacs. As time goes by, these extensions are often included in new
17432 releases. For example, the Calendar and Diary packages are now part
17433 of the standard GNU Emacs, as is Calc.
17435 You can use a @code{load} command to evaluate a complete file and
17436 thereby install all the functions and variables in the file into Emacs.
17439 @c (auto-compression-mode t)
17442 (load "~/emacs/slowsplit")
17445 This evaluates, i.e., loads, the @file{slowsplit.el} file or if it
17446 exists, the faster, byte compiled @file{slowsplit.elc} file from the
17447 @file{emacs} sub-directory of your home directory. The file contains
17448 the function @code{split-window-quietly}, which John Robinson wrote in
17451 The @code{split-window-quietly} function splits a window with the
17452 minimum of redisplay. I installed it in 1989 because it worked well
17453 with the slow 1200 baud terminals I was then using. Nowadays, I only
17454 occasionally come across such a slow connection, but I continue to use
17455 the function because I like the way it leaves the bottom half of a
17456 buffer in the lower of the new windows and the top half in the upper
17460 To replace the key binding for the default
17461 @code{split-window-vertically}, you must also unset that key and bind
17462 the keys to @code{split-window-quietly}, like this:
17466 (global-unset-key "\C-x2")
17467 (global-set-key "\C-x2" 'split-window-quietly)
17472 If you load many extensions, as I do, then instead of specifying the
17473 exact location of the extension file, as shown above, you can specify
17474 that directory as part of Emacs's @code{load-path}. Then, when Emacs
17475 loads a file, it will search that directory as well as its default
17476 list of directories. (The default list is specified in @file{paths.h}
17477 when Emacs is built.)
17480 The following command adds your @file{~/emacs} directory to the
17481 existing load path:
17485 ;;; Emacs Load Path
17486 (setq load-path (cons "~/emacs" load-path))
17490 Incidentally, @code{load-library} is an interactive interface to the
17491 @code{load} function. The complete function looks like this:
17493 @findex load-library
17496 (defun load-library (library)
17497 "Load the Emacs Lisp library named LIBRARY.
17498 This is an interface to the function `load'. LIBRARY is searched
17499 for in `load-path', both with and without `load-suffixes' (as
17500 well as `load-file-rep-suffixes').
17502 See Info node `(emacs)Lisp Libraries' for more details.
17503 See `load-file' for a different interface to `load'."
17505 (list (completing-read "Load library: "
17506 (apply-partially 'locate-file-completion-table
17508 (get-load-suffixes)))))
17513 The name of the function, @code{load-library}, comes from the use of
17514 ``library'' as a conventional synonym for ``file''. The source for the
17515 @code{load-library} command is in the @file{files.el} library.
17517 Another interactive command that does a slightly different job is
17518 @code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for
17519 Emacs, emacs, The GNU Emacs Manual}, for information on the
17520 distinction between @code{load-library} and this command.
17523 @section Autoloading
17526 Instead of installing a function by loading the file that contains it,
17527 or by evaluating the function definition, you can make the function
17528 available but not actually install it until it is first called. This
17529 is called @dfn{autoloading}.
17531 When you execute an autoloaded function, Emacs automatically evaluates
17532 the file that contains the definition, and then calls the function.
17534 Emacs starts quicker with autoloaded functions, since their libraries
17535 are not loaded right away; but you need to wait a moment when you
17536 first use such a function, while its containing file is evaluated.
17538 Rarely used functions are frequently autoloaded. The
17539 @file{loaddefs.el} library contains thousands of autoloaded functions,
17540 from @code{5x5} to @code{zone}. Of course, you may
17541 come to use a rare function frequently. When you do, you should
17542 load that function's file with a @code{load} expression in your
17543 @file{.emacs} file.
17545 In my @file{.emacs} file, I load 14 libraries that contain functions
17546 that would otherwise be autoloaded. (Actually, it would have been
17547 better to include these files in my dumped Emacs, but I forgot.
17548 @xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
17549 Reference Manual}, and the @file{INSTALL} file for more about
17552 You may also want to include autoloaded expressions in your @file{.emacs}
17553 file. @code{autoload} is a built-in function that takes up to five
17554 arguments, the final three of which are optional. The first argument
17555 is the name of the function to be autoloaded; the second is the name
17556 of the file to be loaded. The third argument is documentation for the
17557 function, and the fourth tells whether the function can be called
17558 interactively. The fifth argument tells what type of
17559 object---@code{autoload} can handle a keymap or macro as well as a
17560 function (the default is a function).
17563 Here is a typical example:
17567 (autoload 'html-helper-mode
17568 "html-helper-mode" "Edit HTML documents" t)
17573 (@code{html-helper-mode} is an older alternative to @code{html-mode},
17574 which is a standard part of the distribution.)
17577 This expression autoloads the @code{html-helper-mode} function. It
17578 takes it from the @file{html-helper-mode.el} file (or from the byte
17579 compiled version @file{html-helper-mode.elc}, if that exists.) The
17580 file must be located in a directory specified by @code{load-path}.
17581 The documentation says that this is a mode to help you edit documents
17582 written in the HyperText Markup Language. You can call this mode
17583 interactively by typing @kbd{M-x html-helper-mode}. (You need to
17584 duplicate the function's regular documentation in the autoload
17585 expression because the regular function is not yet loaded, so its
17586 documentation is not available.)
17588 @xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference
17589 Manual}, for more information.
17591 @node Simple Extension
17592 @section A Simple Extension: @code{line-to-top-of-window}
17593 @findex line-to-top-of-window
17594 @cindex Simple extension in @file{.emacs} file
17596 Here is a simple extension to Emacs that moves the line point is on to
17597 the top of the window. I use this all the time, to make text easier
17600 You can put the following code into a separate file and then load it
17601 from your @file{.emacs} file, or you can include it within your
17602 @file{.emacs} file.
17605 Here is the definition:
17609 ;;; Line to top of window;
17610 ;;; replace three keystroke sequence C-u 0 C-l
17611 (defun line-to-top-of-window ()
17612 "Move the line point is on to top of window."
17619 Now for the keybinding.
17621 Nowadays, function keys as well as mouse button events and
17622 non-@sc{ascii} characters are written within square brackets, without
17623 quotation marks. (In Emacs version 18 and before, you had to write
17624 different function key bindings for each different make of terminal.)
17626 I bind @code{line-to-top-of-window} to my @key{F6} function key like
17630 (global-set-key [f6] 'line-to-top-of-window)
17633 For more information, see @ref{Init Rebinding, , Rebinding Keys in
17634 Your Init File, emacs, The GNU Emacs Manual}.
17636 @cindex Conditional 'twixt two versions of Emacs
17637 @cindex Version of Emacs, choosing
17638 @cindex Emacs version, choosing
17639 If you run two versions of GNU Emacs, such as versions 22 and 23, and
17640 use one @file{.emacs} file, you can select which code to evaluate with
17641 the following conditional:
17646 ((= 22 emacs-major-version)
17647 ;; evaluate version 22 code
17649 ((= 23 emacs-major-version)
17650 ;; evaluate version 23 code
17655 For example, recent versions blink
17656 their cursors by default. I hate such blinking, as well as other
17657 features, so I placed the following in my @file{.emacs}
17658 file@footnote{When I start instances of Emacs that do not load my
17659 @file{.emacs} file or any site file, I also turn off blinking:
17662 emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
17664 @exdent Or nowadays, using an even more sophisticated set of options,
17672 (when (>= emacs-major-version 21)
17673 (blink-cursor-mode 0)
17674 ;; Insert newline when you press 'C-n' (next-line)
17675 ;; at the end of the buffer
17676 (setq next-line-add-newlines t)
17679 ;; Turn on image viewing
17680 (auto-image-file-mode t)
17683 ;; Turn on menu bar (this bar has text)
17684 ;; (Use numeric argument to turn on)
17688 ;; Turn off tool bar (this bar has icons)
17689 ;; (Use numeric argument to turn on)
17690 (tool-bar-mode nil)
17693 ;; Turn off tooltip mode for tool bar
17694 ;; (This mode causes icon explanations to pop up)
17695 ;; (Use numeric argument to turn on)
17697 ;; If tooltips turned on, make tips appear promptly
17698 (setq tooltip-delay 0.1) ; default is 0.7 second
17704 @section X11 Colors
17706 You can specify colors when you use Emacs with the MIT X Windowing
17709 I dislike the default colors and specify my own.
17712 Here are the expressions in my @file{.emacs}
17713 file that set values:
17717 ;; Set cursor color
17718 (set-cursor-color "white")
17721 (set-mouse-color "white")
17723 ;; Set foreground and background
17724 (set-foreground-color "white")
17725 (set-background-color "darkblue")
17729 ;;; Set highlighting colors for isearch and drag
17730 (set-face-foreground 'highlight "white")
17731 (set-face-background 'highlight "blue")
17735 (set-face-foreground 'region "cyan")
17736 (set-face-background 'region "blue")
17740 (set-face-foreground 'secondary-selection "skyblue")
17741 (set-face-background 'secondary-selection "darkblue")
17745 ;; Set calendar highlighting colors
17746 (add-hook 'calendar-load-hook
17748 (set-face-foreground 'diary-face "skyblue")
17749 (set-face-background 'holiday-face "slate blue")
17750 (set-face-foreground 'holiday-face "white")))
17754 The various shades of blue soothe my eye and prevent me from seeing
17755 the screen flicker.
17757 Alternatively, I could have set my specifications in various X
17758 initialization files. For example, I could set the foreground,
17759 background, cursor, and pointer (i.e., mouse) colors in my
17760 @file{~/.Xresources} file like this:
17764 Emacs*foreground: white
17765 Emacs*background: darkblue
17766 Emacs*cursorColor: white
17767 Emacs*pointerColor: white
17771 In any event, since it is not part of Emacs, I set the root color of
17772 my X window in my @file{~/.xinitrc} file, like this@footnote{I also
17773 run more modern window managers, such as Enlightenment, Gnome, or KDE;
17774 in those cases, I often specify an image rather than a plain color.}:
17777 xsetroot -solid Navy -fg white &
17781 @node Miscellaneous
17782 @section Miscellaneous Settings for a @file{.emacs} File
17785 Here are a few miscellaneous settings:
17790 Set the shape and color of the mouse cursor:
17794 ; Cursor shapes are defined in
17795 ; '/usr/include/X11/cursorfont.h';
17796 ; for example, the 'target' cursor is number 128;
17797 ; the 'top_left_arrow' cursor is number 132.
17801 (let ((mpointer (x-get-resource "*mpointer"
17802 "*emacs*mpointer")))
17803 ;; If you have not set your mouse pointer
17804 ;; then set it, otherwise leave as is:
17805 (if (eq mpointer nil)
17806 (setq mpointer "132")) ; top_left_arrow
17809 (setq x-pointer-shape (string-to-int mpointer))
17810 (set-mouse-color "white"))
17815 Or you can set the values of a variety of features in an alist, like
17821 default-frame-alist
17822 '((cursor-color . "white")
17823 (mouse-color . "white")
17824 (foreground-color . "white")
17825 (background-color . "DodgerBlue4")
17826 ;; (cursor-type . bar)
17827 (cursor-type . box)
17830 (tool-bar-lines . 0)
17831 (menu-bar-lines . 1)
17835 "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1")
17841 Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL}
17842 into @kbd{@key{CTRL}-h}.@*
17843 (Some older keyboards needed this, although I have not seen the
17848 ;; Translate 'C-h' to <DEL>.
17849 ; (keyboard-translate ?\C-h ?\C-?)
17851 ;; Translate <DEL> to 'C-h'.
17852 (keyboard-translate ?\C-? ?\C-h)
17856 @item Turn off a blinking cursor!
17860 (if (fboundp 'blink-cursor-mode)
17861 (blink-cursor-mode -1))
17866 or start GNU Emacs with the command @code{emacs -nbc}.
17869 @item When using @command{grep}@*
17870 @samp{-i}@w{ } Ignore case distinctions@*
17871 @samp{-n}@w{ } Prefix each line of output with line number@*
17872 @samp{-H}@w{ } Print the filename for each match.@*
17873 @samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-}
17876 (setq grep-command "grep -i -nH -e ")
17880 @c Evidently, no longer needed in GNU Emacs 22
17882 item Automatically uncompress compressed files when visiting them
17885 (load "uncompress")
17890 @item Find an existing buffer, even if it has a different name@*
17891 This avoids problems with symbolic links.
17894 (setq find-file-existing-other-name t)
17897 @item Set your language environment and default input method
17901 (set-language-environment "latin-1")
17902 ;; Remember you can enable or disable multilingual text input
17903 ;; with the @code{toggle-input-method'} (@kbd{C-\}) command
17904 (setq default-input-method "latin-1-prefix")
17908 If you want to write with Chinese GB characters, set this instead:
17912 (set-language-environment "Chinese-GB")
17913 (setq default-input-method "chinese-tonepy")
17918 @subsubheading Fixing Unpleasant Key Bindings
17919 @cindex Key bindings, fixing
17920 @cindex Bindings, key, fixing unpleasant
17922 Some systems bind keys unpleasantly. Sometimes, for example, the
17923 @key{CTRL} key appears in an awkward spot rather than at the far left
17926 Usually, when people fix these sorts of keybindings, they do not
17927 change their @file{~/.emacs} file. Instead, they bind the proper keys
17928 on their consoles with the @code{loadkeys} or @code{install-keymap}
17929 commands in their boot script and then include @code{xmodmap} commands
17930 in their @file{.xinitrc} or @file{.Xsession} file for X Windows.
17938 loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz
17940 install-keymap emacs2
17946 For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps
17947 Lock} key is at the far left of the home row:
17951 # Bind the key labeled 'Caps Lock' to 'Control'
17952 # (Such a broken user interface suggests that keyboard manufacturers
17953 # think that computers are typewriters from 1885.)
17955 xmodmap -e "clear Lock"
17956 xmodmap -e "add Control = Caps_Lock"
17962 In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT}
17963 key to a @key{META} key:
17967 # Some ill designed keyboards have a key labeled ALT and no Meta
17968 xmodmap -e "keysym Alt_L = Meta_L Alt_L"
17974 @section A Modified Mode Line
17975 @vindex mode-line-format
17976 @cindex Mode line format
17978 Finally, a feature I really like: a modified mode line.
17980 When I work over a network, I forget which machine I am using. Also,
17981 I tend to I lose track of where I am, and which line point is on.
17983 So I reset my mode line to look like this:
17986 -:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top
17989 I am visiting a file called @file{foo.texi}, on my machine
17990 @file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in
17991 Texinfo mode, and am at the top of the buffer.
17994 My @file{.emacs} file has a section that looks like this:
17998 ;; Set a Mode Line that tells me which machine, which directory,
17999 ;; and which line I am on, plus the other customary information.
18000 (setq-default mode-line-format
18004 "mouse-1: select window, mouse-2: delete others ..."))
18005 mode-line-mule-info
18007 mode-line-frame-identification
18011 mode-line-buffer-identification
18014 (system-name) 0 (string-match "\\..+" (system-name))))
18019 "mouse-1: select window, mouse-2: delete others ..."))
18020 (line-number-mode " Line %l ")
18026 "mouse-1: select window, mouse-2: delete others ..."))
18027 (:eval (mode-line-mode-name))
18030 #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
18039 Here, I redefine the default mode line. Most of the parts are from
18040 the original; but I make a few changes. I set the @emph{default} mode
18041 line format so as to permit various modes, such as Info, to override
18044 Many elements in the list are self-explanatory:
18045 @code{mode-line-modified} is a variable that tells whether the buffer
18046 has been modified, @code{mode-name} tells the name of the mode, and so
18047 on. However, the format looks complicated because of two features we
18048 have not discussed.
18050 @cindex Properties, in mode line example
18051 The first string in the mode line is a dash or hyphen, @samp{-}. In
18052 the old days, it would have been specified simply as @code{"-"}. But
18053 nowadays, Emacs can add properties to a string, such as highlighting
18054 or, as in this case, a help feature. If you place your mouse cursor
18055 over the hyphen, some help information appears (By default, you must
18056 wait seven-tenths of a second before the information appears. You can
18057 change that timing by changing the value of @code{tooltip-delay}.)
18060 The new string format has a special syntax:
18063 #("-" 0 1 (help-echo "mouse-1: select window, ..."))
18067 The @code{#(} begins a list. The first element of the list is the
18068 string itself, just one @samp{-}. The second and third
18069 elements specify the range over which the fourth element applies. A
18070 range starts @emph{after} a character, so a zero means the range
18071 starts just before the first character; a 1 means that the range ends
18072 just after the first character. The third element is the property for
18073 the range. It consists of a property list, a
18074 property name, in this case, @samp{help-echo}, followed by a value, in this
18075 case, a string. The second, third, and fourth elements of this new
18076 string format can be repeated.
18078 @xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp
18079 Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format,
18080 elisp, The GNU Emacs Lisp Reference Manual}, for more information.
18082 @code{mode-line-buffer-identification}
18083 displays the current buffer name. It is a list
18084 beginning @code{(#("%12b" 0 4 @dots{}}.
18085 The @code{#(} begins the list.
18087 The @samp{"%12b"} displays the current buffer name, using the
18088 @code{buffer-name} function with which we are familiar; the @samp{12}
18089 specifies the maximum number of characters that will be displayed.
18090 When a name has fewer characters, whitespace is added to fill out to
18091 this number. (Buffer names can and often should be longer than 12
18092 characters; this length works well in a typical 80 column wide
18095 @code{:eval} says to evaluate the following form and use the result as
18096 a string to display. In this case, the expression displays the first
18097 component of the full system name. The end of the first component is
18098 a @samp{.} (period), so I use the @code{string-match} function to
18099 tell me the length of the first component. The substring from the
18100 zeroth character to that length is the name of the machine.
18103 This is the expression:
18108 (system-name) 0 (string-match "\\..+" (system-name))))
18112 @samp{%[} and @samp{%]} cause a pair of square brackets
18113 to appear for each recursive editing level. @samp{%n} says ``Narrow''
18114 when narrowing is in effect. @samp{%P} tells you the percentage of
18115 the buffer that is above the bottom of the window, or ``Top'', ``Bottom'',
18116 or ``All''. (A lower case @samp{p} tell you the percentage above the
18117 @emph{top} of the window.) @samp{%-} inserts enough dashes to fill
18120 Remember, you don't have to like Emacs to like it---your own
18121 Emacs can have different colors, different commands, and different
18122 keys than a default Emacs.
18124 On the other hand, if you want to bring up a plain out-of-the-box
18125 Emacs, with no customization, type:
18132 This will start an Emacs that does @emph{not} load your
18133 @file{~/.emacs} initialization file. A plain, default Emacs. Nothing
18140 GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The
18141 first is built into the internals of Emacs and is always with you;
18142 the second requires that you instrument a function before you can use it.
18144 Both debuggers are described extensively in @ref{Debugging, ,
18145 Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}.
18146 In this chapter, I will walk through a short example of each.
18149 * debug:: How to use the built-in debugger.
18150 * debug-on-entry:: Start debugging when you call a function.
18151 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
18152 * edebug:: How to use Edebug, a source level debugger.
18153 * Debugging Exercises::
18157 @section @code{debug}
18160 Suppose you have written a function definition that is intended to
18161 return the sum of the numbers 1 through a given number. (This is the
18162 @code{triangle} function discussed earlier. @xref{Decrementing
18163 Example, , Example with Decrementing Counter}, for a discussion.)
18164 @c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.)
18166 However, your function definition has a bug. You have mistyped
18167 @samp{1=} for @samp{1-}. Here is the broken definition:
18169 @findex triangle-bugged
18172 (defun triangle-bugged (number)
18173 "Return sum of numbers 1 through NUMBER inclusive."
18175 (while (> number 0)
18176 (setq total (+ total number))
18177 (setq number (1= number))) ; @r{Error here.}
18182 If you are reading this in Info, you can evaluate this definition in
18183 the normal fashion. You will see @code{triangle-bugged} appear in the
18187 Now evaluate the @code{triangle-bugged} function with an
18191 (triangle-bugged 4)
18195 In a recent GNU Emacs, you will create and enter a @file{*Backtrace*}
18201 ---------- Buffer: *Backtrace* ----------
18202 Debugger entered--Lisp error: (void-function 1=)
18204 (setq number (1= number))
18205 (while (> number 0) (setq total (+ total number))
18206 (setq number (1= number)))
18207 (let ((total 0)) (while (> number 0) (setq total ...)
18208 (setq number ...)) total)
18212 eval((triangle-bugged 4))
18213 eval-last-sexp-1(nil)
18214 eval-last-sexp(nil)
18215 call-interactively(eval-last-sexp)
18216 ---------- Buffer: *Backtrace* ----------
18221 (I have reformatted this example slightly; the debugger does not fold
18222 long lines. As usual, you can quit the debugger by typing @kbd{q} in
18223 the @file{*Backtrace*} buffer.)
18225 In practice, for a bug as simple as this, the Lisp error line will
18226 tell you what you need to know to correct the definition. The
18227 function @code{1=} is void.
18231 In GNU Emacs 20 and before, you will see:
18234 Symbol's function definition is void:@: 1=
18238 which has the same meaning as the @file{*Backtrace*} buffer line in
18242 However, suppose you are not quite certain what is going on?
18243 You can read the complete backtrace.
18245 In this case, you need to run a recent GNU Emacs, which automatically
18246 starts the debugger that puts you in the @file{*Backtrace*} buffer; or
18247 else, you need to start the debugger manually as described below.
18249 Read the @file{*Backtrace*} buffer from the bottom up; it tells you
18250 what Emacs did that led to the error. Emacs made an interactive call
18251 to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation
18252 of the @code{triangle-bugged} expression. Each line above tells you
18253 what the Lisp interpreter evaluated next.
18256 The third line from the top of the buffer is
18259 (setq number (1= number))
18263 Emacs tried to evaluate this expression; in order to do so, it tried
18264 to evaluate the inner expression shown on the second line from the
18273 This is where the error occurred; as the top line says:
18276 Debugger entered--Lisp error: (void-function 1=)
18280 You can correct the mistake, re-evaluate the function definition, and
18281 then run your test again.
18283 @node debug-on-entry
18284 @section @code{debug-on-entry}
18285 @findex debug-on-entry
18287 A recent GNU Emacs starts the debugger automatically when your
18288 function has an error.
18291 GNU Emacs version 20 and before did not; it simply
18292 presented you with an error message. You had to start the debugger
18296 Incidentally, you can start the debugger manually for all versions of
18297 Emacs; the advantage is that the debugger runs even if you do not have
18298 a bug in your code. Sometimes your code will be free of bugs!
18300 You can enter the debugger when you call the function by calling
18301 @code{debug-on-entry}.
18308 M-x debug-on-entry RET triangle-bugged RET
18313 Now, evaluate the following:
18316 (triangle-bugged 5)
18320 All versions of Emacs will create a @file{*Backtrace*} buffer and tell
18321 you that it is beginning to evaluate the @code{triangle-bugged}
18326 ---------- Buffer: *Backtrace* ----------
18327 Debugger entered--entering a function:
18328 * triangle-bugged(5)
18329 eval((triangle-bugged 5))
18332 eval-last-sexp-1(nil)
18333 eval-last-sexp(nil)
18334 call-interactively(eval-last-sexp)
18335 ---------- Buffer: *Backtrace* ----------
18339 In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate
18340 the first expression in @code{triangle-bugged}; the buffer will look
18345 ---------- Buffer: *Backtrace* ----------
18346 Debugger entered--beginning evaluation of function call form:
18347 * (let ((total 0)) (while (> number 0) (setq total ...)
18348 (setq number ...)) total)
18349 * triangle-bugged(5)
18350 eval((triangle-bugged 5))
18353 eval-last-sexp-1(nil)
18354 eval-last-sexp(nil)
18355 call-interactively(eval-last-sexp)
18356 ---------- Buffer: *Backtrace* ----------
18361 Now, type @kbd{d} again, eight times, slowly. Each time you type
18362 @kbd{d}, Emacs will evaluate another expression in the function
18366 Eventually, the buffer will look like this:
18370 ---------- Buffer: *Backtrace* ----------
18371 Debugger entered--beginning evaluation of function call form:
18372 * (setq number (1= number))
18373 * (while (> number 0) (setq total (+ total number))
18374 (setq number (1= number)))
18377 * (let ((total 0)) (while (> number 0) (setq total ...)
18378 (setq number ...)) total)
18379 * triangle-bugged(5)
18380 eval((triangle-bugged 5))
18383 eval-last-sexp-1(nil)
18384 eval-last-sexp(nil)
18385 call-interactively(eval-last-sexp)
18386 ---------- Buffer: *Backtrace* ----------
18392 Finally, after you type @kbd{d} two more times, Emacs will reach the
18393 error, and the top two lines of the @file{*Backtrace*} buffer will look
18398 ---------- Buffer: *Backtrace* ----------
18399 Debugger entered--Lisp error: (void-function 1=)
18402 ---------- Buffer: *Backtrace* ----------
18406 By typing @kbd{d}, you were able to step through the function.
18408 You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this
18409 quits the trace, but does not cancel @code{debug-on-entry}.
18411 @findex cancel-debug-on-entry
18412 To cancel the effect of @code{debug-on-entry}, call
18413 @code{cancel-debug-on-entry} and the name of the function, like this:
18416 M-x cancel-debug-on-entry RET triangle-bugged RET
18420 (If you are reading this in Info, cancel @code{debug-on-entry} now.)
18422 @node debug-on-quit
18423 @section @code{debug-on-quit} and @code{(debug)}
18425 In addition to setting @code{debug-on-error} or calling @code{debug-on-entry},
18426 there are two other ways to start @code{debug}.
18428 @findex debug-on-quit
18429 You can start @code{debug} whenever you type @kbd{C-g}
18430 (@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to
18431 @code{t}. This is useful for debugging infinite loops.
18434 @cindex @code{(debug)} in code
18435 Or, you can insert a line that says @code{(debug)} into your code
18436 where you want the debugger to start, like this:
18440 (defun triangle-bugged (number)
18441 "Return sum of numbers 1 through NUMBER inclusive."
18443 (while (> number 0)
18444 (setq total (+ total number))
18445 (debug) ; @r{Start debugger.}
18446 (setq number (1= number))) ; @r{Error here.}
18451 The @code{debug} function is described in detail in @ref{Debugger, ,
18452 The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}.
18455 @section The @code{edebug} Source Level Debugger
18456 @cindex Source level debugger
18459 Edebug is a source level debugger. Edebug normally displays the
18460 source of the code you are debugging, with an arrow at the left that
18461 shows which line you are currently executing.
18463 You can walk through the execution of a function, line by line, or run
18464 quickly until reaching a @dfn{breakpoint} where execution stops.
18466 Edebug is described in @ref{Edebug, , , elisp, The GNU Emacs
18467 Lisp Reference Manual}.
18470 Here is a bugged function definition for @code{triangle-recursively}.
18471 @xref{Recursive triangle function, , Recursion in place of a counter},
18472 for a review of it.
18476 (defun triangle-recursively-bugged (number)
18477 "Return sum of numbers 1 through NUMBER inclusive.
18482 (triangle-recursively-bugged
18483 (1= number))))) ; @r{Error here.}
18488 Normally, you would install this definition by positioning your cursor
18489 after the function's closing parenthesis and typing @kbd{C-x C-e}
18490 (@code{eval-last-sexp}) or else by positioning your cursor within the
18491 definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default,
18492 the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp
18496 However, to prepare this function definition for Edebug, you must
18497 first @dfn{instrument} the code using a different command. You can do
18498 this by positioning your cursor within or just after the definition
18502 M-x edebug-defun RET
18506 This will cause Emacs to load Edebug automatically if it is not
18507 already loaded, and properly instrument the function.
18509 After instrumenting the function, place your cursor after the
18510 following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}):
18513 (triangle-recursively-bugged 3)
18517 You will be jumped back to the source for
18518 @code{triangle-recursively-bugged} and the cursor positioned at the
18519 beginning of the @code{if} line of the function. Also, you will see
18520 an arrowhead at the left hand side of that line. The arrowhead marks
18521 the line where the function is executing. (In the following examples,
18522 we show the arrowhead with @samp{=>}; in a windowing system, you may
18523 see the arrowhead as a solid triangle in the window fringe.)
18526 =>@point{}(if (= number 1)
18531 In the example, the location of point is displayed with a star,
18532 @samp{@point{}} (in Info, it is displayed as @samp{-!-}).
18535 In the example, the location of point is displayed as @samp{@point{}}
18536 (in a printed book, it is displayed with a five pointed star).
18539 If you now press @key{SPC}, point will move to the next expression to
18540 be executed; the line will look like this:
18543 =>(if @point{}(= number 1)
18547 As you continue to press @key{SPC}, point will move from expression to
18548 expression. At the same time, whenever an expression returns a value,
18549 that value will be displayed in the echo area. For example, after you
18550 move point past @code{number}, you will see the following:
18553 Result: 3 (#o3, #x3, ?\C-c)
18557 This means the value of @code{number} is 3, which is octal three,
18558 hexadecimal three, and @sc{ascii} Control-C (the third letter of the
18559 alphabet, in case you need to know this information).
18561 You can continue moving through the code until you reach the line with
18562 the error. Before evaluation, that line looks like this:
18565 => @point{}(1= number))))) ; @r{Error here.}
18570 When you press @key{SPC} once again, you will produce an error message
18574 Symbol's function definition is void:@: 1=
18580 Press @kbd{q} to quit Edebug.
18582 To remove instrumentation from a function definition, simply
18583 re-evaluate it with a command that does not instrument it.
18584 For example, you could place your cursor after the definition's
18585 closing parenthesis and type @kbd{C-x C-e}.
18587 Edebug does a great deal more than walk with you through a function.
18588 You can set it so it races through on its own, stopping only at an
18589 error or at specified stopping points; you can cause it to display the
18590 changing values of various expressions; you can find out how many
18591 times a function is called, and more.
18593 Edebug is described in @ref{Edebug, , , elisp, The GNU Emacs
18594 Lisp Reference Manual}.
18597 @node Debugging Exercises
18598 @section Debugging Exercises
18602 Install the @code{@value{COUNT-WORDS}} function and then cause it to
18603 enter the built-in debugger when you call it. Run the command on a
18604 region containing two words. You will need to press @kbd{d} a
18605 remarkable number of times. On your system, is a hook called after
18606 the command finishes? (For information on hooks, see @ref{Command
18607 Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference
18611 Copy @code{@value{COUNT-WORDS}} into the @file{*scratch*} buffer,
18612 instrument the function for Edebug, and walk through its execution.
18613 The function does not need to have a bug, although you can introduce
18614 one if you wish. If the function lacks a bug, the walk-through
18615 completes without problems.
18618 While running Edebug, type @kbd{?} to see a list of all the Edebug commands.
18619 (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.,
18620 @kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix
18621 for commands made outside of the Edebug debugging buffer.)
18624 In the Edebug debugging buffer, use the @kbd{p}
18625 (@code{edebug-bounce-point}) command to see where in the region the
18626 @code{@value{COUNT-WORDS}} is working.
18629 Move point to some spot further down the function and then type the
18630 @kbd{h} (@code{edebug-goto-here}) command to jump to that location.
18633 Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to
18634 walk through the function on its own; use an upper case @kbd{T} for
18635 @code{edebug-Trace-fast-mode}.
18638 Set a breakpoint, then run Edebug in Trace mode until it reaches the
18643 @chapter Conclusion
18645 We have now reached the end of this Introduction. You have now
18646 learned enough about programming in Emacs Lisp to set values, to write
18647 simple @file{.emacs} files for yourself and your friends, and write
18648 simple customizations and extensions to Emacs.
18650 This is a place to stop. Or, if you wish, you can now go onward, and
18653 You have learned some of the basic nuts and bolts of programming. But
18654 only some. There are a great many more brackets and hinges that are
18655 easy to use that we have not touched.
18657 A path you can follow right now lies among the sources to GNU Emacs
18660 @cite{The GNU Emacs Lisp Reference Manual}.
18663 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
18664 Emacs Lisp Reference Manual}.
18667 The Emacs Lisp sources are an adventure. When you read the sources and
18668 come across a function or expression that is unfamiliar, you need to
18669 figure out or find out what it does.
18671 Go to the Reference Manual. It is a thorough, complete, and fairly
18672 easy-to-read description of Emacs Lisp. It is written not only for
18673 experts, but for people who know what you know. (The @cite{Reference
18674 Manual} comes with the standard GNU Emacs distribution. Like this
18675 introduction, it comes as a Texinfo source file, so you can read it
18676 on your computer and as a typeset, printed book.)
18678 Go to the other built-in help that is part of GNU Emacs: the built-in
18679 documentation for all functions and variables, and @code{find-tag},
18680 the program that takes you to sources.
18682 Here is an example of how I explore the sources. Because of its name,
18683 @file{simple.el} is the file I looked at first, a long time ago. As
18684 it happens some of the functions in @file{simple.el} are complicated,
18685 or at least look complicated at first sight. The @code{open-line}
18686 function, for example, looks complicated.
18688 You may want to walk through this function slowly, as we did with the
18689 @code{forward-sentence} function. (@xref{forward-sentence, The
18690 @code{forward-sentence} function}.) Or you may want to skip that
18691 function and look at another, such as @code{split-line}. You don't
18692 need to read all the functions. According to
18693 @code{count-words-in-defun}, the @code{split-line} function contains
18694 102 words and symbols.
18696 Even though it is short, @code{split-line} contains expressions
18697 we have not studied: @code{skip-chars-forward}, @code{indent-to},
18698 @code{current-column} and @code{insert-and-inherit}.
18700 Consider the @code{skip-chars-forward} function.
18701 In GNU Emacs, you can find out more about @code{skip-chars-forward} by
18702 typing @kbd{C-h f} (@code{describe-function}) and the name of the
18703 function. This gives you the function documentation.
18705 You may be able to guess what is done by a well named function such as
18706 @code{indent-to}; or you can look it up, too. Incidentally, the
18707 @code{describe-function} function itself is in @file{help.el}; it is
18708 one of those long, but decipherable functions. You can look up
18709 @code{describe-function} using the @kbd{C-h f} command!
18711 In this instance, since the code is Lisp, the @file{*Help*} buffer
18712 contains the name of the library containing the function's source.
18713 You can put point over the name of the library and press the RET key,
18714 which in this situation is bound to @code{help-follow}, and be taken
18715 directly to the source, in the same way as @kbd{M-.}
18718 The definition for @code{describe-function} illustrates how to
18719 customize the @code{interactive} expression without using the standard
18720 character codes; and it shows how to create a temporary buffer.
18722 (The @code{indent-to} function is written in C rather than Emacs Lisp;
18723 it is a built-in function. @code{help-follow} takes you to its
18724 source as does @code{find-tag}, when properly set up.)
18726 You can look at a function's source using @code{find-tag}, which is
18727 bound to @kbd{M-.} Finally, you can find out what the Reference
18728 Manual has to say by visiting the manual in Info, and typing @kbd{i}
18729 (@code{Info-index}) and the name of the function, or by looking up the
18730 function in the index to a printed copy of the manual.
18732 Similarly, you can find out what is meant by
18733 @code{insert-and-inherit}.
18735 Other interesting source files include @file{paragraphs.el},
18736 @file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el}
18737 file includes short, easily understood functions as well as longer
18738 ones. The @file{loaddefs.el} file contains the many standard
18739 autoloads and many keymaps. I have never looked at it all; only at
18740 parts. @file{loadup.el} is the file that loads the standard parts of
18741 Emacs; it tells you a great deal about how Emacs is built.
18742 (@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
18743 Reference Manual}, for more about building.)
18745 As I said, you have learned some nuts and bolts; however, and very
18746 importantly, we have hardly touched major aspects of programming; I
18747 have said nothing about how to sort information, except to use the
18748 predefined @code{sort} function; I have said nothing about how to store
18749 information, except to use variables and lists; I have said nothing
18750 about how to write programs that write programs. These are topics for
18751 another, and different kind of book, a different kind of learning.
18753 What you have done is learn enough for much practical work with GNU
18754 Emacs. What you have done is get started. This is the end of a
18757 @c ================ Appendix ================
18760 @appendix The @code{the-the} Function
18762 @cindex Duplicated words function
18763 @cindex Words, duplicated
18765 Sometimes when you you write text, you duplicate words---as with ``you
18766 you'' near the beginning of this sentence. I find that most
18767 frequently, I duplicate ``the''; hence, I call the function for
18768 detecting duplicated words, @code{the-the}.
18771 As a first step, you could use the following regular expression to
18772 search for duplicates:
18775 \\(\\w+[ \t\n]+\\)\\1
18779 This regexp matches one or more word-constituent characters followed
18780 by one or more spaces, tabs, or newlines. However, it does not detect
18781 duplicated words on different lines, since the ending of the first
18782 word, the end of the line, is different from the ending of the second
18783 word, a space. (For more information about regular expressions, see
18784 @ref{Regexp Search, , Regular Expression Searches}, as well as
18785 @ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
18786 Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp,
18787 The GNU Emacs Lisp Reference Manual}.)
18789 You might try searching just for duplicated word-constituent
18790 characters but that does not work since the pattern detects doubles
18791 such as the two occurrences of ``th'' in ``with the''.
18793 Another possible regexp searches for word-constituent characters
18794 followed by non-word-constituent characters, reduplicated. Here,
18795 @w{@samp{\\w+}} matches one or more word-constituent characters and
18796 @w{@samp{\\W*}} matches zero or more non-word-constituent characters.
18799 \\(\\(\\w+\\)\\W*\\)\\1
18805 Here is the pattern that I use. It is not perfect, but good enough.
18806 @w{@samp{\\b}} matches the empty string, provided it is at the beginning
18807 or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of
18808 any characters that are @emph{not} an @@-sign, space, newline, or tab.
18811 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
18814 One can write more complicated expressions, but I found that this
18815 expression is good enough, so I use it.
18817 Here is the @code{the-the} function, as I include it in my
18818 @file{.emacs} file, along with a handy global key binding:
18823 "Search forward for for a duplicated word."
18825 (message "Searching for for duplicated words ...")
18829 ;; This regexp is not perfect
18830 ;; but is fairly good over all:
18831 (if (re-search-forward
18832 "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move)
18833 (message "Found duplicated word.")
18834 (message "End of buffer")))
18838 ;; Bind 'the-the' to C-c \
18839 (global-set-key "\C-c\\" 'the-the)
18848 one two two three four five
18853 You can substitute the other regular expressions shown above in the
18854 function definition and try each of them on this list.
18857 @appendix Handling the Kill Ring
18858 @cindex Kill ring handling
18859 @cindex Handling the kill ring
18860 @cindex Ring, making a list like a
18862 The kill ring is a list that is transformed into a ring by the
18863 workings of the @code{current-kill} function. The @code{yank} and
18864 @code{yank-pop} commands use the @code{current-kill} function.
18866 This appendix describes the @code{current-kill} function as well as
18867 both the @code{yank} and the @code{yank-pop} commands, but first,
18868 consider the workings of the kill ring.
18871 * What the Kill Ring Does::
18873 * yank:: Paste a copy of a clipped element.
18874 * yank-pop:: Insert element pointed to.
18879 @node What the Kill Ring Does
18880 @unnumberedsec What the Kill Ring Does
18884 The kill ring has a default maximum length of sixty items; this number
18885 is too large for an explanation. Instead, set it to four. Please
18886 evaluate the following:
18890 (setq old-kill-ring-max kill-ring-max)
18891 (setq kill-ring-max 4)
18896 Then, please copy each line of the following indented example into the
18897 kill ring. You may kill each line with @kbd{C-k} or mark it and copy
18901 (In a read-only buffer, such as the @file{*info*} buffer, the kill
18902 command, @kbd{C-k} (@code{kill-line}), will not remove the text,
18903 merely copy it to the kill ring. However, your machine may beep at
18904 you. Alternatively, for silence, you may copy the region of each line
18905 with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark
18906 each line for this command to succeed, but it does not matter at which
18907 end you put point or mark.)
18911 Please invoke the calls in order, so that five elements attempt to
18912 fill the kill ring:
18917 second piece of text
18919 fourth line of text
18926 Then find the value of @code{kill-ring} by evaluating
18938 ("fifth bit of text" "fourth line of text"
18939 "third line" "second piece of text")
18944 The first element, @samp{first some text}, was dropped.
18947 To return to the old value for the length of the kill ring, evaluate:
18950 (setq kill-ring-max old-kill-ring-max)
18954 @appendixsec The @code{current-kill} Function
18955 @findex current-kill
18957 The @code{current-kill} function changes the element in the kill ring
18958 to which @code{kill-ring-yank-pointer} points. (Also, the
18959 @code{kill-new} function sets @code{kill-ring-yank-pointer} to point
18960 to the latest element of the kill ring. The @code{kill-new}
18961 function is used directly or indirectly by @code{kill-append},
18962 @code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line},
18963 and @code{kill-region}.)
18966 * Code for current-kill::
18967 * Understanding current-kill::
18971 @node Code for current-kill
18972 @unnumberedsubsec The code for @code{current-kill}
18977 The @code{current-kill} function is used by @code{yank} and by
18978 @code{yank-pop}. Here is the code for @code{current-kill}:
18982 (defun current-kill (n &optional do-not-move)
18983 "Rotate the yanking point by N places, and then return that kill.
18984 If N is zero and `interprogram-paste-function' is set to a
18985 function that returns a string or a list of strings, and if that
18986 function doesn't return nil, then that string (or list) is added
18987 to the front of the kill ring and the string (or first string in
18988 the list) is returned as the latest kill.
18991 If N is not zero, and if `yank-pop-change-selection' is
18992 non-nil, use `interprogram-cut-function' to transfer the
18993 kill at the new yank point into the window system selection.
18996 If optional arg DO-NOT-MOVE is non-nil, then don't actually
18997 move the yanking point; just return the Nth kill forward."
18999 (let ((interprogram-paste (and (= n 0)
19000 interprogram-paste-function
19001 (funcall interprogram-paste-function))))
19004 (if interprogram-paste
19006 ;; Disable the interprogram cut function when we add the new
19007 ;; text to the kill ring, so Emacs doesn't try to own the
19008 ;; selection, with identical text.
19009 (let ((interprogram-cut-function nil))
19010 (if (listp interprogram-paste)
19011 (mapc 'kill-new (nreverse interprogram-paste))
19012 (kill-new interprogram-paste)))
19016 (or kill-ring (error "Kill ring is empty"))
19017 (let ((ARGth-kill-element
19018 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19019 (length kill-ring))
19021 (unless do-not-move
19022 (setq kill-ring-yank-pointer ARGth-kill-element)
19023 (when (and yank-pop-change-selection
19025 interprogram-cut-function)
19026 (funcall interprogram-cut-function (car ARGth-kill-element))))
19027 (car ARGth-kill-element)))))
19031 Remember also that the @code{kill-new} function sets
19032 @code{kill-ring-yank-pointer} to the latest element of the kill
19033 ring, which means that all the functions that call it set the value
19034 indirectly: @code{kill-append}, @code{copy-region-as-kill},
19035 @code{kill-ring-save}, @code{kill-line}, and @code{kill-region}.
19038 Here is the line in @code{kill-new}, which is explained in
19039 @ref{kill-new function, , The @code{kill-new} function}.
19042 (setq kill-ring-yank-pointer kill-ring)
19046 @node Understanding current-kill
19047 @unnumberedsubsec @code{current-kill} in Outline
19050 The @code{current-kill} function looks complex, but as usual, it can
19051 be understood by taking it apart piece by piece. First look at it in
19056 (defun current-kill (n &optional do-not-move)
19057 "Rotate the yanking point by N places, and then return that kill."
19063 This function takes two arguments, one of which is optional. It has a
19064 documentation string. It is @emph{not} interactive.
19067 * Body of current-kill::
19068 * Digression concerning error:: How to mislead humans, but not computers.
19069 * Determining the Element::
19073 @node Body of current-kill
19074 @unnumberedsubsubsec The Body of @code{current-kill}
19077 The body of the function definition is a @code{let} expression, which
19078 itself has a body as well as a @var{varlist}.
19080 The @code{let} expression declares a variable that will be only usable
19081 within the bounds of this function. This variable is called
19082 @code{interprogram-paste} and is for copying to another program. It
19083 is not for copying within this instance of GNU Emacs. Most window
19084 systems provide a facility for interprogram pasting. Sadly, that
19085 facility usually provides only for the last element. Most windowing
19086 systems have not adopted a ring of many possibilities, even though
19087 Emacs has provided it for decades.
19089 The @code{if} expression has two parts, one if there exists
19090 @code{interprogram-paste} and one if not.
19093 Let us consider the else-part of the @code{current-kill}
19094 function. (The then-part uses the @code{kill-new} function, which
19095 we have already described. @xref{kill-new function, , The
19096 @code{kill-new} function}.)
19100 (or kill-ring (error "Kill ring is empty"))
19101 (let ((ARGth-kill-element
19102 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19103 (length kill-ring))
19106 (setq kill-ring-yank-pointer ARGth-kill-element))
19107 (car ARGth-kill-element))
19112 The code first checks whether the kill ring has content; otherwise it
19116 Note that the @code{or} expression is very similar to testing length
19123 (if (zerop (length kill-ring)) ; @r{if-part}
19124 (error "Kill ring is empty")) ; @r{then-part}
19130 If there is not anything in the kill ring, its length must be zero and
19131 an error message sent to the user: @samp{Kill ring is empty}. The
19132 @code{current-kill} function uses an @code{or} expression which is
19133 simpler. But an @code{if} expression reminds us what goes on.
19135 This @code{if} expression uses the function @code{zerop} which returns
19136 true if the value it is testing is zero. When @code{zerop} tests
19137 true, the then-part of the @code{if} is evaluated. The then-part is a
19138 list starting with the function @code{error}, which is a function that
19139 is similar to the @code{message} function
19140 (@pxref{message, , The @code{message} Function}) in that
19141 it prints a one-line message in the echo area. However, in addition
19142 to printing a message, @code{error} also stops evaluation of the
19143 function within which it is embedded. This means that the rest of the
19144 function will not be evaluated if the length of the kill ring is zero.
19146 Then the @code{current-kill} function selects the element to return.
19147 The selection depends on the number of places that @code{current-kill}
19148 rotates and on where @code{kill-ring-yank-pointer} points.
19150 Next, either the optional @code{do-not-move} argument is true or the
19151 current value of @code{kill-ring-yank-pointer} is set to point to the
19152 list. Finally, another expression returns the first element of the
19153 list even if the @code{do-not-move} argument is true.
19156 @node Digression concerning error
19157 @unnumberedsubsubsec Digression about the word ``error''
19160 In my opinion, it is slightly misleading, at least to humans, to use
19161 the term ``error'' as the name of the @code{error} function. A better
19162 term would be ``cancel''. Strictly speaking, of course, you cannot
19163 point to, much less rotate a pointer to a list that has no length, so
19164 from the point of view of the computer, the word ``error'' is correct.
19165 But a human expects to attempt this sort of thing, if only to find out
19166 whether the kill ring is full or empty. This is an act of
19169 From the human point of view, the act of exploration and discovery is
19170 not necessarily an error, and therefore should not be labeled as one,
19171 even in the bowels of a computer. As it is, the code in Emacs implies
19172 that a human who is acting virtuously, by exploring his or her
19173 environment, is making an error. This is bad. Even though the computer
19174 takes the same steps as it does when there is an error, a term such as
19175 ``cancel'' would have a clearer connotation.
19178 @node Determining the Element
19179 @unnumberedsubsubsec Determining the Element
19182 Among other actions, the else-part of the @code{if} expression sets
19183 the value of @code{kill-ring-yank-pointer} to
19184 @code{ARGth-kill-element} when the kill ring has something in it and
19185 the value of @code{do-not-move} is @code{nil}.
19188 The code looks like this:
19192 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19193 (length kill-ring))
19198 This needs some examination. Unless it is not supposed to move the
19199 pointer, the @code{current-kill} function changes where
19200 @code{kill-ring-yank-pointer} points.
19202 @w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}}
19203 expression does. Also, clearly, @code{ARGth-kill-element} is being
19204 set to be equal to some @sc{cdr} of the kill ring, using the
19205 @code{nthcdr} function that is described in an earlier section.
19206 (@xref{copy-region-as-kill}.) How does it do this?
19208 As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function
19209 works by repeatedly taking the @sc{cdr} of a list---it takes the
19210 @sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{}
19213 The two following expressions produce the same result:
19217 (setq kill-ring-yank-pointer (cdr kill-ring))
19219 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
19223 However, the @code{nthcdr} expression is more complicated. It uses
19224 the @code{mod} function to determine which @sc{cdr} to select.
19226 (You will remember to look at inner functions first; indeed, we will
19227 have to go inside the @code{mod}.)
19229 The @code{mod} function returns the value of its first argument modulo
19230 the second; that is to say, it returns the remainder after dividing
19231 the first argument by the second. The value returned has the same
19232 sign as the second argument.
19240 @result{} 0 ;; @r{because there is no remainder}
19247 In this case, the first argument is often smaller than the second.
19259 We can guess what the @code{-} function does. It is like @code{+} but
19260 subtracts instead of adds; the @code{-} function subtracts its second
19261 argument from its first. Also, we already know what the @code{length}
19262 function does (@pxref{length}). It returns the length of a list.
19264 And @code{n} is the name of the required argument to the
19265 @code{current-kill} function.
19268 So when the first argument to @code{nthcdr} is zero, the @code{nthcdr}
19269 expression returns the whole list, as you can see by evaluating the
19274 ;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four}
19275 ;; @r{and} (mod (- 0 4) 4) @result{} 0
19276 (nthcdr (mod (- 0 4) 4)
19277 '("fourth line of text"
19279 "second piece of text"
19280 "first some text"))
19285 When the first argument to the @code{current-kill} function is one,
19286 the @code{nthcdr} expression returns the list without its first
19291 (nthcdr (mod (- 1 4) 4)
19292 '("fourth line of text"
19294 "second piece of text"
19295 "first some text"))
19299 @cindex @samp{global variable} defined
19300 @cindex @samp{variable, global}, defined
19301 Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer}
19302 are @dfn{global variables}. That means that any expression in Emacs
19303 Lisp can access them. They are not like the local variables set by
19304 @code{let} or like the symbols in an argument list.
19305 Local variables can only be accessed
19306 within the @code{let} that defines them or the function that specifies
19307 them in an argument list (and within expressions called by them).
19310 @c texi2dvi fails when the name of the section is within ifnottex ...
19311 (@xref{Prevent confusion, , @code{let} Prevents Confusion}, and
19312 @ref{defun, , The @code{defun} Macro}.)
19316 @appendixsec @code{yank}
19319 After learning about @code{current-kill}, the code for the
19320 @code{yank} function is almost easy.
19322 The @code{yank} function does not use the
19323 @code{kill-ring-yank-pointer} variable directly. It calls
19324 @code{insert-for-yank} which calls @code{current-kill} which sets the
19325 @code{kill-ring-yank-pointer} variable.
19328 The code looks like this:
19333 (defun yank (&optional arg)
19334 "Reinsert (\"paste\") the last stretch of killed text.
19335 More precisely, reinsert the stretch of killed text most recently
19336 killed OR yanked. Put point at end, and set mark at beginning.
19337 With just \\[universal-argument] as argument, same but put point at beginning (and mark at end).
19338 With argument N, reinsert the Nth most recently killed stretch of killed
19341 When this command inserts killed text into the buffer, it honors
19342 `yank-excluded-properties' and `yank-handler' as described in the
19343 doc string for `insert-for-yank-1', which see.
19345 See also the command `yank-pop' (\\[yank-pop])."
19349 (setq yank-window-start (window-start))
19350 ;; If we don't get all the way thru, make last-command indicate that
19351 ;; for the following command.
19352 (setq this-command t)
19353 (push-mark (point))
19356 (insert-for-yank (current-kill (cond
19361 ;; This is like exchange-point-and-mark, but doesn't activate the mark.
19362 ;; It is cleaner to avoid activation, even though the command
19363 ;; loop would deactivate the mark because we inserted text.
19364 (goto-char (prog1 (mark t)
19365 (set-marker (mark-marker) (point) (current-buffer)))))
19368 ;; If we do get all the way thru, make this-command indicate that.
19369 (if (eq this-command t)
19370 (setq this-command 'yank))
19375 The key expression is @code{insert-for-yank}, which inserts the string
19376 returned by @code{current-kill}, but removes some text properties from
19379 However, before getting to that expression, the function sets the value
19380 of @code{yank-window-start} to the position returned by the
19381 @code{(window-start)} expression, the position at which the display
19382 currently starts. The @code{yank} function also sets
19383 @code{this-command} and pushes the mark.
19385 After it yanks the appropriate element, if the optional argument is a
19386 @sc{cons} rather than a number or nothing, it puts point at beginning
19387 of the yanked text and mark at its end.
19389 (The @code{prog1} function is like @code{progn} but returns the value
19390 of its first argument rather than the value of its last argument. Its
19391 first argument is forced to return the buffer's mark as an integer.
19392 You can see the documentation for these functions by placing point
19393 over them in this buffer and then typing @kbd{C-h f}
19394 (@code{describe-function}) followed by a @kbd{RET}; the default is the
19397 The last part of the function tells what to do when it succeeds.
19400 @appendixsec @code{yank-pop}
19403 After understanding @code{yank} and @code{current-kill}, you know how
19404 to approach the @code{yank-pop} function. Leaving out the
19405 documentation to save space, it looks like this:
19410 (defun yank-pop (&optional arg)
19413 (if (not (eq last-command 'yank))
19414 (error "Previous command was not a yank"))
19417 (setq this-command 'yank)
19418 (unless arg (setq arg 1))
19419 (let ((inhibit-read-only t)
19420 (before (< (point) (mark t))))
19424 (funcall (or yank-undo-function 'delete-region) (point) (mark t))
19425 (funcall (or yank-undo-function 'delete-region) (mark t) (point)))
19426 (setq yank-undo-function nil)
19429 (set-marker (mark-marker) (point) (current-buffer))
19430 (insert-for-yank (current-kill arg))
19431 ;; Set the window start back where it was in the yank command,
19433 (set-window-start (selected-window) yank-window-start t)
19437 ;; This is like exchange-point-and-mark,
19438 ;; but doesn't activate the mark.
19439 ;; It is cleaner to avoid activation, even though the command
19440 ;; loop would deactivate the mark because we inserted text.
19441 (goto-char (prog1 (mark t)
19442 (set-marker (mark-marker)
19444 (current-buffer))))))
19449 The function is interactive with a small @samp{p} so the prefix
19450 argument is processed and passed to the function. The command can
19451 only be used after a previous yank; otherwise an error message is
19452 sent. This check uses the variable @code{last-command} which is set
19453 by @code{yank} and is discussed elsewhere.
19454 (@xref{copy-region-as-kill}.)
19456 The @code{let} clause sets the variable @code{before} to true or false
19457 depending whether point is before or after mark and then the region
19458 between point and mark is deleted. This is the region that was just
19459 inserted by the previous yank and it is this text that will be
19462 @code{funcall} calls its first argument as a function, passing
19463 remaining arguments to it. The first argument is whatever the
19464 @code{or} expression returns. The two remaining arguments are the
19465 positions of point and mark set by the preceding @code{yank} command.
19467 There is more, but that is the hardest part.
19470 @appendixsec The @file{ring.el} File
19471 @cindex @file{ring.el} file
19473 Interestingly, GNU Emacs posses a file called @file{ring.el} that
19474 provides many of the features we just discussed. But functions such
19475 as @code{kill-ring-yank-pointer} do not use this library, possibly
19476 because they were written earlier.
19479 @appendix A Graph with Labeled Axes
19481 Printed axes help you understand a graph. They convey scale. In an
19482 earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we
19483 wrote the code to print the body of a graph. Here we write the code
19484 for printing and labeling vertical and horizontal axes, along with the
19488 * Labeled Example::
19489 * print-graph Varlist:: @code{let} expression in @code{print-graph}.
19490 * print-Y-axis:: Print a label for the vertical axis.
19491 * print-X-axis:: Print a horizontal label.
19492 * Print Whole Graph:: The function to print a complete graph.
19496 @node Labeled Example
19497 @unnumberedsec Labeled Example Graph
19500 Since insertions fill a buffer to the right and below point, the new
19501 graph printing function should first print the Y or vertical axis,
19502 then the body of the graph, and finally the X or horizontal axis.
19503 This sequence lays out for us the contents of the function:
19513 Print body of graph.
19520 Here is an example of how a finished graph should look:
19533 1 - ****************
19540 In this graph, both the vertical and the horizontal axes are labeled
19541 with numbers. However, in some graphs, the horizontal axis is time
19542 and would be better labeled with months, like this:
19556 Indeed, with a little thought, we can easily come up with a variety of
19557 vertical and horizontal labeling schemes. Our task could become
19558 complicated. But complications breed confusion. Rather than permit
19559 this, it is better choose a simple labeling scheme for our first
19560 effort, and to modify or replace it later.
19563 These considerations suggest the following outline for the
19564 @code{print-graph} function:
19568 (defun print-graph (numbers-list)
19569 "@var{documentation}@dots{}"
19570 (let ((height @dots{}
19574 (print-Y-axis height @dots{} )
19575 (graph-body-print numbers-list)
19576 (print-X-axis @dots{} )))
19580 We can work on each part of the @code{print-graph} function definition
19583 @node print-graph Varlist
19584 @appendixsec The @code{print-graph} Varlist
19585 @cindex @code{print-graph} varlist
19587 In writing the @code{print-graph} function, the first task is to write
19588 the varlist in the @code{let} expression. (We will leave aside for the
19589 moment any thoughts about making the function interactive or about the
19590 contents of its documentation string.)
19592 The varlist should set several values. Clearly, the top of the label
19593 for the vertical axis must be at least the height of the graph, which
19594 means that we must obtain this information here. Note that the
19595 @code{print-graph-body} function also requires this information. There
19596 is no reason to calculate the height of the graph in two different
19597 places, so we should change @code{print-graph-body} from the way we
19598 defined it earlier to take advantage of the calculation.
19600 Similarly, both the function for printing the X axis labels and the
19601 @code{print-graph-body} function need to learn the value of the width of
19602 each symbol. We can perform the calculation here and change the
19603 definition for @code{print-graph-body} from the way we defined it in the
19606 The length of the label for the horizontal axis must be at least as long
19607 as the graph. However, this information is used only in the function
19608 that prints the horizontal axis, so it does not need to be calculated here.
19610 These thoughts lead us directly to the following form for the varlist
19611 in the @code{let} for @code{print-graph}:
19615 (let ((height (apply 'max numbers-list)) ; @r{First version.}
19616 (symbol-width (length graph-blank)))
19621 As we shall see, this expression is not quite right.
19625 @appendixsec The @code{print-Y-axis} Function
19626 @cindex Axis, print vertical
19627 @cindex Y axis printing
19628 @cindex Vertical axis printing
19629 @cindex Print vertical axis
19631 The job of the @code{print-Y-axis} function is to print a label for
19632 the vertical axis that looks like this:
19650 The function should be passed the height of the graph, and then should
19651 construct and insert the appropriate numbers and marks.
19654 * print-Y-axis in Detail::
19655 * Height of label:: What height for the Y axis?
19656 * Compute a Remainder:: How to compute the remainder of a division.
19657 * Y Axis Element:: Construct a line for the Y axis.
19658 * Y-axis-column:: Generate a list of Y axis labels.
19659 * print-Y-axis Penultimate:: A not quite final version.
19663 @node print-Y-axis in Detail
19664 @unnumberedsubsec The @code{print-Y-axis} Function in Detail
19667 It is easy enough to see in the figure what the Y axis label should
19668 look like; but to say in words, and then to write a function
19669 definition to do the job is another matter. It is not quite true to
19670 say that we want a number and a tic every five lines: there are only
19671 three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4),
19672 but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8,
19673 and 9). It is better to say that we want a number and a tic mark on
19674 the base line (number 1) and then that we want a number and a tic on
19675 the fifth line from the bottom and on every line that is a multiple of
19679 @node Height of label
19680 @unnumberedsubsec What height should the label be?
19683 The next issue is what height the label should be? Suppose the maximum
19684 height of tallest column of the graph is seven. Should the highest
19685 label on the Y axis be @samp{5 -}, and should the graph stick up above
19686 the label? Or should the highest label be @samp{7 -}, and mark the peak
19687 of the graph? Or should the highest label be @code{10 -}, which is a
19688 multiple of five, and be higher than the topmost value of the graph?
19690 The latter form is preferred. Most graphs are drawn within rectangles
19691 whose sides are an integral number of steps long---5, 10, 15, and so
19692 on for a step distance of five. But as soon as we decide to use a
19693 step height for the vertical axis, we discover that the simple
19694 expression in the varlist for computing the height is wrong. The
19695 expression is @code{(apply 'max numbers-list)}. This returns the
19696 precise height, not the maximum height plus whatever is necessary to
19697 round up to the nearest multiple of five. A more complex expression
19700 As usual in cases like this, a complex problem becomes simpler if it is
19701 divided into several smaller problems.
19703 First, consider the case when the highest value of the graph is an
19704 integral multiple of five---when it is 5, 10, 15, or some higher
19705 multiple of five. We can use this value as the Y axis height.
19707 A fairly simply way to determine whether a number is a multiple of
19708 five is to divide it by five and see if the division results in a
19709 remainder. If there is no remainder, the number is a multiple of
19710 five. Thus, seven divided by five has a remainder of two, and seven
19711 is not an integral multiple of five. Put in slightly different
19712 language, more reminiscent of the classroom, five goes into seven
19713 once, with a remainder of two. However, five goes into ten twice,
19714 with no remainder: ten is an integral multiple of five.
19716 @node Compute a Remainder
19717 @appendixsubsec Side Trip: Compute a Remainder
19719 @findex % @r{(remainder function)}
19720 @cindex Remainder function, @code{%}
19721 In Lisp, the function for computing a remainder is @code{%}. The
19722 function returns the remainder of its first argument divided by its
19723 second argument. As it happens, @code{%} is a function in Emacs Lisp
19724 that you cannot discover using @code{apropos}: you find nothing if you
19725 type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to
19726 learn of the existence of @code{%} is to read about it in a book such
19727 as this or in the Emacs Lisp sources.
19729 You can try the @code{%} function by evaluating the following two
19741 The first expression returns 2 and the second expression returns 0.
19743 To test whether the returned value is zero or some other number, we
19744 can use the @code{zerop} function. This function returns @code{t} if
19745 its argument, which must be a number, is zero.
19757 Thus, the following expression will return @code{t} if the height
19758 of the graph is evenly divisible by five:
19761 (zerop (% height 5))
19765 (The value of @code{height}, of course, can be found from @code{(apply
19766 'max numbers-list)}.)
19768 On the other hand, if the value of @code{height} is not a multiple of
19769 five, we want to reset the value to the next higher multiple of five.
19770 This is straightforward arithmetic using functions with which we are
19771 already familiar. First, we divide the value of @code{height} by five
19772 to determine how many times five goes into the number. Thus, five
19773 goes into twelve twice. If we add one to this quotient and multiply by
19774 five, we will obtain the value of the next multiple of five that is
19775 larger than the height. Five goes into twelve twice. Add one to two,
19776 and multiply by five; the result is fifteen, which is the next multiple
19777 of five that is higher than twelve. The Lisp expression for this is:
19780 (* (1+ (/ height 5)) 5)
19784 For example, if you evaluate the following, the result is 15:
19787 (* (1+ (/ 12 5)) 5)
19790 All through this discussion, we have been using 5 as the value
19791 for spacing labels on the Y axis; but we may want to use some other
19792 value. For generality, we should replace 5 with a variable to
19793 which we can assign a value. The best name I can think of for this
19794 variable is @code{Y-axis-label-spacing}.
19797 Using this term, and an @code{if} expression, we produce the
19802 (if (zerop (% height Y-axis-label-spacing))
19805 (* (1+ (/ height Y-axis-label-spacing))
19806 Y-axis-label-spacing))
19811 This expression returns the value of @code{height} itself if the height
19812 is an even multiple of the value of the @code{Y-axis-label-spacing} or
19813 else it computes and returns a value of @code{height} that is equal to
19814 the next higher multiple of the value of the @code{Y-axis-label-spacing}.
19816 We can now include this expression in the @code{let} expression of the
19817 @code{print-graph} function (after first setting the value of
19818 @code{Y-axis-label-spacing}):
19819 @vindex Y-axis-label-spacing
19823 (defvar Y-axis-label-spacing 5
19824 "Number of lines from one Y axis label to next.")
19829 (let* ((height (apply 'max numbers-list))
19830 (height-of-top-line
19831 (if (zerop (% height Y-axis-label-spacing))
19836 (* (1+ (/ height Y-axis-label-spacing))
19837 Y-axis-label-spacing)))
19838 (symbol-width (length graph-blank))))
19844 (Note use of the @code{let*} function: the initial value of height is
19845 computed once by the @code{(apply 'max numbers-list)} expression and
19846 then the resulting value of @code{height} is used to compute its
19847 final value. @xref{fwd-para let, , The @code{let*} expression}, for
19848 more about @code{let*}.)
19850 @node Y Axis Element
19851 @appendixsubsec Construct a Y Axis Element
19853 When we print the vertical axis, we want to insert strings such as
19854 @w{@samp{5 -}} and @w{@samp{10 - }} every five lines.
19855 Moreover, we want the numbers and dashes to line up, so shorter
19856 numbers must be padded with leading spaces. If some of the strings
19857 use two digit numbers, the strings with single digit numbers must
19858 include a leading blank space before the number.
19860 @findex number-to-string
19861 To figure out the length of the number, the @code{length} function is
19862 used. But the @code{length} function works only with a string, not with
19863 a number. So the number has to be converted from being a number to
19864 being a string. This is done with the @code{number-to-string} function.
19869 (length (number-to-string 35))
19872 (length (number-to-string 100))
19878 (@code{number-to-string} is also called @code{int-to-string}; you will
19879 see this alternative name in various sources.)
19881 In addition, in each label, each number is followed by a string such
19882 as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker.
19883 This variable is defined with @code{defvar}:
19888 (defvar Y-axis-tic " - "
19889 "String that follows number in a Y axis label.")
19893 The length of the Y label is the sum of the length of the Y axis tic
19894 mark and the length of the number of the top of the graph.
19897 (length (concat (number-to-string height) Y-axis-tic)))
19900 This value will be calculated by the @code{print-graph} function in
19901 its varlist as @code{full-Y-label-width} and passed on. (Note that we
19902 did not think to include this in the varlist when we first proposed it.)
19904 To make a complete vertical axis label, a tic mark is concatenated
19905 with a number; and the two together may be preceded by one or more
19906 spaces depending on how long the number is. The label consists of
19907 three parts: the (optional) leading spaces, the number, and the tic
19908 mark. The function is passed the value of the number for the specific
19909 row, and the value of the width of the top line, which is calculated
19910 (just once) by @code{print-graph}.
19914 (defun Y-axis-element (number full-Y-label-width)
19915 "Construct a NUMBERed label element.
19916 A numbered element looks like this ` 5 - ',
19917 and is padded as needed so all line up with
19918 the element for the largest number."
19921 (let* ((leading-spaces
19922 (- full-Y-label-width
19924 (concat (number-to-string number)
19929 (make-string leading-spaces ? )
19930 (number-to-string number)
19935 The @code{Y-axis-element} function concatenates together the leading
19936 spaces, if any; the number, as a string; and the tic mark.
19938 To figure out how many leading spaces the label will need, the
19939 function subtracts the actual length of the label---the length of the
19940 number plus the length of the tic mark---from the desired label width.
19942 @findex make-string
19943 Blank spaces are inserted using the @code{make-string} function. This
19944 function takes two arguments: the first tells it how long the string
19945 will be and the second is a symbol for the character to insert, in a
19946 special format. The format is a question mark followed by a blank
19947 space, like this, @samp{? }. @xref{Character Type, , Character Type,
19948 elisp, The GNU Emacs Lisp Reference Manual}, for a description of the
19949 syntax for characters. (Of course, you might want to replace the
19950 blank space by some other character @dots{} You know what to do.)
19952 The @code{number-to-string} function is used in the concatenation
19953 expression, to convert the number to a string that is concatenated
19954 with the leading spaces and the tic mark.
19956 @node Y-axis-column
19957 @appendixsubsec Create a Y Axis Column
19959 The preceding functions provide all the tools needed to construct a
19960 function that generates a list of numbered and blank strings to insert
19961 as the label for the vertical axis:
19963 @findex Y-axis-column
19966 (defun Y-axis-column (height width-of-label)
19967 "Construct list of Y axis labels and blank strings.
19968 For HEIGHT of line above base and WIDTH-OF-LABEL."
19972 (while (> height 1)
19973 (if (zerop (% height Y-axis-label-spacing))
19974 ;; @r{Insert label.}
19977 (Y-axis-element height width-of-label)
19981 ;; @r{Else, insert blanks.}
19984 (make-string width-of-label ? )
19986 (setq height (1- height)))
19987 ;; @r{Insert base line.}
19989 (cons (Y-axis-element 1 width-of-label) Y-axis))
19990 (nreverse Y-axis)))
19994 In this function, we start with the value of @code{height} and
19995 repetitively subtract one from its value. After each subtraction, we
19996 test to see whether the value is an integral multiple of the
19997 @code{Y-axis-label-spacing}. If it is, we construct a numbered label
19998 using the @code{Y-axis-element} function; if not, we construct a
19999 blank label using the @code{make-string} function. The base line
20000 consists of the number one followed by a tic mark.
20003 @node print-Y-axis Penultimate
20004 @appendixsubsec The Not Quite Final Version of @code{print-Y-axis}
20006 The list constructed by the @code{Y-axis-column} function is passed to
20007 the @code{print-Y-axis} function, which inserts the list as a column.
20009 @findex print-Y-axis
20012 (defun print-Y-axis (height full-Y-label-width)
20013 "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH.
20014 Height must be the maximum height of the graph.
20015 Full width is the width of the highest label element."
20016 ;; Value of height and full-Y-label-width
20017 ;; are passed by print-graph.
20020 (let ((start (point)))
20022 (Y-axis-column height full-Y-label-width))
20023 ;; @r{Place point ready for inserting graph.}
20025 ;; @r{Move point forward by value of} full-Y-label-width
20026 (forward-char full-Y-label-width)))
20030 The @code{print-Y-axis} uses the @code{insert-rectangle} function to
20031 insert the Y axis labels created by the @code{Y-axis-column} function.
20032 In addition, it places point at the correct position for printing the body of
20035 You can test @code{print-Y-axis}:
20043 Y-axis-label-spacing
20052 Copy the following expression:
20055 (print-Y-axis 12 5)
20059 Switch to the @file{*scratch*} buffer and place the cursor where you
20060 want the axis labels to start.
20063 Type @kbd{M-:} (@code{eval-expression}).
20066 Yank the @code{graph-body-print} expression into the minibuffer
20067 with @kbd{C-y} (@code{yank)}.
20070 Press @key{RET} to evaluate the expression.
20073 Emacs will print labels vertically, the top one being @w{@samp{10 -@w{
20074 }}}. (The @code{print-graph} function will pass the value of
20075 @code{height-of-top-line}, which in this case will end up as 15,
20076 thereby getting rid of what might appear as a bug.)
20080 @appendixsec The @code{print-X-axis} Function
20081 @cindex Axis, print horizontal
20082 @cindex X axis printing
20083 @cindex Print horizontal axis
20084 @cindex Horizontal axis printing
20086 X axis labels are much like Y axis labels, except that the ticks are on a
20087 line above the numbers. Labels should look like this:
20096 The first tic is under the first column of the graph and is preceded by
20097 several blank spaces. These spaces provide room in rows above for the Y
20098 axis labels. The second, third, fourth, and subsequent ticks are all
20099 spaced equally, according to the value of @code{X-axis-label-spacing}.
20101 The second row of the X axis consists of numbers, preceded by several
20102 blank spaces and also separated according to the value of the variable
20103 @code{X-axis-label-spacing}.
20105 The value of the variable @code{X-axis-label-spacing} should itself be
20106 measured in units of @code{symbol-width}, since you may want to change
20107 the width of the symbols that you are using to print the body of the
20108 graph without changing the ways the graph is labeled.
20111 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
20112 * X Axis Tic Marks:: Create tic marks for the horizontal axis.
20116 @node Similarities differences
20117 @unnumberedsubsec Similarities and differences
20120 The @code{print-X-axis} function is constructed in more or less the
20121 same fashion as the @code{print-Y-axis} function except that it has
20122 two lines: the line of tic marks and the numbers. We will write a
20123 separate function to print each line and then combine them within the
20124 @code{print-X-axis} function.
20126 This is a three step process:
20130 Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}.
20133 Write a function to print the X numbers, @code{print-X-axis-numbered-line}.
20136 Write a function to print both lines, the @code{print-X-axis} function,
20137 using @code{print-X-axis-tic-line} and
20138 @code{print-X-axis-numbered-line}.
20141 @node X Axis Tic Marks
20142 @appendixsubsec X Axis Tic Marks
20144 The first function should print the X axis tic marks. We must specify
20145 the tic marks themselves and their spacing:
20149 (defvar X-axis-label-spacing
20150 (if (boundp 'graph-blank)
20151 (* 5 (length graph-blank)) 5)
20152 "Number of units from one X axis label to next.")
20157 (Note that the value of @code{graph-blank} is set by another
20158 @code{defvar}. The @code{boundp} predicate checks whether it has
20159 already been set; @code{boundp} returns @code{nil} if it has not. If
20160 @code{graph-blank} were unbound and we did not use this conditional
20161 construction, in a recent GNU Emacs, we would enter the debugger and
20162 see an error message saying @samp{@w{Debugger entered--Lisp error:}
20163 @w{(void-variable graph-blank)}}.)
20166 Here is the @code{defvar} for @code{X-axis-tic-symbol}:
20170 (defvar X-axis-tic-symbol "|"
20171 "String to insert to point to a column in X axis.")
20176 The goal is to make a line that looks like this:
20182 The first tic is indented so that it is under the first column, which is
20183 indented to provide space for the Y axis labels.
20185 A tic element consists of the blank spaces that stretch from one tic to
20186 the next plus a tic symbol. The number of blanks is determined by the
20187 width of the tic symbol and the @code{X-axis-label-spacing}.
20190 The code looks like this:
20194 ;;; X-axis-tic-element
20198 ;; @r{Make a string of blanks.}
20199 (- (* symbol-width X-axis-label-spacing)
20200 (length X-axis-tic-symbol))
20202 ;; @r{Concatenate blanks with tic symbol.}
20208 Next, we determine how many blanks are needed to indent the first tic
20209 mark to the first column of the graph. This uses the value of
20210 @code{full-Y-label-width} passed it by the @code{print-graph} function.
20213 The code to make @code{X-axis-leading-spaces}
20218 ;; X-axis-leading-spaces
20220 (make-string full-Y-label-width ? )
20225 We also need to determine the length of the horizontal axis, which is
20226 the length of the numbers list, and the number of ticks in the horizontal
20233 (length numbers-list)
20239 (* symbol-width X-axis-label-spacing)
20243 ;; number-of-X-ticks
20244 (if (zerop (% (X-length tic-width)))
20245 (/ (X-length tic-width))
20246 (1+ (/ (X-length tic-width))))
20251 All this leads us directly to the function for printing the X axis tic line:
20253 @findex print-X-axis-tic-line
20256 (defun print-X-axis-tic-line
20257 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
20258 "Print ticks for X axis."
20259 (insert X-axis-leading-spaces)
20260 (insert X-axis-tic-symbol) ; @r{Under first column.}
20263 ;; @r{Insert second tic in the right spot.}
20266 (- (* symbol-width X-axis-label-spacing)
20267 ;; @r{Insert white space up to second tic symbol.}
20268 (* 2 (length X-axis-tic-symbol)))
20270 X-axis-tic-symbol))
20273 ;; @r{Insert remaining ticks.}
20274 (while (> number-of-X-tics 1)
20275 (insert X-axis-tic-element)
20276 (setq number-of-X-tics (1- number-of-X-tics))))
20280 The line of numbers is equally straightforward:
20283 First, we create a numbered element with blank spaces before each number:
20285 @findex X-axis-element
20288 (defun X-axis-element (number)
20289 "Construct a numbered X axis element."
20290 (let ((leading-spaces
20291 (- (* symbol-width X-axis-label-spacing)
20292 (length (number-to-string number)))))
20293 (concat (make-string leading-spaces ? )
20294 (number-to-string number))))
20298 Next, we create the function to print the numbered line, starting with
20299 the number 1 under the first column:
20301 @findex print-X-axis-numbered-line
20304 (defun print-X-axis-numbered-line
20305 (number-of-X-tics X-axis-leading-spaces)
20306 "Print line of X-axis numbers"
20307 (let ((number X-axis-label-spacing))
20308 (insert X-axis-leading-spaces)
20314 ;; @r{Insert white space up to next number.}
20315 (- (* symbol-width X-axis-label-spacing) 2)
20317 (number-to-string number)))
20320 ;; @r{Insert remaining numbers.}
20321 (setq number (+ number X-axis-label-spacing))
20322 (while (> number-of-X-tics 1)
20323 (insert (X-axis-element number))
20324 (setq number (+ number X-axis-label-spacing))
20325 (setq number-of-X-tics (1- number-of-X-tics)))))
20329 Finally, we need to write the @code{print-X-axis} that uses
20330 @code{print-X-axis-tic-line} and
20331 @code{print-X-axis-numbered-line}.
20333 The function must determine the local values of the variables used by both
20334 @code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and
20335 then it must call them. Also, it must print the carriage return that
20336 separates the two lines.
20338 The function consists of a varlist that specifies five local variables,
20339 and calls to each of the two line printing functions:
20341 @findex print-X-axis
20344 (defun print-X-axis (numbers-list)
20345 "Print X axis labels to length of NUMBERS-LIST."
20346 (let* ((leading-spaces
20347 (make-string full-Y-label-width ? ))
20350 ;; symbol-width @r{is provided by} graph-body-print
20351 (tic-width (* symbol-width X-axis-label-spacing))
20352 (X-length (length numbers-list))
20360 ;; @r{Make a string of blanks.}
20361 (- (* symbol-width X-axis-label-spacing)
20362 (length X-axis-tic-symbol))
20366 ;; @r{Concatenate blanks with tic symbol.}
20367 X-axis-tic-symbol))
20371 (if (zerop (% X-length tic-width))
20372 (/ X-length tic-width)
20373 (1+ (/ X-length tic-width)))))
20376 (print-X-axis-tic-line tic-number leading-spaces X-tic)
20378 (print-X-axis-numbered-line tic-number leading-spaces)))
20383 You can test @code{print-X-axis}:
20387 Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing},
20388 @code{print-X-axis-tic-line}, as well as @code{X-axis-element},
20389 @code{print-X-axis-numbered-line}, and @code{print-X-axis}.
20392 Copy the following expression:
20397 (let ((full-Y-label-width 5)
20400 '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16))))
20405 Switch to the @file{*scratch*} buffer and place the cursor where you
20406 want the axis labels to start.
20409 Type @kbd{M-:} (@code{eval-expression}).
20412 Yank the test expression into the minibuffer
20413 with @kbd{C-y} (@code{yank)}.
20416 Press @key{RET} to evaluate the expression.
20420 Emacs will print the horizontal axis like this:
20430 @node Print Whole Graph
20431 @appendixsec Printing the Whole Graph
20432 @cindex Printing the whole graph
20433 @cindex Whole graph printing
20434 @cindex Graph, printing all
20436 Now we are nearly ready to print the whole graph.
20438 The function to print the graph with the proper labels follows the
20439 outline we created earlier (@pxref{Full Graph, , A Graph with Labeled
20440 Axes}), but with additions.
20443 Here is the outline:
20447 (defun print-graph (numbers-list)
20448 "@var{documentation}@dots{}"
20449 (let ((height @dots{}
20453 (print-Y-axis height @dots{} )
20454 (graph-body-print numbers-list)
20455 (print-X-axis @dots{} )))
20460 * The final version:: A few changes.
20461 * Test print-graph:: Run a short test.
20462 * Graphing words in defuns:: Executing the final code.
20463 * lambda:: How to write an anonymous function.
20464 * mapcar:: Apply a function to elements of a list.
20465 * Another Bug:: Yet another bug @dots{} most insidious.
20466 * Final printed graph:: The graph itself!
20470 @node The final version
20471 @unnumberedsubsec Changes for the Final Version
20474 The final version is different from what we planned in two ways:
20475 first, it contains additional values calculated once in the varlist;
20476 second, it carries an option to specify the labels' increment per row.
20477 This latter feature turns out to be essential; otherwise, a graph may
20478 have more rows than fit on a display or on a sheet of paper.
20481 This new feature requires a change to the @code{Y-axis-column}
20482 function, to add @code{vertical-step} to it. The function looks like
20485 @findex Y-axis-column @r{Final version.}
20488 ;;; @r{Final version.}
20489 (defun Y-axis-column
20490 (height width-of-label &optional vertical-step)
20491 "Construct list of labels for Y axis.
20492 HEIGHT is maximum height of graph.
20493 WIDTH-OF-LABEL is maximum width of label.
20494 VERTICAL-STEP, an option, is a positive integer
20495 that specifies how much a Y axis label increments
20496 for each line. For example, a step of 5 means
20497 that each line is five units of the graph."
20501 (number-per-line (or vertical-step 1)))
20502 (while (> height 1)
20503 (if (zerop (% height Y-axis-label-spacing))
20506 ;; @r{Insert label.}
20510 (* height number-per-line)
20515 ;; @r{Else, insert blanks.}
20518 (make-string width-of-label ? )
20520 (setq height (1- height)))
20523 ;; @r{Insert base line.}
20524 (setq Y-axis (cons (Y-axis-element
20525 (or vertical-step 1)
20528 (nreverse Y-axis)))
20532 The values for the maximum height of graph and the width of a symbol
20533 are computed by @code{print-graph} in its @code{let} expression; so
20534 @code{graph-body-print} must be changed to accept them.
20536 @findex graph-body-print @r{Final version.}
20539 ;;; @r{Final version.}
20540 (defun graph-body-print (numbers-list height symbol-width)
20541 "Print a bar graph of the NUMBERS-LIST.
20542 The numbers-list consists of the Y-axis values.
20543 HEIGHT is maximum height of graph.
20544 SYMBOL-WIDTH is number of each column."
20547 (let (from-position)
20548 (while numbers-list
20549 (setq from-position (point))
20551 (column-of-graph height (car numbers-list)))
20552 (goto-char from-position)
20553 (forward-char symbol-width)
20556 ;; @r{Draw graph column by column.}
20558 (setq numbers-list (cdr numbers-list)))
20559 ;; @r{Place point for X axis labels.}
20560 (forward-line height)
20566 Finally, the code for the @code{print-graph} function:
20568 @findex print-graph @r{Final version.}
20571 ;;; @r{Final version.}
20573 (numbers-list &optional vertical-step)
20574 "Print labeled bar graph of the NUMBERS-LIST.
20575 The numbers-list consists of the Y-axis values.
20579 Optionally, VERTICAL-STEP, a positive integer,
20580 specifies how much a Y axis label increments for
20581 each line. For example, a step of 5 means that
20582 each row is five units."
20585 (let* ((symbol-width (length graph-blank))
20586 ;; @code{height} @r{is both the largest number}
20587 ;; @r{and the number with the most digits.}
20588 (height (apply 'max numbers-list))
20591 (height-of-top-line
20592 (if (zerop (% height Y-axis-label-spacing))
20595 (* (1+ (/ height Y-axis-label-spacing))
20596 Y-axis-label-spacing)))
20599 (vertical-step (or vertical-step 1))
20600 (full-Y-label-width
20606 (* height-of-top-line vertical-step))
20612 height-of-top-line full-Y-label-width vertical-step)
20616 numbers-list height-of-top-line symbol-width)
20617 (print-X-axis numbers-list)))
20621 @node Test print-graph
20622 @appendixsubsec Testing @code{print-graph}
20625 We can test the @code{print-graph} function with a short list of numbers:
20629 Install the final versions of @code{Y-axis-column},
20630 @code{graph-body-print}, and @code{print-graph} (in addition to the
20634 Copy the following expression:
20637 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1))
20641 Switch to the @file{*scratch*} buffer and place the cursor where you
20642 want the axis labels to start.
20645 Type @kbd{M-:} (@code{eval-expression}).
20648 Yank the test expression into the minibuffer
20649 with @kbd{C-y} (@code{yank)}.
20652 Press @key{RET} to evaluate the expression.
20656 Emacs will print a graph that looks like this:
20677 On the other hand, if you pass @code{print-graph} a
20678 @code{vertical-step} value of 2, by evaluating this expression:
20681 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2)
20686 The graph looks like this:
20707 (A question: is the @samp{2} on the bottom of the vertical axis a bug or a
20708 feature? If you think it is a bug, and should be a @samp{1} instead, (or
20709 even a @samp{0}), you can modify the sources.)
20711 @node Graphing words in defuns
20712 @appendixsubsec Graphing Numbers of Words and Symbols
20714 Now for the graph for which all this code was written: a graph that
20715 shows how many function definitions contain fewer than 10 words and
20716 symbols, how many contain between 10 and 19 words and symbols, how
20717 many contain between 20 and 29 words and symbols, and so on.
20719 This is a multi-step process. First make sure you have loaded all the
20723 It is a good idea to reset the value of @code{top-of-ranges} in case
20724 you have set it to some different value. You can evaluate the
20729 (setq top-of-ranges
20732 110 120 130 140 150
20733 160 170 180 190 200
20734 210 220 230 240 250
20735 260 270 280 290 300)
20740 Next create a list of the number of words and symbols in each range.
20744 Evaluate the following:
20748 (setq list-for-graph
20751 (recursive-lengths-list-many-files
20752 (directory-files "/usr/local/emacs/lisp"
20760 On my old machine, this took about an hour. It looked though 303 Lisp
20761 files in my copy of Emacs version 19.23. After all that computing,
20762 the @code{list-for-graph} had this value:
20766 (537 1027 955 785 594 483 349 292 224 199 166 120 116 99
20767 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220)
20772 This means that my copy of Emacs had 537 function definitions with
20773 fewer than 10 words or symbols in them, 1,027 function definitions
20774 with 10 to 19 words or symbols in them, 955 function definitions with
20775 20 to 29 words or symbols in them, and so on.
20777 Clearly, just by looking at this list we can see that most function
20778 definitions contain ten to thirty words and symbols.
20780 Now for printing. We do @emph{not} want to print a graph that is
20781 1,030 lines high @dots{} Instead, we should print a graph that is
20782 fewer than twenty-five lines high. A graph that height can be
20783 displayed on almost any monitor, and easily printed on a sheet of paper.
20785 This means that each value in @code{list-for-graph} must be reduced to
20786 one-fiftieth its present value.
20788 Here is a short function to do just that, using two functions we have
20789 not yet seen, @code{mapcar} and @code{lambda}.
20793 (defun one-fiftieth (full-range)
20794 "Return list, each number one-fiftieth of previous."
20795 (mapcar (lambda (arg) (/ arg 50)) full-range))
20800 @appendixsubsec A @code{lambda} Expression: Useful Anonymity
20801 @cindex Anonymous function
20804 @code{lambda} is the symbol for an anonymous function, a function
20805 without a name. Every time you use an anonymous function, you need to
20806 include its whole body.
20813 (lambda (arg) (/ arg 50))
20817 is a function that returns the value resulting from
20818 dividing whatever is passed to it as @code{arg} by 50.
20821 Earlier, for example, we had a function @code{multiply-by-seven}; it
20822 multiplied its argument by 7. This function is similar, except it
20823 divides its argument by 50; and, it has no name. The anonymous
20824 equivalent of @code{multiply-by-seven} is:
20827 (lambda (number) (* 7 number))
20831 (@xref{defun, , The @code{defun} Macro}.)
20835 If we want to multiply 3 by 7, we can write:
20837 @c clear print-postscript-figures
20838 @c lambda example diagram #1
20842 (multiply-by-seven 3)
20843 \_______________/ ^
20849 @ifset print-postscript-figures
20852 @center @image{lambda-1}
20856 @ifclear print-postscript-figures
20860 (multiply-by-seven 3)
20861 \_______________/ ^
20870 This expression returns 21.
20874 Similarly, we can write:
20876 @c lambda example diagram #2
20880 ((lambda (number) (* 7 number)) 3)
20881 \____________________________/ ^
20883 anonymous function argument
20887 @ifset print-postscript-figures
20890 @center @image{lambda-2}
20894 @ifclear print-postscript-figures
20898 ((lambda (number) (* 7 number)) 3)
20899 \____________________________/ ^
20901 anonymous function argument
20909 If we want to divide 100 by 50, we can write:
20911 @c lambda example diagram #3
20915 ((lambda (arg) (/ arg 50)) 100)
20916 \______________________/ \_/
20918 anonymous function argument
20922 @ifset print-postscript-figures
20925 @center @image{lambda-3}
20929 @ifclear print-postscript-figures
20933 ((lambda (arg) (/ arg 50)) 100)
20934 \______________________/ \_/
20936 anonymous function argument
20943 This expression returns 2. The 100 is passed to the function, which
20944 divides that number by 50.
20946 @xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs
20947 Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda
20948 expressions derive from the Lambda Calculus.
20951 @appendixsubsec The @code{mapcar} Function
20954 @code{mapcar} is a function that calls its first argument with each
20955 element of its second argument, in turn. The second argument must be
20958 The @samp{map} part of the name comes from the mathematical phrase,
20959 ``mapping over a domain'', meaning to apply a function to each of the
20960 elements in a domain. The mathematical phrase is based on the
20961 metaphor of a surveyor walking, one step at a time, over an area he is
20962 mapping. And @samp{car}, of course, comes from the Lisp notion of the
20971 (mapcar '1+ '(2 4 6))
20977 The function @code{1+} which adds one to its argument, is executed on
20978 @emph{each} element of the list, and a new list is returned.
20980 Contrast this with @code{apply}, which applies its first argument to
20982 (@xref{Readying a Graph, , Readying a Graph}, for a explanation of
20986 In the definition of @code{one-fiftieth}, the first argument is the
20987 anonymous function:
20990 (lambda (arg) (/ arg 50))
20994 and the second argument is @code{full-range}, which will be bound to
20995 @code{list-for-graph}.
20998 The whole expression looks like this:
21001 (mapcar (lambda (arg) (/ arg 50)) full-range))
21004 @xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs
21005 Lisp Reference Manual}, for more about @code{mapcar}.
21007 Using the @code{one-fiftieth} function, we can generate a list in
21008 which each element is one-fiftieth the size of the corresponding
21009 element in @code{list-for-graph}.
21013 (setq fiftieth-list-for-graph
21014 (one-fiftieth list-for-graph))
21019 The resulting list looks like this:
21023 (10 20 19 15 11 9 6 5 4 3 3 2 2
21024 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4)
21029 This, we are almost ready to print! (We also notice the loss of
21030 information: many of the higher ranges are 0, meaning that fewer than
21031 50 defuns had that many words or symbols---but not necessarily meaning
21032 that none had that many words or symbols.)
21035 @appendixsubsec Another Bug @dots{} Most Insidious
21036 @cindex Bug, most insidious type
21037 @cindex Insidious type of bug
21039 I said ``almost ready to print''! Of course, there is a bug in the
21040 @code{print-graph} function @dots{} It has a @code{vertical-step}
21041 option, but not a @code{horizontal-step} option. The
21042 @code{top-of-range} scale goes from 10 to 300 by tens. But the
21043 @code{print-graph} function will print only by ones.
21045 This is a classic example of what some consider the most insidious
21046 type of bug, the bug of omission. This is not the kind of bug you can
21047 find by studying the code, for it is not in the code; it is an omitted
21048 feature. Your best actions are to try your program early and often;
21049 and try to arrange, as much as you can, to write code that is easy to
21050 understand and easy to change. Try to be aware, whenever you can,
21051 that whatever you have written, @emph{will} be rewritten, if not soon,
21052 eventually. A hard maxim to follow.
21054 It is the @code{print-X-axis-numbered-line} function that needs the
21055 work; and then the @code{print-X-axis} and the @code{print-graph}
21056 functions need to be adapted. Not much needs to be done; there is one
21057 nicety: the numbers ought to line up under the tic marks. This takes
21061 Here is the corrected @code{print-X-axis-numbered-line}:
21065 (defun print-X-axis-numbered-line
21066 (number-of-X-tics X-axis-leading-spaces
21067 &optional horizontal-step)
21068 "Print line of X-axis numbers"
21069 (let ((number X-axis-label-spacing)
21070 (horizontal-step (or horizontal-step 1)))
21073 (insert X-axis-leading-spaces)
21074 ;; @r{Delete extra leading spaces.}
21077 (length (number-to-string horizontal-step)))))
21082 ;; @r{Insert white space.}
21084 X-axis-label-spacing)
21087 (number-to-string horizontal-step)))
21091 (* number horizontal-step))))
21094 ;; @r{Insert remaining numbers.}
21095 (setq number (+ number X-axis-label-spacing))
21096 (while (> number-of-X-tics 1)
21097 (insert (X-axis-element
21098 (* number horizontal-step)))
21099 (setq number (+ number X-axis-label-spacing))
21100 (setq number-of-X-tics (1- number-of-X-tics)))))
21105 If you are reading this in Info, you can see the new versions of
21106 @code{print-X-axis} @code{print-graph} and evaluate them. If you are
21107 reading this in a printed book, you can see the changed lines here
21108 (the full text is too much to print).
21113 (defun print-X-axis (numbers-list horizontal-step)
21115 (print-X-axis-numbered-line
21116 tic-number leading-spaces horizontal-step))
21124 &optional vertical-step horizontal-step)
21126 (print-X-axis numbers-list horizontal-step))
21134 (defun print-X-axis (numbers-list horizontal-step)
21135 "Print X axis labels to length of NUMBERS-LIST.
21136 Optionally, HORIZONTAL-STEP, a positive integer,
21137 specifies how much an X axis label increments for
21141 ;; Value of symbol-width and full-Y-label-width
21142 ;; are passed by print-graph.
21143 (let* ((leading-spaces
21144 (make-string full-Y-label-width ? ))
21145 ;; symbol-width @r{is provided by} graph-body-print
21146 (tic-width (* symbol-width X-axis-label-spacing))
21147 (X-length (length numbers-list))
21153 ;; @r{Make a string of blanks.}
21154 (- (* symbol-width X-axis-label-spacing)
21155 (length X-axis-tic-symbol))
21159 ;; @r{Concatenate blanks with tic symbol.}
21160 X-axis-tic-symbol))
21162 (if (zerop (% X-length tic-width))
21163 (/ X-length tic-width)
21164 (1+ (/ X-length tic-width)))))
21168 (print-X-axis-tic-line
21169 tic-number leading-spaces X-tic)
21171 (print-X-axis-numbered-line
21172 tic-number leading-spaces horizontal-step)))
21179 (numbers-list &optional vertical-step horizontal-step)
21180 "Print labeled bar graph of the NUMBERS-LIST.
21181 The numbers-list consists of the Y-axis values.
21185 Optionally, VERTICAL-STEP, a positive integer,
21186 specifies how much a Y axis label increments for
21187 each line. For example, a step of 5 means that
21188 each row is five units.
21192 Optionally, HORIZONTAL-STEP, a positive integer,
21193 specifies how much an X axis label increments for
21195 (let* ((symbol-width (length graph-blank))
21196 ;; @code{height} @r{is both the largest number}
21197 ;; @r{and the number with the most digits.}
21198 (height (apply 'max numbers-list))
21201 (height-of-top-line
21202 (if (zerop (% height Y-axis-label-spacing))
21205 (* (1+ (/ height Y-axis-label-spacing))
21206 Y-axis-label-spacing)))
21209 (vertical-step (or vertical-step 1))
21210 (full-Y-label-width
21214 (* height-of-top-line vertical-step))
21219 height-of-top-line full-Y-label-width vertical-step)
21221 numbers-list height-of-top-line symbol-width)
21222 (print-X-axis numbers-list horizontal-step)))
21229 Graphing Definitions Re-listed
21232 Here are all the graphing definitions in their final form:
21236 (defvar top-of-ranges
21239 110 120 130 140 150
21240 160 170 180 190 200
21241 210 220 230 240 250)
21242 "List specifying ranges for `defuns-per-range'.")
21246 (defvar graph-symbol "*"
21247 "String used as symbol in graph, usually an asterisk.")
21251 (defvar graph-blank " "
21252 "String used as blank in graph, usually a blank space.
21253 graph-blank must be the same number of columns wide
21258 (defvar Y-axis-tic " - "
21259 "String that follows number in a Y axis label.")
21263 (defvar Y-axis-label-spacing 5
21264 "Number of lines from one Y axis label to next.")
21268 (defvar X-axis-tic-symbol "|"
21269 "String to insert to point to a column in X axis.")
21273 (defvar X-axis-label-spacing
21274 (if (boundp 'graph-blank)
21275 (* 5 (length graph-blank)) 5)
21276 "Number of units from one X axis label to next.")
21282 (defun count-words-in-defun ()
21283 "Return the number of words and symbols in a defun."
21284 (beginning-of-defun)
21286 (end (save-excursion (end-of-defun) (point))))
21291 (and (< (point) end)
21293 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
21295 (setq count (1+ count)))
21302 (defun lengths-list-file (filename)
21303 "Return list of definitions' lengths within FILE.
21304 The returned list is a list of numbers.
21305 Each number is the number of words or
21306 symbols in one function definition."
21310 (message "Working on `%s' ... " filename)
21312 (let ((buffer (find-file-noselect filename))
21314 (set-buffer buffer)
21315 (setq buffer-read-only t)
21317 (goto-char (point-min))
21321 (while (re-search-forward "^(defun" nil t)
21323 (cons (count-words-in-defun) lengths-list)))
21324 (kill-buffer buffer)
21331 (defun lengths-list-many-files (list-of-files)
21332 "Return list of lengths of defuns in LIST-OF-FILES."
21333 (let (lengths-list)
21334 ;;; @r{true-or-false-test}
21335 (while list-of-files
21341 ;;; @r{Generate a lengths' list.}
21343 (expand-file-name (car list-of-files)))))
21344 ;;; @r{Make files' list shorter.}
21345 (setq list-of-files (cdr list-of-files)))
21346 ;;; @r{Return final value of lengths' list.}
21353 (defun defuns-per-range (sorted-lengths top-of-ranges)
21354 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
21355 (let ((top-of-range (car top-of-ranges))
21356 (number-within-range 0)
21357 defuns-per-range-list)
21362 (while top-of-ranges
21366 ;; @r{Need number for numeric test.}
21367 (car sorted-lengths)
21368 (< (car sorted-lengths) top-of-range))
21370 ;; @r{Count number of definitions within current range.}
21371 (setq number-within-range (1+ number-within-range))
21372 (setq sorted-lengths (cdr sorted-lengths)))
21376 ;; @r{Exit inner loop but remain within outer loop.}
21378 (setq defuns-per-range-list
21379 (cons number-within-range defuns-per-range-list))
21380 (setq number-within-range 0) ; @r{Reset count to zero.}
21382 ;; @r{Move to next range.}
21383 (setq top-of-ranges (cdr top-of-ranges))
21384 ;; @r{Specify next top of range value.}
21385 (setq top-of-range (car top-of-ranges)))
21389 ;; @r{Exit outer loop and count the number of defuns larger than}
21390 ;; @r{ the largest top-of-range value.}
21391 (setq defuns-per-range-list
21393 (length sorted-lengths)
21394 defuns-per-range-list))
21396 ;; @r{Return a list of the number of definitions within each range,}
21397 ;; @r{ smallest to largest.}
21398 (nreverse defuns-per-range-list)))
21404 (defun column-of-graph (max-graph-height actual-height)
21405 "Return list of MAX-GRAPH-HEIGHT strings;
21406 ACTUAL-HEIGHT are graph-symbols.
21407 The graph-symbols are contiguous entries at the end
21409 The list will be inserted as one column of a graph.
21410 The strings are either graph-blank or graph-symbol."
21414 (let ((insert-list nil)
21415 (number-of-top-blanks
21416 (- max-graph-height actual-height)))
21418 ;; @r{Fill in @code{graph-symbols}.}
21419 (while (> actual-height 0)
21420 (setq insert-list (cons graph-symbol insert-list))
21421 (setq actual-height (1- actual-height)))
21425 ;; @r{Fill in @code{graph-blanks}.}
21426 (while (> number-of-top-blanks 0)
21427 (setq insert-list (cons graph-blank insert-list))
21428 (setq number-of-top-blanks
21429 (1- number-of-top-blanks)))
21431 ;; @r{Return whole list.}
21438 (defun Y-axis-element (number full-Y-label-width)
21439 "Construct a NUMBERed label element.
21440 A numbered element looks like this ` 5 - ',
21441 and is padded as needed so all line up with
21442 the element for the largest number."
21445 (let* ((leading-spaces
21446 (- full-Y-label-width
21448 (concat (number-to-string number)
21453 (make-string leading-spaces ? )
21454 (number-to-string number)
21461 (defun print-Y-axis
21462 (height full-Y-label-width &optional vertical-step)
21463 "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH.
21464 Height must be the maximum height of the graph.
21465 Full width is the width of the highest label element.
21466 Optionally, print according to VERTICAL-STEP."
21469 ;; Value of height and full-Y-label-width
21470 ;; are passed by 'print-graph'.
21471 (let ((start (point)))
21473 (Y-axis-column height full-Y-label-width vertical-step))
21476 ;; @r{Place point ready for inserting graph.}
21478 ;; @r{Move point forward by value of} full-Y-label-width
21479 (forward-char full-Y-label-width)))
21485 (defun print-X-axis-tic-line
21486 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
21487 "Print ticks for X axis."
21488 (insert X-axis-leading-spaces)
21489 (insert X-axis-tic-symbol) ; @r{Under first column.}
21492 ;; @r{Insert second tic in the right spot.}
21495 (- (* symbol-width X-axis-label-spacing)
21496 ;; @r{Insert white space up to second tic symbol.}
21497 (* 2 (length X-axis-tic-symbol)))
21499 X-axis-tic-symbol))
21502 ;; @r{Insert remaining ticks.}
21503 (while (> number-of-X-tics 1)
21504 (insert X-axis-tic-element)
21505 (setq number-of-X-tics (1- number-of-X-tics))))
21511 (defun X-axis-element (number)
21512 "Construct a numbered X axis element."
21513 (let ((leading-spaces
21514 (- (* symbol-width X-axis-label-spacing)
21515 (length (number-to-string number)))))
21516 (concat (make-string leading-spaces ? )
21517 (number-to-string number))))
21523 (defun graph-body-print (numbers-list height symbol-width)
21524 "Print a bar graph of the NUMBERS-LIST.
21525 The numbers-list consists of the Y-axis values.
21526 HEIGHT is maximum height of graph.
21527 SYMBOL-WIDTH is number of each column."
21530 (let (from-position)
21531 (while numbers-list
21532 (setq from-position (point))
21534 (column-of-graph height (car numbers-list)))
21535 (goto-char from-position)
21536 (forward-char symbol-width)
21539 ;; @r{Draw graph column by column.}
21541 (setq numbers-list (cdr numbers-list)))
21542 ;; @r{Place point for X axis labels.}
21543 (forward-line height)
21550 (defun Y-axis-column
21551 (height width-of-label &optional vertical-step)
21552 "Construct list of labels for Y axis.
21553 HEIGHT is maximum height of graph.
21554 WIDTH-OF-LABEL is maximum width of label.
21557 VERTICAL-STEP, an option, is a positive integer
21558 that specifies how much a Y axis label increments
21559 for each line. For example, a step of 5 means
21560 that each line is five units of the graph."
21562 (number-per-line (or vertical-step 1)))
21565 (while (> height 1)
21566 (if (zerop (% height Y-axis-label-spacing))
21567 ;; @r{Insert label.}
21571 (* height number-per-line)
21576 ;; @r{Else, insert blanks.}
21579 (make-string width-of-label ? )
21581 (setq height (1- height)))
21584 ;; @r{Insert base line.}
21585 (setq Y-axis (cons (Y-axis-element
21586 (or vertical-step 1)
21589 (nreverse Y-axis)))
21595 (defun print-X-axis-numbered-line
21596 (number-of-X-tics X-axis-leading-spaces
21597 &optional horizontal-step)
21598 "Print line of X-axis numbers"
21599 (let ((number X-axis-label-spacing)
21600 (horizontal-step (or horizontal-step 1)))
21603 (insert X-axis-leading-spaces)
21605 (delete-char (- (1- (length (number-to-string horizontal-step)))))
21608 ;; @r{Insert white space up to next number.}
21609 (- (* symbol-width X-axis-label-spacing)
21610 (1- (length (number-to-string horizontal-step)))
21613 (number-to-string (* number horizontal-step))))
21616 ;; @r{Insert remaining numbers.}
21617 (setq number (+ number X-axis-label-spacing))
21618 (while (> number-of-X-tics 1)
21619 (insert (X-axis-element (* number horizontal-step)))
21620 (setq number (+ number X-axis-label-spacing))
21621 (setq number-of-X-tics (1- number-of-X-tics)))))
21627 (defun print-X-axis (numbers-list horizontal-step)
21628 "Print X axis labels to length of NUMBERS-LIST.
21629 Optionally, HORIZONTAL-STEP, a positive integer,
21630 specifies how much an X axis label increments for
21634 ;; Value of symbol-width and full-Y-label-width
21635 ;; are passed by 'print-graph'.
21636 (let* ((leading-spaces
21637 (make-string full-Y-label-width ? ))
21638 ;; symbol-width @r{is provided by} graph-body-print
21639 (tic-width (* symbol-width X-axis-label-spacing))
21640 (X-length (length numbers-list))
21646 ;; @r{Make a string of blanks.}
21647 (- (* symbol-width X-axis-label-spacing)
21648 (length X-axis-tic-symbol))
21652 ;; @r{Concatenate blanks with tic symbol.}
21653 X-axis-tic-symbol))
21655 (if (zerop (% X-length tic-width))
21656 (/ X-length tic-width)
21657 (1+ (/ X-length tic-width)))))
21661 (print-X-axis-tic-line
21662 tic-number leading-spaces X-tic)
21664 (print-X-axis-numbered-line
21665 tic-number leading-spaces horizontal-step)))
21671 (defun one-fiftieth (full-range)
21672 "Return list, each number of which is 1/50th previous."
21673 (mapcar (lambda (arg) (/ arg 50)) full-range))
21680 (numbers-list &optional vertical-step horizontal-step)
21681 "Print labeled bar graph of the NUMBERS-LIST.
21682 The numbers-list consists of the Y-axis values.
21686 Optionally, VERTICAL-STEP, a positive integer,
21687 specifies how much a Y axis label increments for
21688 each line. For example, a step of 5 means that
21689 each row is five units.
21693 Optionally, HORIZONTAL-STEP, a positive integer,
21694 specifies how much an X axis label increments for
21696 (let* ((symbol-width (length graph-blank))
21697 ;; @code{height} @r{is both the largest number}
21698 ;; @r{and the number with the most digits.}
21699 (height (apply 'max numbers-list))
21702 (height-of-top-line
21703 (if (zerop (% height Y-axis-label-spacing))
21706 (* (1+ (/ height Y-axis-label-spacing))
21707 Y-axis-label-spacing)))
21710 (vertical-step (or vertical-step 1))
21711 (full-Y-label-width
21715 (* height-of-top-line vertical-step))
21721 height-of-top-line full-Y-label-width vertical-step)
21723 numbers-list height-of-top-line symbol-width)
21724 (print-X-axis numbers-list horizontal-step)))
21731 @node Final printed graph
21732 @appendixsubsec The Printed Graph
21734 When made and installed, you can call the @code{print-graph} command
21740 (print-graph fiftieth-list-for-graph 50 10)
21770 50 - ***************** * *
21772 10 50 100 150 200 250 300 350
21779 The largest group of functions contain 10--19 words and symbols each.
21781 @node Free Software and Free Manuals
21782 @appendix Free Software and Free Manuals
21784 @strong{by Richard M. Stallman}
21787 The biggest deficiency in free operating systems is not in the
21788 software---it is the lack of good free manuals that we can include in
21789 these systems. Many of our most important programs do not come with
21790 full manuals. Documentation is an essential part of any software
21791 package; when an important free software package does not come with a
21792 free manual, that is a major gap. We have many such gaps today.
21794 Once upon a time, many years ago, I thought I would learn Perl. I got
21795 a copy of a free manual, but I found it hard to read. When I asked
21796 Perl users about alternatives, they told me that there were better
21797 introductory manuals---but those were not free.
21799 Why was this? The authors of the good manuals had written them for
21800 O'Reilly Associates, which published them with restrictive terms---no
21801 copying, no modification, source files not available---which exclude
21802 them from the free software community.
21804 That wasn't the first time this sort of thing has happened, and (to
21805 our community's great loss) it was far from the last. Proprietary
21806 manual publishers have enticed a great many authors to restrict their
21807 manuals since then. Many times I have heard a GNU user eagerly tell me
21808 about a manual that he is writing, with which he expects to help the
21809 GNU project---and then had my hopes dashed, as he proceeded to explain
21810 that he had signed a contract with a publisher that would restrict it
21811 so that we cannot use it.
21813 Given that writing good English is a rare skill among programmers, we
21814 can ill afford to lose manuals this way.
21816 Free documentation, like free software, is a matter of freedom, not
21817 price. The problem with these manuals was not that O'Reilly Associates
21818 charged a price for printed copies---that in itself is fine. The Free
21819 Software Foundation @uref{http://shop.fsf.org, sells printed copies} of
21820 free @uref{http://www.gnu.org/doc/doc.html, GNU manuals}, too.
21821 But GNU manuals are available in source code form, while these manuals
21822 are available only on paper. GNU manuals come with permission to copy
21823 and modify; the Perl manuals do not. These restrictions are the
21826 The criterion for a free manual is pretty much the same as for free
21827 software: it is a matter of giving all users certain
21828 freedoms. Redistribution (including commercial redistribution) must be
21829 permitted, so that the manual can accompany every copy of the program,
21830 on-line or on paper. Permission for modification is crucial too.
21832 As a general rule, I don't believe that it is essential for people to
21833 have permission to modify all sorts of articles and books. The issues
21834 for writings are not necessarily the same as those for software. For
21835 example, I don't think you or I are obliged to give permission to
21836 modify articles like this one, which describe our actions and our
21839 But there is a particular reason why the freedom to modify is crucial
21840 for documentation for free software. When people exercise their right
21841 to modify the software, and add or change its features, if they are
21842 conscientious they will change the manual too---so they can provide
21843 accurate and usable documentation with the modified program. A manual
21844 which forbids programmers to be conscientious and finish the job, or
21845 more precisely requires them to write a new manual from scratch if
21846 they change the program, does not fill our community's needs.
21848 While a blanket prohibition on modification is unacceptable, some
21849 kinds of limits on the method of modification pose no problem. For
21850 example, requirements to preserve the original author's copyright
21851 notice, the distribution terms, or the list of authors, are ok. It is
21852 also no problem to require modified versions to include notice that
21853 they were modified, even to have entire sections that may not be
21854 deleted or changed, as long as these sections deal with nontechnical
21855 topics. (Some GNU manuals have them.)
21857 These kinds of restrictions are not a problem because, as a practical
21858 matter, they don't stop the conscientious programmer from adapting the
21859 manual to fit the modified program. In other words, they don't block
21860 the free software community from making full use of the manual.
21862 However, it must be possible to modify all the technical content of
21863 the manual, and then distribute the result in all the usual media,
21864 through all the usual channels; otherwise, the restrictions do block
21865 the community, the manual is not free, and so we need another manual.
21867 Unfortunately, it is often hard to find someone to write another
21868 manual when a proprietary manual exists. The obstacle is that many
21869 users think that a proprietary manual is good enough---so they don't
21870 see the need to write a free manual. They do not see that the free
21871 operating system has a gap that needs filling.
21873 Why do users think that proprietary manuals are good enough? Some have
21874 not considered the issue. I hope this article will do something to
21877 Other users consider proprietary manuals acceptable for the same
21878 reason so many people consider proprietary software acceptable: they
21879 judge in purely practical terms, not using freedom as a
21880 criterion. These people are entitled to their opinions, but since
21881 those opinions spring from values which do not include freedom, they
21882 are no guide for those of us who do value freedom.
21884 Please spread the word about this issue. We continue to lose manuals
21885 to proprietary publishing. If we spread the word that proprietary
21886 manuals are not sufficient, perhaps the next person who wants to help
21887 GNU by writing documentation will realize, before it is too late, that
21888 he must above all make it free.
21890 We can also encourage commercial publishers to sell free, copylefted
21891 manuals instead of proprietary ones. One way you can help this is to
21892 check the distribution terms of a manual before you buy it, and prefer
21893 copylefted manuals to non-copylefted ones.
21897 Note: The Free Software Foundation maintains a page on its Web site
21898 that lists free books available from other publishers:@*
21899 @uref{http://www.gnu.org/doc/other-free-books.html}
21901 @node GNU Free Documentation License
21902 @appendix GNU Free Documentation License
21904 @cindex FDL, GNU Free Documentation License
21905 @include doclicense.texi
21911 MENU ENTRY: NODE NAME.
21917 @c Place biographical information on right-hand (verso) page
21920 \par\vfill\supereject
21922 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
21923 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
21926 % \par\vfill\supereject
21927 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
21928 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
21929 %\page\hbox{}%\page
21930 %\page\hbox{}%\page
21937 @c ================ Biographical information ================
21941 @center About the Author
21946 @node About the Author
21947 @unnumbered About the Author
21951 Robert J. Chassell has worked with GNU Emacs since 1985. He writes
21952 and edits, teaches Emacs and Emacs Lisp, and speaks throughout the
21953 world on software freedom. Chassell was a founding Director and
21954 Treasurer of the Free Software Foundation, Inc. He is co-author of
21955 the @cite{Texinfo} manual, and has edited more than a dozen other
21956 books. He graduated from Cambridge University, in England. He has an
21957 abiding interest in social and economic history and flies his own
21964 @c @c Prevent page number on blank verso, so eject it first.
21966 @c \par\vfill\supereject
21971 @c @evenheading @thispage @| @| @thistitle
21972 @c @oddheading @| @| @thispage