1 \input ../man/texinfo @c -*-texinfo-*-
2 @c \input texinfo @c -*-texinfo-*-
3 @c change to \input texinfo if building on own.
4 @comment %**start of header
5 @setfilename ../info/eintr
6 @c setfilename emacs-lisp-intro.info
7 @c sethtmlfilename emacs-lisp-intro.html
8 @settitle Programming in Emacs Lisp
11 @setchapternewpage odd
15 @c <<<< For hard copy printing, this file is now
16 @c set for smallbook, which works for all sizes
17 @c of paper, and with Postscript figures >>>>
20 @set print-postscript-figures
22 @c clear print-postscript-figures
25 @comment %**end of header
27 @set edition-number 3.01
28 @set update-date 2006 Oct 31
31 ## Summary of shell commands to create various output formats:
33 pushd /usr/local/src/emacs/lispintro/
37 # makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
38 makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi
40 ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/u/intro/emacs-lisp-intro.info"))
43 texi2dvi emacs-lisp-intro.texi
45 ## View DVI output; see below also
46 # xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi &
49 makeinfo --html --no-split --verbose emacs-lisp-intro.texi
52 makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
53 --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi
56 makeinfo --docbook --no-split --paragraph-indent=0 \
57 --verbose emacs-lisp-intro.texi
60 makeinfo --xml --no-split --paragraph-indent=0 \
61 --verbose emacs-lisp-intro.texi
65 #### (You must be in the same directory as the viewed file.)
68 xdvi emacs-lisp-intro.dvi &
71 galeon emacs-lisp-intro.html
73 ## View Info output with standalone reader
74 info emacs-lisp-intro.info
81 mtusb # mount -v -t ext3 /dev/sda /mnt
82 cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi
83 umtusb # umount -v /mnt
88 @c ================ Included Figures ================
90 @c Set print-postscript-figures if you print PostScript figures.
91 @c If you clear this, the ten figures will be printed as ASCII diagrams.
92 @c (This is not relevant to Info, since Info only handles ASCII.)
93 @c Your site may require editing changes to print PostScript; in this
94 @c case, search for `print-postscript-figures' and make appropriate changes.
96 @c ================ How to Create an Info file ================
98 @c If you have `makeinfo' installed, run the following command
100 @c makeinfo emacs-lisp-intro.texi
102 @c or, if you want a single, large Info file, and no paragraph indents:
103 @c makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
105 @c After creating the Info file, edit your Info `dir' file, if the
106 @c `dircategory' section below does not enable your system to
107 @c install the manual automatically.
108 @c (The `dir' file is often in the `/usr/local/info/' directory.)
110 @c ================ How to Create an HTML file ================
112 @c To convert to HTML format
113 @c makeinfo --html --no-split --verbose emacs-lisp-intro.texi
115 @c ================ How to Print a Book in Various Sizes ================
117 @c This book can be printed in any of three different sizes.
118 @c In the above header, set @-commands appropriately.
128 @c European A4 size paper:
133 @c ================ How to Typeset and Print ================
135 @c If you do not include PostScript figures, run either of the
136 @c following command sequences, or similar commands suited to your
139 @c texi2dvi emacs-lisp-intro.texi
140 @c lpr -d emacs-lisp-intro.dvi
144 @c tex emacs-lisp-intro.texi
145 @c texindex emacs-lisp-intro.??
146 @c tex emacs-lisp-intro.texi
147 @c lpr -d emacs-lisp-intro.dvi
149 @c If you include the PostScript figures, and you have old software,
150 @c you may need to convert the .dvi file to a .ps file before
151 @c printing. Run either of the following command sequences, or one
154 @c dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
158 @c postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
161 @c (Note: if you edit the book so as to change the length of the
162 @c table of contents, you may have to change the value of `pageno' below.)
164 @c ================ End of Formatting Sections ================
166 @c For next or subsequent edition:
167 @c create function using with-output-to-temp-buffer
168 @c create a major mode, with keymaps
169 @c run an asynchronous process, like grep or diff
171 @c For 8.5 by 11 inch format: do not use such a small amount of
172 @c whitespace between paragraphs as smallbook format
175 \global\parskip 6pt plus 1pt
179 @c For all sized formats: print within-book cross
180 @c reference with ``...'' rather than [...]
182 @c This works with the texinfo.tex file, version 2003-05-04.08,
183 @c in the Texinfo version 4.6 of the 2003 Jun 13 distribution.
186 \global\def\xrefprintnodename#1{\unskip, ``#1''}
187 % \global\def\xrefprintnodename#1{, ``#1''}
190 @c ----------------------------------------------------
194 * Emacs Lisp Intro: (eintr).
195 A simple introduction to Emacs Lisp programming.
199 This is an @cite{Introduction to Programming in Emacs Lisp}, for
200 people who are not programmers.
202 Edition @value{edition-number}, @value{update-date}
204 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001,
205 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
211 GNU Press, @hfill @uref{http://www.gnupress.org}@*
212 a division of the @hfill General: @email{press@@gnu.org}@*
213 Free Software Foundation, Inc. @hfill Orders:@w{ } @email{sales@@gnu.org}@*
214 51 Franklin Street, Fifth Floor @hfill Tel: +1 (617) 542-5942@*
215 Boston, MA 02110-1301 USA @hfill Fax: +1 (617) 542-2652@*
222 GNU Press, Website: http://www.gnupress.org
223 a division of the General: press@@gnu.org
224 Free Software Foundation, Inc. Orders: sales@@gnu.org
225 51 Franklin Street, Fifth Floor Tel: +1 (617) 542-5942
226 Boston, MA 02110-1301 USA Fax: +1 (617) 542-2652
231 @c Printed copies are available for $30 each.@*
234 Permission is granted to copy, distribute and/or modify this document
235 under the terms of the GNU Free Documentation License, Version 1.2 or
236 any later version published by the Free Software Foundation; there
237 being no Invariant Section, with the Front-Cover Texts being ``A GNU
238 Manual'', and with the Back-Cover Texts as in (a) below. A copy of
239 the license is included in the section entitled ``GNU Free
240 Documentation License''.
242 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
243 modify this GNU Manual, like GNU software. Copies published by the
244 Free Software Foundation raise funds for GNU development.''
247 @c half title; two lines here, so do not use `shorttitlepage'
250 \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}%
252 {\begingroup\hbox{}\vskip 0.25in \chaprm%
253 \centerline{Programming in Emacs Lisp}%
254 \endgroup\page\hbox{}\page}
259 @center @titlefont{An Introduction to}
261 @center @titlefont{Programming in Emacs Lisp}
263 @center Revised Third Edition
265 @center by Robert J. Chassell
268 @vskip 0pt plus 1filll
274 @evenheading @thispage @| @| @thischapter
275 @oddheading @thissection @| @| @thispage
279 @c Keep T.O.C. short by tightening up for largebook
282 \global\parskip 2pt plus 1pt
283 \global\advance\baselineskip by -1pt
292 @node Top, Preface, (dir), (dir)
293 @top An Introduction to Programming in Emacs Lisp
297 This master menu first lists each chapter and index; then it lists
298 every node in every chapter.
301 @c >>>> Set pageno appropriately <<<<
303 @c The first page of the Preface is a roman numeral; it is the first
304 @c right handed page after the Table of Contents; hence the following
305 @c setting must be for an odd negative number.
312 * Preface:: What to look for.
313 * List Processing:: What is Lisp?
314 * Practicing Evaluation:: Running several programs.
315 * Writing Defuns:: How to write function definitions.
316 * Buffer Walk Through:: Exploring a few buffer-related functions.
317 * More Complex:: A few, even more complex functions.
318 * Narrowing & Widening:: Restricting your and Emacs attention to
320 * car cdr & cons:: Fundamental functions in Lisp.
321 * Cutting & Storing Text:: Removing text and saving it.
322 * List Implementation:: How lists are implemented in the computer.
323 * Yanking:: Pasting stored text.
324 * Loops & Recursion:: How to repeat a process.
325 * Regexp Search:: Regular expression searches.
326 * Counting Words:: A review of repetition and regexps.
327 * Words in a defun:: Counting words in a @code{defun}.
328 * Readying a Graph:: A prototype graph printing function.
329 * Emacs Initialization:: How to write a @file{.emacs} file.
330 * Debugging:: How to run the Emacs Lisp debuggers.
331 * Conclusion:: Now you have the basics.
332 * the-the:: An appendix: how to find reduplicated words.
333 * Kill Ring:: An appendix: how the kill ring works.
334 * Full Graph:: How to create a graph with labelled axes.
335 * Free Software and Free Manuals::
336 * GNU Free Documentation License::
341 --- The Detailed Node Listing ---
345 * Why:: Why learn Emacs Lisp?
346 * On Reading this Text:: Read, gain familiarity, pick up habits....
347 * Who You Are:: For whom this is written.
349 * Note for Novices:: You can read this as a novice.
354 * Lisp Lists:: What are lists?
355 * Run a Program:: Any list in Lisp is a program ready to run.
356 * Making Errors:: Generating an error message.
357 * Names & Definitions:: Names of symbols and function definitions.
358 * Lisp Interpreter:: What the Lisp interpreter does.
359 * Evaluation:: Running a program.
360 * Variables:: Returning a value from a variable.
361 * Arguments:: Passing information to a function.
362 * set & setq:: Setting the value of a variable.
363 * Summary:: The major points.
364 * Error Message Exercises::
368 * Numbers Lists:: List have numbers, other lists, in them.
369 * Lisp Atoms:: Elemental entities.
370 * Whitespace in Lists:: Formatting lists to be readable.
371 * Typing Lists:: How GNU Emacs helps you type lists.
375 * Complications:: Variables, Special forms, Lists within.
376 * Byte Compiling:: Specially processing code for speed.
380 * Evaluating Inner Lists:: Lists within lists...
384 * fill-column Example::
385 * Void Function:: The error message for a symbol
387 * Void Variable:: The error message for a symbol without a value.
391 * Data types:: Types of data passed to a function.
392 * Args as Variable or List:: An argument can be the value
393 of a variable or list.
394 * Variable Number of Arguments:: Some functions may take a
395 variable number of arguments.
396 * Wrong Type of Argument:: Passing an argument of the wrong type
398 * message:: A useful function for sending messages.
400 Setting the Value of a Variable
402 * Using set:: Setting values.
403 * Using setq:: Setting a quoted value.
404 * Counting:: Using @code{setq} to count.
406 Practicing Evaluation
408 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
410 * Buffer Names:: Buffers and files are different.
411 * Getting Buffers:: Getting a buffer itself, not merely its name.
412 * Switching Buffers:: How to change to another buffer.
413 * Buffer Size & Locations:: Where point is located and the size of
415 * Evaluation Exercise::
417 How To Write Function Definitions
419 * Primitive Functions::
420 * defun:: The @code{defun} special form.
421 * Install:: Install a function definition.
422 * Interactive:: Making a function interactive.
423 * Interactive Options:: Different options for @code{interactive}.
424 * Permanent Installation:: Installing code permanently.
425 * let:: Creating and initializing local variables.
427 * else:: If--then--else expressions.
428 * Truth & Falsehood:: What Lisp considers false and true.
429 * save-excursion:: Keeping track of point, mark, and buffer.
433 Install a Function Definition
435 * Effect of installation::
436 * Change a defun:: How to change a function definition.
438 Make a Function Interactive
440 * Interactive multiply-by-seven:: An overview.
441 * multiply-by-seven in detail:: The interactive version.
445 * Prevent confusion::
446 * Parts of let Expression::
447 * Sample let Expression::
448 * Uninitialized let Variables::
450 The @code{if} Special Form
452 * if in more detail::
453 * type-of-animal in detail:: An example of an @code{if} expression.
455 Truth and Falsehood in Emacs Lisp
457 * nil explained:: @code{nil} has two meanings.
459 @code{save-excursion}
461 * Point and mark:: A review of various locations.
462 * Template for save-excursion::
464 A Few Buffer--Related Functions
466 * Finding More:: How to find more information.
467 * simplified-beginning-of-buffer:: Shows @code{goto-char},
468 @code{point-min}, and @code{push-mark}.
469 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
470 * append-to-buffer:: Uses @code{save-excursion} and
471 @code{insert-buffer-substring}.
472 * Buffer Related Review:: Review.
475 The Definition of @code{mark-whole-buffer}
477 * mark-whole-buffer overview::
478 * Body of mark-whole-buffer:: Only three lines of code.
480 The Definition of @code{append-to-buffer}
482 * append-to-buffer overview::
483 * append interactive:: A two part interactive expression.
484 * append-to-buffer body:: Incorporates a @code{let} expression.
485 * append save-excursion:: How the @code{save-excursion} works.
487 A Few More Complex Functions
489 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
490 * insert-buffer:: Read-only, and with @code{or}.
491 * beginning-of-buffer:: Shows @code{goto-char},
492 @code{point-min}, and @code{push-mark}.
493 * Second Buffer Related Review::
494 * optional Exercise::
496 The Definition of @code{insert-buffer}
498 * insert-buffer code::
499 * insert-buffer interactive:: When you can read, but not write.
500 * insert-buffer body:: The body has an @code{or} and a @code{let}.
501 * if & or:: Using an @code{if} instead of an @code{or}.
502 * Insert or:: How the @code{or} expression works.
503 * Insert let:: Two @code{save-excursion} expressions.
504 * New insert-buffer::
506 The Interactive Expression in @code{insert-buffer}
508 * Read-only buffer:: When a buffer cannot be modified.
509 * b for interactive:: An existing buffer or else its name.
511 Complete Definition of @code{beginning-of-buffer}
513 * Optional Arguments::
514 * beginning-of-buffer opt arg:: Example with optional argument.
515 * beginning-of-buffer complete::
517 @code{beginning-of-buffer} with an Argument
519 * Disentangle beginning-of-buffer::
520 * Large buffer case::
521 * Small buffer case::
523 Narrowing and Widening
525 * Narrowing advantages:: The advantages of narrowing
526 * save-restriction:: The @code{save-restriction} special form.
527 * what-line:: The number of the line that point is on.
530 @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
532 * Strange Names:: An historical aside: why the strange names?
533 * car & cdr:: Functions for extracting part of a list.
534 * cons:: Constructing a list.
535 * nthcdr:: Calling @code{cdr} repeatedly.
537 * setcar:: Changing the first element of a list.
538 * setcdr:: Changing the rest of a list.
544 * length:: How to find the length of a list.
546 Cutting and Storing Text
548 * Storing Text:: Text is stored in a list.
549 * zap-to-char:: Cutting out text up to a character.
550 * kill-region:: Cutting text out of a region.
551 * copy-region-as-kill:: A definition for copying text.
552 * Digression into C:: Minor note on C programming language macros.
553 * defvar:: How to give a variable an initial value.
554 * cons & search-fwd Review::
559 * Complete zap-to-char:: The complete implementation.
560 * zap-to-char interactive:: A three part interactive expression.
561 * zap-to-char body:: A short overview.
562 * search-forward:: How to search for a string.
563 * progn:: The @code{progn} special form.
564 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
568 * Complete kill-region:: The function definition.
569 * condition-case:: Dealing with a problem.
572 @code{copy-region-as-kill}
574 * Complete copy-region-as-kill:: The complete function definition.
575 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
577 The Body of @code{copy-region-as-kill}
579 * last-command & this-command::
580 * kill-append function::
581 * kill-new function::
583 Initializing a Variable with @code{defvar}
585 * See variable current value::
586 * defvar and asterisk::
588 How Lists are Implemented
591 * Symbols as Chest:: Exploring a powerful metaphor.
596 * Kill Ring Overview::
597 * kill-ring-yank-pointer:: The kill ring is a list.
598 * yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
602 * while:: Causing a stretch of code to repeat.
604 * Recursion:: Causing a function to call itself.
609 * Looping with while:: Repeat so long as test returns true.
610 * Loop Example:: A @code{while} loop that uses a list.
611 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
612 * Incrementing Loop:: A loop with an incrementing counter.
613 * Decrementing Loop:: A loop with a decrementing counter.
615 A Loop with an Incrementing Counter
617 * Incrementing Example:: Counting pebbles in a triangle.
618 * Inc Example parts:: The parts of the function definition.
619 * Inc Example altogether:: Putting the function definition together.
621 Loop with a Decrementing Counter
623 * Decrementing Example:: More pebbles on the beach.
624 * Dec Example parts:: The parts of the function definition.
625 * Dec Example altogether:: Putting the function definition together.
627 Save your time: @code{dolist} and @code{dotimes}
634 * Building Robots:: Same model, different serial number ...
635 * Recursive Definition Parts:: Walk until you stop ...
636 * Recursion with list:: Using a list as the test whether to recurse.
637 * Recursive triangle function::
638 * Recursion with cond::
639 * Recursive Patterns:: Often used templates.
640 * No Deferment:: Don't store up work ...
641 * No deferment solution::
643 Recursion in Place of a Counter
645 * Recursive Example arg of 1 or 2::
646 * Recursive Example arg of 3 or 4::
654 Regular Expression Searches
656 * sentence-end:: The regular expression for @code{sentence-end}.
657 * re-search-forward:: Very similar to @code{search-forward}.
658 * forward-sentence:: A straightforward example of regexp search.
659 * forward-paragraph:: A somewhat complex example.
660 * etags:: How to create your own @file{TAGS} table.
662 * re-search Exercises::
664 @code{forward-sentence}
666 * Complete forward-sentence::
667 * fwd-sentence while loops:: Two @code{while} loops.
668 * fwd-sentence re-search:: A regular expression search.
670 @code{forward-paragraph}: a Goldmine of Functions
672 * forward-paragraph in brief:: Key parts of the function definition.
673 * fwd-para let:: The @code{let*} expression.
674 * fwd-para while:: The forward motion @code{while} loop.
676 Counting: Repetition and Regexps
679 * count-words-region:: Use a regexp, but find a problem.
680 * recursive-count-words:: Start with case of no words in region.
681 * Counting Exercise::
683 The @code{count-words-region} Function
685 * Design count-words-region:: The definition using a @code{while} loop.
686 * Whitespace Bug:: The Whitespace Bug in @code{count-words-region}.
688 Counting Words in a @code{defun}
690 * Divide and Conquer::
691 * Words and Symbols:: What to count?
692 * Syntax:: What constitutes a word or symbol?
693 * count-words-in-defun:: Very like @code{count-words}.
694 * Several defuns:: Counting several defuns in a file.
695 * Find a File:: Do you want to look at a file?
696 * lengths-list-file:: A list of the lengths of many definitions.
697 * Several files:: Counting in definitions in different files.
698 * Several files recursively:: Recursively counting in different files.
699 * Prepare the data:: Prepare the data for display in a graph.
701 Count Words in @code{defuns} in Different Files
703 * lengths-list-many-files:: Return a list of the lengths of defuns.
704 * append:: Attach one list to another.
706 Prepare the Data for Display in a Graph
708 * Sorting:: Sorting lists.
709 * Files List:: Making a list of files.
710 * Counting function definitions::
714 * Columns of a graph::
715 * graph-body-print:: How to print the body of a graph.
716 * recursive-graph-body-print::
718 * Line Graph Exercise::
720 Your @file{.emacs} File
722 * Default Configuration::
723 * Site-wide Init:: You can write site-wide init files.
724 * defcustom:: Emacs will write code for you.
725 * Beginning a .emacs File:: How to write a @code{.emacs file}.
726 * Text and Auto-fill:: Automatically wrap lines.
727 * Mail Aliases:: Use abbreviations for email addresses.
728 * Indent Tabs Mode:: Don't use tabs with @TeX{}
729 * Keybindings:: Create some personal keybindings.
730 * Keymaps:: More about key binding.
731 * Loading Files:: Load (i.e., evaluate) files automatically.
732 * Autoload:: Make functions available.
733 * Simple Extension:: Define a function; bind it to a key.
734 * X11 Colors:: Colors in X.
736 * Mode Line:: How to customize your mode line.
740 * debug:: How to use the built-in debugger.
741 * debug-on-entry:: Start debugging when you call a function.
742 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
743 * edebug:: How to use Edebug, a source level debugger.
744 * Debugging Exercises::
746 Handling the Kill Ring
749 * yank:: Paste a copy of a clipped element.
750 * yank-pop:: Insert element pointed to.
753 The @code{current-kill} Function
755 * Understanding current-kill::
757 @code{current-kill} in Outline
759 * Digression concerning error:: How to mislead humans, but not computers.
760 * Determining the Element::
762 A Graph with Labelled Axes
765 * print-graph Varlist:: @code{let} expression in @code{print-graph}.
766 * print-Y-axis:: Print a label for the vertical axis.
767 * print-X-axis:: Print a horizontal label.
768 * Print Whole Graph:: The function to print a complete graph.
770 The @code{print-Y-axis} Function
772 * Height of label:: What height for the Y axis?
773 * Compute a Remainder:: How to compute the remainder of a division.
774 * Y Axis Element:: Construct a line for the Y axis.
775 * Y-axis-column:: Generate a list of Y axis labels.
776 * print-Y-axis Penultimate:: A not quite final version.
778 The @code{print-X-axis} Function
780 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
781 * X Axis Tic Marks:: Create tic marks for the horizontal axis.
783 Printing the Whole Graph
785 * The final version:: A few changes.
786 * Test print-graph:: Run a short test.
787 * Graphing words in defuns:: Executing the final code.
788 * lambda:: How to write an anonymous function.
789 * mapcar:: Apply a function to elements of a list.
790 * Another Bug:: Yet another bug @dots{} most insidious.
791 * Final printed graph:: The graph itself!
796 @node Preface, List Processing, Top, Top
797 @comment node-name, next, previous, up
800 Most of the GNU Emacs integrated environment is written in the programming
801 language called Emacs Lisp. The code written in this programming
802 language is the software---the sets of instructions---that tell the
803 computer what to do when you give it commands. Emacs is designed so
804 that you can write new code in Emacs Lisp and easily install it as an
805 extension to the editor.
807 (GNU Emacs is sometimes called an ``extensible editor'', but it does
808 much more than provide editing capabilities. It is better to refer to
809 Emacs as an ``extensible computing environment''. However, that
810 phrase is quite a mouthful. It is easier to refer to Emacs simply as
811 an editor. Moreover, everything you do in Emacs---find the Mayan date
812 and phases of the moon, simplify polynomials, debug code, manage
813 files, read letters, write books---all these activities are kinds of
814 editing in the most general sense of the word.)
818 * On Reading this Text::
825 @node Why, On Reading this Text, Preface, Preface
827 @unnumberedsec Why Study Emacs Lisp?
830 Although Emacs Lisp is usually thought of in association only with Emacs,
831 it is a full computer programming language. You can use Emacs Lisp as
832 you would any other programming language.
834 Perhaps you want to understand programming; perhaps you want to extend
835 Emacs; or perhaps you want to become a programmer. This introduction to
836 Emacs Lisp is designed to get you started: to guide you in learning the
837 fundamentals of programming, and more importantly, to show you how you
838 can teach yourself to go further.
840 @node On Reading this Text, Who You Are, Why, Preface
841 @comment node-name, next, previous, up
842 @unnumberedsec On Reading this Text
844 All through this document, you will see little sample programs you can
845 run inside of Emacs. If you read this document in Info inside of GNU
846 Emacs, you can run the programs as they appear. (This is easy to do and
847 is explained when the examples are presented.) Alternatively, you can
848 read this introduction as a printed book while sitting beside a computer
849 running Emacs. (This is what I like to do; I like printed books.) If
850 you don't have a running Emacs beside you, you can still read this book,
851 but in this case, it is best to treat it as a novel or as a travel guide
852 to a country not yet visited: interesting, but not the same as being
855 Much of this introduction is dedicated to walk-throughs or guided tours
856 of code used in GNU Emacs. These tours are designed for two purposes:
857 first, to give you familiarity with real, working code (code you use
858 every day); and, second, to give you familiarity with the way Emacs
859 works. It is interesting to see how a working environment is
862 hope that you will pick up the habit of browsing through source code.
863 You can learn from it and mine it for ideas. Having GNU Emacs is like
864 having a dragon's cave of treasures.
866 In addition to learning about Emacs as an editor and Emacs Lisp as a
867 programming language, the examples and guided tours will give you an
868 opportunity to get acquainted with Emacs as a Lisp programming
869 environment. GNU Emacs supports programming and provides tools that
870 you will want to become comfortable using, such as @kbd{M-.} (the key
871 which invokes the @code{find-tag} command). You will also learn about
872 buffers and other objects that are part of the environment.
873 Learning about these features of Emacs is like learning new routes
874 around your home town.
877 In addition, I have written several programs as extended examples.
878 Although these are examples, the programs are real. I use them.
879 Other people use them. You may use them. Beyond the fragments of
880 programs used for illustrations, there is very little in here that is
881 `just for teaching purposes'; what you see is used. This is a great
882 advantage of Emacs Lisp: it is easy to learn to use it for work.
885 Finally, I hope to convey some of the skills for using Emacs to
886 learn aspects of programming that you don't know. You can often use
887 Emacs to help you understand what puzzles you or to find out how to do
888 something new. This self-reliance is not only a pleasure, but an
891 @node Who You Are, Lisp History, On Reading this Text, Preface
892 @comment node-name, next, previous, up
893 @unnumberedsec For Whom This is Written
895 This text is written as an elementary introduction for people who are
896 not programmers. If you are a programmer, you may not be satisfied with
897 this primer. The reason is that you may have become expert at reading
898 reference manuals and be put off by the way this text is organized.
900 An expert programmer who reviewed this text said to me:
903 @i{I prefer to learn from reference manuals. I ``dive into'' each
904 paragraph, and ``come up for air'' between paragraphs.}
906 @i{When I get to the end of a paragraph, I assume that that subject is
907 done, finished, that I know everything I need (with the
908 possible exception of the case when the next paragraph starts talking
909 about it in more detail). I expect that a well written reference manual
910 will not have a lot of redundancy, and that it will have excellent
911 pointers to the (one) place where the information I want is.}
914 This introduction is not written for this person!
916 Firstly, I try to say everything at least three times: first, to
917 introduce it; second, to show it in context; and third, to show it in a
918 different context, or to review it.
920 Secondly, I hardly ever put all the information about a subject in one
921 place, much less in one paragraph. To my way of thinking, that imposes
922 too heavy a burden on the reader. Instead I try to explain only what
923 you need to know at the time. (Sometimes I include a little extra
924 information so you won't be surprised later when the additional
925 information is formally introduced.)
927 When you read this text, you are not expected to learn everything the
928 first time. Frequently, you need only make, as it were, a `nodding
929 acquaintance' with some of the items mentioned. My hope is that I have
930 structured the text and given you enough hints that you will be alert to
931 what is important, and concentrate on it.
933 You will need to ``dive into'' some paragraphs; there is no other way
934 to read them. But I have tried to keep down the number of such
935 paragraphs. This book is intended as an approachable hill, rather than
936 as a daunting mountain.
938 This introduction to @cite{Programming in Emacs Lisp} has a companion
941 @cite{The GNU Emacs Lisp Reference Manual}.
944 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
945 Emacs Lisp Reference Manual}.
947 The reference manual has more detail than this introduction. In the
948 reference manual, all the information about one topic is concentrated
949 in one place. You should turn to it if you are like the programmer
950 quoted above. And, of course, after you have read this
951 @cite{Introduction}, you will find the @cite{Reference Manual} useful
952 when you are writing your own programs.
954 @node Lisp History, Note for Novices, Who You Are, Preface
955 @unnumberedsec Lisp History
958 Lisp was first developed in the late 1950s at the Massachusetts
959 Institute of Technology for research in artificial intelligence. The
960 great power of the Lisp language makes it superior for other purposes as
961 well, such as writing editor commands and integrated environments.
965 GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT
966 in the 1960s. It is somewhat inspired by Common Lisp, which became a
967 standard in the 1980s. However, Emacs Lisp is much simpler than Common
968 Lisp. (The standard Emacs distribution contains an optional extensions
969 file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.)
971 @node Note for Novices, Thank You, Lisp History, Preface
972 @comment node-name, next, previous, up
973 @unnumberedsec A Note for Novices
975 If you don't know GNU Emacs, you can still read this document
976 profitably. However, I recommend you learn Emacs, if only to learn to
977 move around your computer screen. You can teach yourself how to use
978 Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This
979 means you press and release the @key{CTRL} key and the @kbd{h} at the
980 same time, and then press and release @kbd{t}.)
982 Also, I often refer to one of Emacs' standard commands by listing the
983 keys which you press to invoke the command and then giving the name of
984 the command in parentheses, like this: @kbd{M-C-\}
985 (@code{indent-region}). What this means is that the
986 @code{indent-region} command is customarily invoked by typing
987 @kbd{M-C-\}. (You can, if you wish, change the keys that are typed to
988 invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, ,
989 Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your
990 @key{META} key, @key{CTRL} key and @key{\} key all at the same time.
991 (On many modern keyboards the @key{META} key is labelled
993 Sometimes a combination like this is called a keychord, since it is
994 similar to the way you play a chord on a piano. If your keyboard does
995 not have a @key{META} key, the @key{ESC} key prefix is used in place
996 of it. In this case, @kbd{M-C-\} means that you press and release your
997 @key{ESC} key and then type the @key{CTRL} key and the @key{\} key at
998 the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key
999 along with the key that is labelled @key{ALT} and, at the same time,
1000 press the @key{\} key.
1002 In addition to typing a lone keychord, you can prefix what you type
1003 with @kbd{C-u}, which is called the `universal argument'. The
1004 @kbd{C-u} keychord passes an argument to the subsequent command.
1005 Thus, to indent a region of plain text by 6 spaces, mark the region,
1006 and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number,
1007 Emacs either passes the number 4 to the command or otherwise runs the
1008 command differently than it would otherwise.) @xref{Arguments, ,
1009 Numeric Arguments, emacs, The GNU Emacs Manual}.
1011 If you are reading this in Info using GNU Emacs, you can read through
1012 this whole document just by pressing the space bar, @key{SPC}.
1013 (To learn about Info, type @kbd{C-h i} and then select Info.)
1015 A note on terminology: when I use the word Lisp alone, I often am
1016 referring to the various dialects of Lisp in general, but when I speak
1017 of Emacs Lisp, I am referring to GNU Emacs Lisp in particular.
1019 @node Thank You, , Note for Novices, Preface
1020 @comment node-name, next, previous, up
1021 @unnumberedsec Thank You
1023 My thanks to all who helped me with this book. My especial thanks to
1024 @r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland
1025 McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@:
1026 Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both
1027 @w{Philip Johnson} and @w{David Stampe} for their patient
1028 encouragement. My mistakes are my own.
1034 @c ================ Beginning of main text ================
1036 @c Start main text on right-hand (verso) page
1039 \par\vfill\supereject
1042 \par\vfill\supereject
1044 \par\vfill\supereject
1046 \par\vfill\supereject
1052 @evenheading @thispage @| @| @thischapter
1053 @oddheading @thissection @| @| @thispage
1057 @node List Processing, Practicing Evaluation, Preface, Top
1058 @comment node-name, next, previous, up
1059 @chapter List Processing
1061 To the untutored eye, Lisp is a strange programming language. In Lisp
1062 code there are parentheses everywhere. Some people even claim that
1063 the name stands for `Lots of Isolated Silly Parentheses'. But the
1064 claim is unwarranted. Lisp stands for LISt Processing, and the
1065 programming language handles @emph{lists} (and lists of lists) by
1066 putting them between parentheses. The parentheses mark the boundaries
1067 of the list. Sometimes a list is preceded by a single apostrophe or
1068 quotation mark, @samp{'}@footnote{The single apostrophe or quotation
1069 mark is an abbreviation for the function @code{quote}; you need not
1070 think about functions now; functions are defined in @ref{Making
1071 Errors, , Generate an Error Message}.} Lists are the basis of Lisp.
1077 * Names & Definitions::
1078 * Lisp Interpreter::
1084 * Error Message Exercises::
1087 @node Lisp Lists, Run a Program, List Processing, List Processing
1088 @comment node-name, next, previous, up
1092 In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}.
1093 This list is preceded by a single apostrophe. It could just as well be
1094 written as follows, which looks more like the kind of list you are likely
1095 to be familiar with:
1107 The elements of this list are the names of the four different flowers,
1108 separated from each other by whitespace and surrounded by parentheses,
1109 like flowers in a field with a stone wall around them.
1110 @cindex Flowers in a field
1115 * Whitespace in Lists::
1119 @node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists
1121 @unnumberedsubsec Numbers, Lists inside of Lists
1124 Lists can also have numbers in them, as in this list: @code{(+ 2 2)}.
1125 This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each
1126 separated by whitespace.
1128 In Lisp, both data and programs are represented the same way; that is,
1129 they are both lists of words, numbers, or other lists, separated by
1130 whitespace and surrounded by parentheses. (Since a program looks like
1131 data, one program may easily serve as data for another; this is a very
1132 powerful feature of Lisp.) (Incidentally, these two parenthetical
1133 remarks are @emph{not} Lisp lists, because they contain @samp{;} and
1134 @samp{.} as punctuation marks.)
1137 Here is another list, this time with a list inside of it:
1140 '(this list has (a list inside of it))
1143 The components of this list are the words @samp{this}, @samp{list},
1144 @samp{has}, and the list @samp{(a list inside of it)}. The interior
1145 list is made up of the words @samp{a}, @samp{list}, @samp{inside},
1146 @samp{of}, @samp{it}.
1148 @node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists
1149 @comment node-name, next, previous, up
1150 @subsection Lisp Atoms
1153 In Lisp, what we have been calling words are called @dfn{atoms}. This
1154 term comes from the historical meaning of the word atom, which means
1155 `indivisible'. As far as Lisp is concerned, the words we have been
1156 using in the lists cannot be divided into any smaller parts and still
1157 mean the same thing as part of a program; likewise with numbers and
1158 single character symbols like @samp{+}. On the other hand, unlike an
1159 ancient atom, a list can be split into parts. (@xref{car cdr & cons,
1160 , @code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
1162 In a list, atoms are separated from each other by whitespace. They can be
1163 right next to a parenthesis.
1165 @cindex @samp{empty list} defined
1166 Technically speaking, a list in Lisp consists of parentheses surrounding
1167 atoms separated by whitespace or surrounding other lists or surrounding
1168 both atoms and other lists. A list can have just one atom in it or
1169 have nothing in it at all. A list with nothing in it looks like this:
1170 @code{()}, and is called the @dfn{empty list}. Unlike anything else, an
1171 empty list is considered both an atom and a list at the same time.
1173 @cindex Symbolic expressions, introduced
1174 @cindex @samp{expression} defined
1175 @cindex @samp{form} defined
1176 The printed representation of both atoms and lists are called
1177 @dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}.
1178 The word @dfn{expression} by itself can refer to either the printed
1179 representation, or to the atom or list as it is held internally in the
1180 computer. Often, people use the term @dfn{expression}
1181 indiscriminately. (Also, in many texts, the word @dfn{form} is used
1182 as a synonym for expression.)
1184 Incidentally, the atoms that make up our universe were named such when
1185 they were thought to be indivisible; but it has been found that physical
1186 atoms are not indivisible. Parts can split off an atom or it can
1187 fission into two parts of roughly equal size. Physical atoms were named
1188 prematurely, before their truer nature was found. In Lisp, certain
1189 kinds of atom, such as an array, can be separated into parts; but the
1190 mechanism for doing this is different from the mechanism for splitting a
1191 list. As far as list operations are concerned, the atoms of a list are
1194 As in English, the meanings of the component letters of a Lisp atom
1195 are different from the meaning the letters make as a word. For
1196 example, the word for the South American sloth, the @samp{ai}, is
1197 completely different from the two words, @samp{a}, and @samp{i}.
1199 There are many kinds of atom in nature but only a few in Lisp: for
1200 example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such
1201 as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have
1202 listed in the examples above are all symbols. In everyday Lisp
1203 conversation, the word ``atom'' is not often used, because programmers
1204 usually try to be more specific about what kind of atom they are dealing
1205 with. Lisp programming is mostly about symbols (and sometimes numbers)
1206 within lists. (Incidentally, the preceding three word parenthetical
1207 remark is a proper list in Lisp, since it consists of atoms, which in
1208 this case are symbols, separated by whitespace and enclosed by
1209 parentheses, without any non-Lisp punctuation.)
1212 In addition, text between double quotation marks---even sentences or
1213 paragraphs---is an atom. Here is an example:
1214 @cindex Text between double quotation marks
1217 '(this list includes "text between quotation marks.")
1220 @cindex @samp{string} defined
1222 In Lisp, all of the quoted text including the punctuation mark and the
1223 blank spaces is a single atom. This kind of atom is called a
1224 @dfn{string} (for `string of characters') and is the sort of thing that
1225 is used for messages that a computer can print for a human to read.
1226 Strings are a different kind of atom than numbers or symbols and are
1229 @node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists
1230 @comment node-name, next, previous, up
1231 @subsection Whitespace in Lists
1232 @cindex Whitespace in lists
1235 The amount of whitespace in a list does not matter. From the point of view
1236 of the Lisp language,
1247 is exactly the same as this:
1250 '(this list looks like this)
1253 Both examples show what to Lisp is the same list, the list made up of
1254 the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and
1255 @samp{this} in that order.
1257 Extra whitespace and newlines are designed to make a list more readable
1258 by humans. When Lisp reads the expression, it gets rid of all the extra
1259 whitespace (but it needs to have at least one space between atoms in
1260 order to tell them apart.)
1262 Odd as it seems, the examples we have seen cover almost all of what Lisp
1263 lists look like! Every other list in Lisp looks more or less like one
1264 of these examples, except that the list may be longer and more complex.
1265 In brief, a list is between parentheses, a string is between quotation
1266 marks, a symbol looks like a word, and a number looks like a number.
1267 (For certain situations, square brackets, dots and a few other special
1268 characters may be used; however, we will go quite far without them.)
1270 @node Typing Lists, , Whitespace in Lists, Lisp Lists
1271 @comment node-name, next, previous, up
1272 @subsection GNU Emacs Helps You Type Lists
1273 @cindex Help typing lists
1274 @cindex Formatting help
1276 When you type a Lisp expression in GNU Emacs using either Lisp
1277 Interaction mode or Emacs Lisp mode, you have available to you several
1278 commands to format the Lisp expression so it is easy to read. For
1279 example, pressing the @key{TAB} key automatically indents the line the
1280 cursor is on by the right amount. A command to properly indent the
1281 code in a region is customarily bound to @kbd{M-C-\}. Indentation is
1282 designed so that you can see which elements of a list belong to which
1283 list---elements of a sub-list are indented more than the elements of
1286 In addition, when you type a closing parenthesis, Emacs momentarily
1287 jumps the cursor back to the matching opening parenthesis, so you can
1288 see which one it is. This is very useful, since every list you type
1289 in Lisp must have its closing parenthesis match its opening
1290 parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs
1291 Manual}, for more information about Emacs' modes.)
1293 @node Run a Program, Making Errors, Lisp Lists, List Processing
1294 @comment node-name, next, previous, up
1295 @section Run a Program
1296 @cindex Run a program
1297 @cindex Program, running one
1299 @cindex @samp{evaluate} defined
1300 A list in Lisp---any list---is a program ready to run. If you run it
1301 (for which the Lisp jargon is @dfn{evaluate}), the computer will do one
1302 of three things: do nothing except return to you the list itself; send
1303 you an error message; or, treat the first symbol in the list as a
1304 command to do something. (Usually, of course, it is the last of these
1305 three things that you really want!)
1307 @c use code for the single apostrophe, not samp.
1308 The single apostrophe, @code{'}, that I put in front of some of the
1309 example lists in preceding sections is called a @dfn{quote}; when it
1310 precedes a list, it tells Lisp to do nothing with the list, other than
1311 take it as it is written. But if there is no quote preceding a list,
1312 the first item of the list is special: it is a command for the computer
1313 to obey. (In Lisp, these commands are called @emph{functions}.) The list
1314 @code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp
1315 understands that the @code{+} is an instruction to do something with the
1316 rest of the list: add the numbers that follow.
1319 If you are reading this inside of GNU Emacs in Info, here is how you can
1320 evaluate such a list: place your cursor immediately after the right
1321 hand parenthesis of the following list and then type @kbd{C-x C-e}:
1327 @c use code for the number four, not samp.
1329 You will see the number @code{4} appear in the echo area. (In the
1330 jargon, what you have just done is ``evaluate the list.'' The echo area
1331 is the line at the bottom of the screen that displays or ``echoes''
1332 text.) Now try the same thing with a quoted list: place the cursor
1333 right after the following list and type @kbd{C-x C-e}:
1336 '(this is a quoted list)
1340 You will see @code{(this is a quoted list)} appear in the echo area.
1342 @cindex Lisp interpreter, explained
1343 @cindex Interpreter, Lisp, explained
1344 In both cases, what you are doing is giving a command to the program
1345 inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the
1346 interpreter a command to evaluate the expression. The name of the Lisp
1347 interpreter comes from the word for the task done by a human who comes
1348 up with the meaning of an expression---who ``interprets'' it.
1350 You can also evaluate an atom that is not part of a list---one that is
1351 not surrounded by parentheses; again, the Lisp interpreter translates
1352 from the humanly readable expression to the language of the computer.
1353 But before discussing this (@pxref{Variables}), we will discuss what the
1354 Lisp interpreter does when you make an error.
1356 @node Making Errors, Names & Definitions, Run a Program, List Processing
1357 @comment node-name, next, previous, up
1358 @section Generate an Error Message
1359 @cindex Generate an error message
1360 @cindex Error message generation
1362 Partly so you won't worry if you do it accidentally, we will now give
1363 a command to the Lisp interpreter that generates an error message.
1364 This is a harmless activity; and indeed, we will often try to generate
1365 error messages intentionally. Once you understand the jargon, error
1366 messages can be informative. Instead of being called ``error''
1367 messages, they should be called ``help'' messages. They are like
1368 signposts to a traveller in a strange country; deciphering them can be
1369 hard, but once understood, they can point the way.
1371 The error message is generated by a built-in GNU Emacs debugger. We
1372 will `enter the debugger'. You get out of the debugger by typing @code{q}.
1374 What we will do is evaluate a list that is not quoted and does not
1375 have a meaningful command as its first element. Here is a list almost
1376 exactly the same as the one we just used, but without the single-quote
1377 in front of it. Position the cursor right after it and type @kbd{C-x
1381 (this is an unquoted list)
1385 What you see depends on which version of Emacs you are running. GNU
1386 Emacs version 22 provides more information than version 20 and before.
1387 First, the more recent result of generating an error; then the
1388 earlier, version 20 result.
1392 In GNU Emacs version 22, a @file{*Backtrace*} window will open up and
1393 you will see the following in it:
1397 ---------- Buffer: *Backtrace* ----------
1398 Debugger entered--Lisp error: (void-function this)
1399 (this is an unquoted list)
1400 eval((this is an unquoted list))
1401 eval-last-sexp-1(nil)
1403 call-interactively(eval-last-sexp)
1404 ---------- Buffer: *Backtrace* ----------
1410 Your cursor will be in this window (you may have to wait a few seconds
1411 before it becomes visible). To quit the debugger and make the
1412 debugger window go away, type:
1419 Please type @kbd{q} right now, so you become confident that you can
1420 get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter
1423 @cindex @samp{function} defined
1424 Based on what we already know, we can almost read this error message.
1426 You read the @file{*Backtrace*} buffer from the bottom up; it tells
1427 you what Emacs did. When you typed @kbd{C-x C-e}, you made an
1428 interactive call to the command @code{eval-last-sexp}. @code{eval} is
1429 an abbreviation for `evaluate' and @code{sexp} is an abbreviation for
1430 `symbolic expression'. The command means `evaluate last symbolic
1431 expression', which is the expression just before your cursor.
1433 Each line above tells you what the Lisp interpreter evaluated next.
1434 The most recent action is at the top. The buffer is called the
1435 @file{*Backtrace*} buffer because it enables you to track Emacs
1439 At the top of the @file{*Backtrace*} buffer, you see the line:
1442 Debugger entered--Lisp error: (void-function this)
1446 The Lisp interpreter tried to evaluate the first atom of the list, the
1447 word @samp{this}. It is this action that generated the error message
1448 @samp{void-function this}.
1450 The message contains the words @samp{void-function} and @samp{this}.
1452 @cindex @samp{function} defined
1453 The word @samp{function} was mentioned once before. It is a very
1454 important word. For our purposes, we can define it by saying that a
1455 @dfn{function} is a set of instructions to the computer that tell the
1456 computer to do something.
1458 Now we can begin to understand the error message: @samp{void-function
1459 this}. The function (that is, the word @samp{this}) does not have a
1460 definition of any set of instructions for the computer to carry out.
1462 The slightly odd word, @samp{void-function}, is designed to cover the
1463 way Emacs Lisp is implemented, which is that when a symbol does not
1464 have a function definition attached to it, the place that should
1465 contain the instructions is `void'.
1467 On the other hand, since we were able to add 2 plus 2 successfully, by
1468 evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must
1469 have a set of instructions for the computer to obey and those
1470 instructions must be to add the numbers that follow the @code{+}.
1473 In GNU Emacs version 20, and in earlier versions, you will see only
1474 one line of error message; it will appear in the echo area and look
1478 Symbol's function definition is void:@: this
1482 (Also, your terminal may beep at you---some do, some don't; and others
1483 blink. This is just a device to get your attention.) The message goes
1484 away as soon as you type another key, even just to move the cursor.
1486 We know the meaning of the word @samp{Symbol}. It refers to the first
1487 atom of the list, the word @samp{this}. The word @samp{function}
1488 refers to the instructions that tell the computer what to do.
1489 (Technically, the symbol tells the computer where to find the
1490 instructions, but this is a complication we can ignore for the
1493 The error message can be understood: @samp{Symbol's function
1494 definition is void:@: this}. The symbol (that is, the word
1495 @samp{this}) lacks instructions for the computer to carry out.
1497 @node Names & Definitions, Lisp Interpreter, Making Errors, List Processing
1498 @comment node-name, next, previous, up
1499 @section Symbol Names and Function Definitions
1500 @cindex Symbol names
1502 We can articulate another characteristic of Lisp based on what we have
1503 discussed so far---an important characteristic: a symbol, like
1504 @code{+}, is not itself the set of instructions for the computer to
1505 carry out. Instead, the symbol is used, perhaps temporarily, as a way
1506 of locating the definition or set of instructions. What we see is the
1507 name through which the instructions can be found. Names of people
1508 work the same way. I can be referred to as @samp{Bob}; however, I am
1509 not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the
1510 consciousness consistently associated with a particular life-form.
1511 The name is not me, but it can be used to refer to me.
1513 In Lisp, one set of instructions can be attached to several names.
1514 For example, the computer instructions for adding numbers can be
1515 linked to the symbol @code{plus} as well as to the symbol @code{+}
1516 (and are in some dialects of Lisp). Among humans, I can be referred
1517 to as @samp{Robert} as well as @samp{Bob} and by other words as well.
1519 On the other hand, a symbol can have only one function definition
1520 attached to it at a time. Otherwise, the computer would be confused as
1521 to which definition to use. If this were the case among people, only
1522 one person in the world could be named @samp{Bob}. However, the function
1523 definition to which the name refers can be changed readily.
1524 (@xref{Install, , Install a Function Definition}.)
1526 Since Emacs Lisp is large, it is customary to name symbols in a way
1527 that identifies the part of Emacs to which the function belongs.
1528 Thus, all the names for functions that deal with Texinfo start with
1529 @samp{texinfo-} and those for functions that deal with reading mail
1530 start with @samp{rmail-}.
1532 @node Lisp Interpreter, Evaluation, Names & Definitions, List Processing
1533 @comment node-name, next, previous, up
1534 @section The Lisp Interpreter
1535 @cindex Lisp interpreter, what it does
1536 @cindex Interpreter, what it does
1538 Based on what we have seen, we can now start to figure out what the
1539 Lisp interpreter does when we command it to evaluate a list.
1540 First, it looks to see whether there is a quote before the list; if
1541 there is, the interpreter just gives us the list. On the other
1542 hand, if there is no quote, the interpreter looks at the first element
1543 in the list and sees whether it has a function definition. If it does,
1544 the interpreter carries out the instructions in the function definition.
1545 Otherwise, the interpreter prints an error message.
1547 This is how Lisp works. Simple. There are added complications which we
1548 will get to in a minute, but these are the fundamentals. Of course, to
1549 write Lisp programs, you need to know how to write function definitions
1550 and attach them to names, and how to do this without confusing either
1551 yourself or the computer.
1558 @node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter
1560 @unnumberedsubsec Complications
1563 Now, for the first complication. In addition to lists, the Lisp
1564 interpreter can evaluate a symbol that is not quoted and does not have
1565 parentheses around it. The Lisp interpreter will attempt to determine
1566 the symbol's value as a @dfn{variable}. This situation is described
1567 in the section on variables. (@xref{Variables}.)
1569 @cindex Special form
1570 The second complication occurs because some functions are unusual and do
1571 not work in the usual manner. Those that don't are called @dfn{special
1572 forms}. They are used for special jobs, like defining a function, and
1573 there are not many of them. In the next few chapters, you will be
1574 introduced to several of the more important special forms.
1576 The third and final complication is this: if the function that the
1577 Lisp interpreter is looking at is not a special form, and if it is part
1578 of a list, the Lisp interpreter looks to see whether the list has a list
1579 inside of it. If there is an inner list, the Lisp interpreter first
1580 figures out what it should do with the inside list, and then it works on
1581 the outside list. If there is yet another list embedded inside the
1582 inner list, it works on that one first, and so on. It always works on
1583 the innermost list first. The interpreter works on the innermost list
1584 first, to evaluate the result of that list. The result may be
1585 used by the enclosing expression.
1587 Otherwise, the interpreter works left to right, from one expression to
1590 @node Byte Compiling, , Complications, Lisp Interpreter
1591 @subsection Byte Compiling
1592 @cindex Byte compiling
1594 One other aspect of interpreting: the Lisp interpreter is able to
1595 interpret two kinds of entity: humanly readable code, on which we will
1596 focus exclusively, and specially processed code, called @dfn{byte
1597 compiled} code, which is not humanly readable. Byte compiled code
1598 runs faster than humanly readable code.
1600 You can transform humanly readable code into byte compiled code by
1601 running one of the compile commands such as @code{byte-compile-file}.
1602 Byte compiled code is usually stored in a file that ends with a
1603 @file{.elc} extension rather than a @file{.el} extension. You will
1604 see both kinds of file in the @file{emacs/lisp} directory; the files
1605 to read are those with @file{.el} extensions.
1607 As a practical matter, for most things you might do to customize or
1608 extend Emacs, you do not need to byte compile; and I will not discuss
1609 the topic here. @xref{Byte Compilation, , Byte Compilation, elisp,
1610 The GNU Emacs Lisp Reference Manual}, for a full description of byte
1613 @node Evaluation, Variables, Lisp Interpreter, List Processing
1614 @comment node-name, next, previous, up
1618 When the Lisp interpreter works on an expression, the term for the
1619 activity is called @dfn{evaluation}. We say that the interpreter
1620 `evaluates the expression'. I've used this term several times before.
1621 The word comes from its use in everyday language, `to ascertain the
1622 value or amount of; to appraise', according to @cite{Webster's New
1623 Collegiate Dictionary}.
1625 After evaluating an expression, the Lisp interpreter will most likely
1626 @dfn{return} the value that the computer produces by carrying out the
1627 instructions it found in the function definition, or perhaps it will
1628 give up on that function and produce an error message. (The interpreter
1629 may also find itself tossed, so to speak, to a different function or it
1630 may attempt to repeat continually what it is doing for ever and ever in
1631 what is called an `infinite loop'. These actions are less common; and
1632 we can ignore them.) Most frequently, the interpreter returns a value.
1634 @cindex @samp{side effect} defined
1635 At the same time the interpreter returns a value, it may do something
1636 else as well, such as move a cursor or copy a file; this other kind of
1637 action is called a @dfn{side effect}. Actions that we humans think are
1638 important, such as printing results, are often ``side effects'' to the
1639 Lisp interpreter. The jargon can sound peculiar, but it turns out that
1640 it is fairly easy to learn to use side effects.
1642 In summary, evaluating a symbolic expression most commonly causes the
1643 Lisp interpreter to return a value and perhaps carry out a side effect;
1644 or else produce an error.
1647 * Evaluating Inner Lists::
1650 @node Evaluating Inner Lists, , Evaluation, Evaluation
1651 @comment node-name, next, previous, up
1652 @subsection Evaluating Inner Lists
1653 @cindex Inner list evaluation
1654 @cindex Evaluating inner lists
1656 If evaluation applies to a list that is inside another list, the outer
1657 list may use the value returned by the first evaluation as information
1658 when the outer list is evaluated. This explains why inner expressions
1659 are evaluated first: the values they return are used by the outer
1663 We can investigate this process by evaluating another addition example.
1664 Place your cursor after the following expression and type @kbd{C-x C-e}:
1671 The number 8 will appear in the echo area.
1673 What happens is that the Lisp interpreter first evaluates the inner
1674 expression, @code{(+ 3 3)}, for which the value 6 is returned; then it
1675 evaluates the outer expression as if it were written @code{(+ 2 6)}, which
1676 returns the value 8. Since there are no more enclosing expressions to
1677 evaluate, the interpreter prints that value in the echo area.
1679 Now it is easy to understand the name of the command invoked by the
1680 keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The
1681 letters @code{sexp} are an abbreviation for `symbolic expression', and
1682 @code{eval} is an abbreviation for `evaluate'. The command means
1683 `evaluate last symbolic expression'.
1685 As an experiment, you can try evaluating the expression by putting the
1686 cursor at the beginning of the next line immediately following the
1687 expression, or inside the expression.
1690 Here is another copy of the expression:
1697 If you place the cursor at the beginning of the blank line that
1698 immediately follows the expression and type @kbd{C-x C-e}, you will
1699 still get the value 8 printed in the echo area. Now try putting the
1700 cursor inside the expression. If you put it right after the next to
1701 last parenthesis (so it appears to sit on top of the last parenthesis),
1702 you will get a 6 printed in the echo area! This is because the command
1703 evaluates the expression @code{(+ 3 3)}.
1705 Now put the cursor immediately after a number. Type @kbd{C-x C-e} and
1706 you will get the number itself. In Lisp, if you evaluate a number, you
1707 get the number itself---this is how numbers differ from symbols. If you
1708 evaluate a list starting with a symbol like @code{+}, you will get a
1709 value returned that is the result of the computer carrying out the
1710 instructions in the function definition attached to that name. If a
1711 symbol by itself is evaluated, something different happens, as we will
1712 see in the next section.
1714 @node Variables, Arguments, Evaluation, List Processing
1715 @comment node-name, next, previous, up
1719 In Emacs Lisp, a symbol can have a value attached to it just as it can
1720 have a function definition attached to it. The two are different.
1721 The function definition is a set of instructions that a computer will
1722 obey. A value, on the other hand, is something, such as number or a
1723 name, that can vary (which is why such a symbol is called a variable).
1724 The value of a symbol can be any expression in Lisp, such as a symbol,
1725 number, list, or string. A symbol that has a value is often called a
1728 A symbol can have both a function definition and a value attached to
1729 it at the same time. Or it can have just one or the other.
1730 The two are separate. This is somewhat similar
1731 to the way the name Cambridge can refer to the city in Massachusetts
1732 and have some information attached to the name as well, such as
1733 ``great programming center''.
1736 (Incidentally, in Emacs Lisp, a symbol can have two
1737 other things attached to it, too: a property list and a documentation
1738 string; these are discussed later.)
1741 Another way to think about this is to imagine a symbol as being a chest
1742 of drawers. The function definition is put in one drawer, the value in
1743 another, and so on. What is put in the drawer holding the value can be
1744 changed without affecting the contents of the drawer holding the
1745 function definition, and vice-verse.
1748 * fill-column Example::
1753 @node fill-column Example, Void Function, Variables, Variables
1755 @unnumberedsubsec @code{fill-column}, an Example Variable
1758 @findex fill-column, @r{an example variable}
1759 @cindex Example variable, @code{fill-column}
1760 @cindex Variable, example of, @code{fill-column}
1761 The variable @code{fill-column} illustrates a symbol with a value
1762 attached to it: in every GNU Emacs buffer, this symbol is set to some
1763 value, usually 72 or 70, but sometimes to some other value. To find the
1764 value of this symbol, evaluate it by itself. If you are reading this in
1765 Info inside of GNU Emacs, you can do this by putting the cursor after
1766 the symbol and typing @kbd{C-x C-e}:
1773 After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo
1774 area. This is the value for which @code{fill-column} is set for me as I
1775 write this. It may be different for you in your Info buffer. Notice
1776 that the value returned as a variable is printed in exactly the same way
1777 as the value returned by a function carrying out its instructions. From
1778 the point of view of the Lisp interpreter, a value returned is a value
1779 returned. What kind of expression it came from ceases to matter once
1782 A symbol can have any value attached to it or, to use the jargon, we can
1783 @dfn{bind} the variable to a value: to a number, such as 72; to a
1784 string, @code{"such as this"}; to a list, such as @code{(spruce pine
1785 oak)}; we can even bind a variable to a function definition.
1787 A symbol can be bound to a value in several ways. @xref{set & setq, ,
1788 Setting the Value of a Variable}, for information about one way to do
1791 @node Void Function, Void Variable, fill-column Example, Variables
1792 @comment node-name, next, previous, up
1793 @subsection Error Message for a Symbol Without a Function
1794 @cindex Symbol without function error
1795 @cindex Error for symbol without function
1797 When we evaluated @code{fill-column} to find its value as a variable,
1798 we did not place parentheses around the word. This is because we did
1799 not intend to use it as a function name.
1801 If @code{fill-column} were the first or only element of a list, the
1802 Lisp interpreter would attempt to find the function definition
1803 attached to it. But @code{fill-column} has no function definition.
1804 Try evaluating this:
1812 In GNU Emacs version 22, you will create a @file{*Backtrace*} buffer
1817 ---------- Buffer: *Backtrace* ----------
1818 Debugger entered--Lisp error: (void-function fill-column)
1821 eval-last-sexp-1(nil)
1823 call-interactively(eval-last-sexp)
1824 ---------- Buffer: *Backtrace* ----------
1829 (Remember, to quit the debugger and make the debugger window go away,
1830 type @kbd{q} in the @file{*Backtrace*} buffer.)
1834 In GNU Emacs 20 and before, you will produce an error message that says:
1837 Symbol's function definition is void:@: fill-column
1841 (The message will go away as soon as you move the cursor or type
1845 @node Void Variable, , Void Function, Variables
1846 @comment node-name, next, previous, up
1847 @subsection Error Message for a Symbol Without a Value
1848 @cindex Symbol without value error
1849 @cindex Error for symbol without value
1851 If you attempt to evaluate a symbol that does not have a value bound to
1852 it, you will receive an error message. You can see this by
1853 experimenting with our 2 plus 2 addition. In the following expression,
1854 put your cursor right after the @code{+}, before the first number 2,
1863 In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that
1868 ---------- Buffer: *Backtrace* ----------
1869 Debugger entered--Lisp error: (void-variable +)
1871 eval-last-sexp-1(nil)
1873 call-interactively(eval-last-sexp)
1874 ---------- Buffer: *Backtrace* ----------
1879 (As with the other times we entered the debugger, you can quit by
1880 typing @kbd{q} in the @file{*Backtrace*} buffer.)
1882 This backtrace is different from the very first error message we saw,
1883 which said, @samp{Debugger entered--Lisp error: (void-function this)}.
1884 In this case, the function does not have a value as a variable; while
1885 in the other error message, the function (the word `this') did not
1888 In this experiment with the @code{+}, what we did was cause the Lisp
1889 interpreter to evaluate the @code{+} and look for the value of the
1890 variable instead of the function definition. We did this by placing the
1891 cursor right after the symbol rather than after the parenthesis of the
1892 enclosing list as we did before. As a consequence, the Lisp interpreter
1893 evaluated the preceding s-expression, which in this case was the
1896 Since @code{+} does not have a value bound to it, just the function
1897 definition, the error message reported that the symbol's value as a
1902 In GNU Emacs version 20 and before, your error message will say:
1905 Symbol's value as variable is void:@: +
1909 The meaning is the same as in GNU Emacs 22.
1912 @node Arguments, set & setq, Variables, List Processing
1913 @comment node-name, next, previous, up
1916 @cindex Passing information to functions
1918 To see how information is passed to functions, let's look again at
1919 our old standby, the addition of two plus two. In Lisp, this is written
1926 If you evaluate this expression, the number 4 will appear in your echo
1927 area. What the Lisp interpreter does is add the numbers that follow
1930 @cindex @samp{argument} defined
1931 The numbers added by @code{+} are called the @dfn{arguments} of the
1932 function @code{+}. These numbers are the information that is given to
1933 or @dfn{passed} to the function.
1935 The word `argument' comes from the way it is used in mathematics and
1936 does not refer to a disputation between two people; instead it refers to
1937 the information presented to the function, in this case, to the
1938 @code{+}. In Lisp, the arguments to a function are the atoms or lists
1939 that follow the function. The values returned by the evaluation of
1940 these atoms or lists are passed to the function. Different functions
1941 require different numbers of arguments; some functions require none at
1942 all.@footnote{It is curious to track the path by which the word `argument'
1943 came to have two different meanings, one in mathematics and the other in
1944 everyday English. According to the @cite{Oxford English Dictionary},
1945 the word derives from the Latin for @samp{to make clear, prove}; thus it
1946 came to mean, by one thread of derivation, `the evidence offered as
1947 proof', which is to say, `the information offered', which led to its
1948 meaning in Lisp. But in the other thread of derivation, it came to mean
1949 `to assert in a manner against which others may make counter
1950 assertions', which led to the meaning of the word as a disputation.
1951 (Note here that the English word has two different definitions attached
1952 to it at the same time. By contrast, in Emacs Lisp, a symbol cannot
1953 have two different function definitions at the same time.)}
1957 * Args as Variable or List::
1958 * Variable Number of Arguments::
1959 * Wrong Type of Argument::
1963 @node Data types, Args as Variable or List, Arguments, Arguments
1964 @comment node-name, next, previous, up
1965 @subsection Arguments' Data Types
1967 @cindex Types of data
1968 @cindex Arguments' data types
1970 The type of data that should be passed to a function depends on what
1971 kind of information it uses. The arguments to a function such as
1972 @code{+} must have values that are numbers, since @code{+} adds numbers.
1973 Other functions use different kinds of data for their arguments.
1977 For example, the @code{concat} function links together or unites two or
1978 more strings of text to produce a string. The arguments are strings.
1979 Concatenating the two character strings @code{abc}, @code{def} produces
1980 the single string @code{abcdef}. This can be seen by evaluating the
1984 (concat "abc" "def")
1988 The value produced by evaluating this expression is @code{"abcdef"}.
1990 A function such as @code{substring} uses both a string and numbers as
1991 arguments. The function returns a part of the string, a substring of
1992 the first argument. This function takes three arguments. Its first
1993 argument is the string of characters, the second and third arguments are
1994 numbers that indicate the beginning and end of the substring. The
1995 numbers are a count of the number of characters (including spaces and
1996 punctuations) from the beginning of the string.
1999 For example, if you evaluate the following:
2002 (substring "The quick brown fox jumped." 16 19)
2006 you will see @code{"fox"} appear in the echo area. The arguments are the
2007 string and the two numbers.
2009 Note that the string passed to @code{substring} is a single atom even
2010 though it is made up of several words separated by spaces. Lisp counts
2011 everything between the two quotation marks as part of the string,
2012 including the spaces. You can think of the @code{substring} function as
2013 a kind of `atom smasher' since it takes an otherwise indivisible atom
2014 and extracts a part. However, @code{substring} is only able to extract
2015 a substring from an argument that is a string, not from another type of
2016 atom such as a number or symbol.
2018 @node Args as Variable or List, Variable Number of Arguments, Data types, Arguments
2019 @comment node-name, next, previous, up
2020 @subsection An Argument as the Value of a Variable or List
2022 An argument can be a symbol that returns a value when it is evaluated.
2023 For example, when the symbol @code{fill-column} by itself is evaluated,
2024 it returns a number. This number can be used in an addition.
2027 Position the cursor after the following expression and type @kbd{C-x
2035 The value will be a number two more than what you get by evaluating
2036 @code{fill-column} alone. For me, this is 74, because my value of
2037 @code{fill-column} is 72.
2039 As we have just seen, an argument can be a symbol that returns a value
2040 when evaluated. In addition, an argument can be a list that returns a
2041 value when it is evaluated. For example, in the following expression,
2042 the arguments to the function @code{concat} are the strings
2043 @w{@code{"The "}} and @w{@code{" red foxes."}} and the list
2044 @code{(number-to-string (+ 2 fill-column))}.
2046 @c For GNU Emacs 22, need number-to-string
2048 (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
2052 If you evaluate this expression---and if, as with my Emacs,
2053 @code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will
2054 appear in the echo area. (Note that you must put spaces after the
2055 word @samp{The} and before the word @samp{red} so they will appear in
2056 the final string. The function @code{number-to-string} converts the
2057 integer that the addition function returns to a string.
2058 @code{number-to-string} is also known as @code{int-to-string}.)
2060 @node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments
2061 @comment node-name, next, previous, up
2062 @subsection Variable Number of Arguments
2063 @cindex Variable number of arguments
2064 @cindex Arguments, variable number of
2066 Some functions, such as @code{concat}, @code{+} or @code{*}, take any
2067 number of arguments. (The @code{*} is the symbol for multiplication.)
2068 This can be seen by evaluating each of the following expressions in
2069 the usual way. What you will see in the echo area is printed in this
2070 text after @samp{@result{}}, which you may read as `evaluates to'.
2073 In the first set, the functions have no arguments:
2084 In this set, the functions have one argument each:
2095 In this set, the functions have three arguments each:
2099 (+ 3 4 5) @result{} 12
2101 (* 3 4 5) @result{} 60
2105 @node Wrong Type of Argument, message, Variable Number of Arguments, Arguments
2106 @comment node-name, next, previous, up
2107 @subsection Using the Wrong Type Object as an Argument
2108 @cindex Wrong type of argument
2109 @cindex Argument, wrong type of
2111 When a function is passed an argument of the wrong type, the Lisp
2112 interpreter produces an error message. For example, the @code{+}
2113 function expects the values of its arguments to be numbers. As an
2114 experiment we can pass it the quoted symbol @code{hello} instead of a
2115 number. Position the cursor after the following expression and type
2123 When you do this you will generate an error message. What has happened
2124 is that @code{+} has tried to add the 2 to the value returned by
2125 @code{'hello}, but the value returned by @code{'hello} is the symbol
2126 @code{hello}, not a number. Only numbers can be added. So @code{+}
2127 could not carry out its addition.
2130 In GNU Emacs version 22, you will create and enter a
2131 @file{*Backtrace*} buffer that says:
2136 ---------- Buffer: *Backtrace* ----------
2137 Debugger entered--Lisp error:
2138 (wrong-type-argument number-or-marker-p hello)
2140 eval((+ 2 (quote hello)))
2141 eval-last-sexp-1(nil)
2143 call-interactively(eval-last-sexp)
2144 ---------- Buffer: *Backtrace* ----------
2149 As usual, the error message tries to be helpful and makes sense after you
2150 learn how to read it.@footnote{@code{(quote hello)} is an expansion of
2151 the abbreviation @code{'hello}.}
2153 The first part of the error message is straightforward; it says
2154 @samp{wrong type argument}. Next comes the mysterious jargon word
2155 @w{@samp{number-or-marker-p}}. This word is trying to tell you what
2156 kind of argument the @code{+} expected.
2158 The symbol @code{number-or-marker-p} says that the Lisp interpreter is
2159 trying to determine whether the information presented it (the value of
2160 the argument) is a number or a marker (a special object representing a
2161 buffer position). What it does is test to see whether the @code{+} is
2162 being given numbers to add. It also tests to see whether the
2163 argument is something called a marker, which is a specific feature of
2164 Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers.
2165 When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command,
2166 its position is kept as a marker. The mark can be considered a
2167 number---the number of characters the location is from the beginning
2168 of the buffer.) In Emacs Lisp, @code{+} can be used to add the
2169 numeric value of marker positions as numbers.
2171 The @samp{p} of @code{number-or-marker-p} is the embodiment of a
2172 practice started in the early days of Lisp programming. The @samp{p}
2173 stands for `predicate'. In the jargon used by the early Lisp
2174 researchers, a predicate refers to a function to determine whether some
2175 property is true or false. So the @samp{p} tells us that
2176 @code{number-or-marker-p} is the name of a function that determines
2177 whether it is true or false that the argument supplied is a number or
2178 a marker. Other Lisp symbols that end in @samp{p} include @code{zerop},
2179 a function that tests whether its argument has the value of zero, and
2180 @code{listp}, a function that tests whether its argument is a list.
2182 Finally, the last part of the error message is the symbol @code{hello}.
2183 This is the value of the argument that was passed to @code{+}. If the
2184 addition had been passed the correct type of object, the value passed
2185 would have been a number, such as 37, rather than a symbol like
2186 @code{hello}. But then you would not have got the error message.
2190 In GNU Emacs version 20 and before, the echo area displays an error
2194 Wrong type argument:@: number-or-marker-p, hello
2197 This says, in different words, the same as the top line of the
2198 @file{*Backtrace*} buffer.
2201 @node message, , Wrong Type of Argument, Arguments
2202 @comment node-name, next, previous, up
2203 @subsection The @code{message} Function
2206 Like @code{+}, the @code{message} function takes a variable number of
2207 arguments. It is used to send messages to the user and is so useful
2208 that we will describe it here.
2211 A message is printed in the echo area. For example, you can print a
2212 message in your echo area by evaluating the following list:
2215 (message "This message appears in the echo area!")
2218 The whole string between double quotation marks is a single argument
2219 and is printed @i{in toto}. (Note that in this example, the message
2220 itself will appear in the echo area within double quotes; that is
2221 because you see the value returned by the @code{message} function. In
2222 most uses of @code{message} in programs that you write, the text will
2223 be printed in the echo area as a side-effect, without the quotes.
2224 @xref{multiply-by-seven in detail, , @code{multiply-by-seven} in
2225 detail}, for an example of this.)
2227 However, if there is a @samp{%s} in the quoted string of characters, the
2228 @code{message} function does not print the @samp{%s} as such, but looks
2229 to the argument that follows the string. It evaluates the second
2230 argument and prints the value at the location in the string where the
2234 You can see this by positioning the cursor after the following
2235 expression and typing @kbd{C-x C-e}:
2238 (message "The name of this buffer is: %s." (buffer-name))
2242 In Info, @code{"The name of this buffer is: *info*."} will appear in the
2243 echo area. The function @code{buffer-name} returns the name of the
2244 buffer as a string, which the @code{message} function inserts in place
2247 To print a value as an integer, use @samp{%d} in the same way as
2248 @samp{%s}. For example, to print a message in the echo area that
2249 states the value of the @code{fill-column}, evaluate the following:
2252 (message "The value of fill-column is %d." fill-column)
2256 On my system, when I evaluate this list, @code{"The value of
2257 fill-column is 72."} appears in my echo area@footnote{Actually, you
2258 can use @code{%s} to print a number. It is non-specific. @code{%d}
2259 prints only the part of a number left of a decimal point, and not
2260 anything that is not a number.}.
2262 If there is more than one @samp{%s} in the quoted string, the value of
2263 the first argument following the quoted string is printed at the
2264 location of the first @samp{%s} and the value of the second argument is
2265 printed at the location of the second @samp{%s}, and so on.
2268 For example, if you evaluate the following,
2272 (message "There are %d %s in the office!"
2273 (- fill-column 14) "pink elephants")
2278 a rather whimsical message will appear in your echo area. On my system
2279 it says, @code{"There are 58 pink elephants in the office!"}.
2281 The expression @code{(- fill-column 14)} is evaluated and the resulting
2282 number is inserted in place of the @samp{%d}; and the string in double
2283 quotes, @code{"pink elephants"}, is treated as a single argument and
2284 inserted in place of the @samp{%s}. (That is to say, a string between
2285 double quotes evaluates to itself, like a number.)
2287 Finally, here is a somewhat complex example that not only illustrates
2288 the computation of a number, but also shows how you can use an
2289 expression within an expression to generate the text that is substituted
2294 (message "He saw %d %s"
2298 "The quick brown foxes jumped." 16 21)
2303 In this example, @code{message} has three arguments: the string,
2304 @code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and
2305 the expression beginning with the function @code{concat}. The value
2306 resulting from the evaluation of @code{(- fill-column 32)} is inserted
2307 in place of the @samp{%d}; and the value returned by the expression
2308 beginning with @code{concat} is inserted in place of the @samp{%s}.
2310 When your fill column is 70 and you evaluate the expression, the
2311 message @code{"He saw 38 red foxes leaping."} appears in your echo
2314 @node set & setq, Summary, Arguments, List Processing
2315 @comment node-name, next, previous, up
2316 @section Setting the Value of a Variable
2317 @cindex Variable, setting value
2318 @cindex Setting value of variable
2320 @cindex @samp{bind} defined
2321 There are several ways by which a variable can be given a value. One of
2322 the ways is to use either the function @code{set} or the function
2323 @code{setq}. Another way is to use @code{let} (@pxref{let}). (The
2324 jargon for this process is to @dfn{bind} a variable to a value.)
2326 The following sections not only describe how @code{set} and @code{setq}
2327 work but also illustrate how arguments are passed.
2335 @node Using set, Using setq, set & setq, set & setq
2336 @comment node-name, next, previous, up
2337 @subsection Using @code{set}
2340 To set the value of the symbol @code{flowers} to the list @code{'(rose
2341 violet daisy buttercup)}, evaluate the following expression by
2342 positioning the cursor after the expression and typing @kbd{C-x C-e}.
2345 (set 'flowers '(rose violet daisy buttercup))
2349 The list @code{(rose violet daisy buttercup)} will appear in the echo
2350 area. This is what is @emph{returned} by the @code{set} function. As a
2351 side effect, the symbol @code{flowers} is bound to the list; that is,
2352 the symbol @code{flowers}, which can be viewed as a variable, is given
2353 the list as its value. (This process, by the way, illustrates how a
2354 side effect to the Lisp interpreter, setting the value, can be the
2355 primary effect that we humans are interested in. This is because every
2356 Lisp function must return a value if it does not get an error, but it
2357 will only have a side effect if it is designed to have one.)
2359 After evaluating the @code{set} expression, you can evaluate the symbol
2360 @code{flowers} and it will return the value you just set. Here is the
2361 symbol. Place your cursor after it and type @kbd{C-x C-e}.
2368 When you evaluate @code{flowers}, the list
2369 @code{(rose violet daisy buttercup)} appears in the echo area.
2371 Incidentally, if you evaluate @code{'flowers}, the variable with a quote
2372 in front of it, what you will see in the echo area is the symbol itself,
2373 @code{flowers}. Here is the quoted symbol, so you can try this:
2379 Note also, that when you use @code{set}, you need to quote both
2380 arguments to @code{set}, unless you want them evaluated. Since we do
2381 not want either argument evaluated, neither the variable
2382 @code{flowers} nor the list @code{(rose violet daisy buttercup)}, both
2383 are quoted. (When you use @code{set} without quoting its first
2384 argument, the first argument is evaluated before anything else is
2385 done. If you did this and @code{flowers} did not have a value
2386 already, you would get an error message that the @samp{Symbol's value
2387 as variable is void}; on the other hand, if @code{flowers} did return
2388 a value after it was evaluated, the @code{set} would attempt to set
2389 the value that was returned. There are situations where this is the
2390 right thing for the function to do; but such situations are rare.)
2392 @node Using setq, Counting, Using set, set & setq
2393 @comment node-name, next, previous, up
2394 @subsection Using @code{setq}
2397 As a practical matter, you almost always quote the first argument to
2398 @code{set}. The combination of @code{set} and a quoted first argument
2399 is so common that it has its own name: the special form @code{setq}.
2400 This special form is just like @code{set} except that the first argument
2401 is quoted automatically, so you don't need to type the quote mark
2402 yourself. Also, as an added convenience, @code{setq} permits you to set
2403 several different variables to different values, all in one expression.
2405 To set the value of the variable @code{carnivores} to the list
2406 @code{'(lion tiger leopard)} using @code{setq}, the following expression
2410 (setq carnivores '(lion tiger leopard))
2414 This is exactly the same as using @code{set} except the first argument
2415 is automatically quoted by @code{setq}. (The @samp{q} in @code{setq}
2416 means @code{quote}.)
2419 With @code{set}, the expression would look like this:
2422 (set 'carnivores '(lion tiger leopard))
2425 Also, @code{setq} can be used to assign different values to
2426 different variables. The first argument is bound to the value
2427 of the second argument, the third argument is bound to the value of the
2428 fourth argument, and so on. For example, you could use the following to
2429 assign a list of trees to the symbol @code{trees} and a list of herbivores
2430 to the symbol @code{herbivores}:
2434 (setq trees '(pine fir oak maple)
2435 herbivores '(gazelle antelope zebra))
2440 (The expression could just as well have been on one line, but it might
2441 not have fit on a page; and humans find it easier to read nicely
2444 Although I have been using the term `assign', there is another way of
2445 thinking about the workings of @code{set} and @code{setq}; and that is to
2446 say that @code{set} and @code{setq} make the symbol @emph{point} to the
2447 list. This latter way of thinking is very common and in forthcoming
2448 chapters we shall come upon at least one symbol that has `pointer' as
2449 part of its name. The name is chosen because the symbol has a value,
2450 specifically a list, attached to it; or, expressed another way,
2451 the symbol is set to ``point'' to the list.
2453 @node Counting, , Using setq, set & setq
2454 @comment node-name, next, previous, up
2455 @subsection Counting
2458 Here is an example that shows how to use @code{setq} in a counter. You
2459 might use this to count how many times a part of your program repeats
2460 itself. First set a variable to zero; then add one to the number each
2461 time the program repeats itself. To do this, you need a variable that
2462 serves as a counter, and two expressions: an initial @code{setq}
2463 expression that sets the counter variable to zero; and a second
2464 @code{setq} expression that increments the counter each time it is
2469 (setq counter 0) ; @r{Let's call this the initializer.}
2471 (setq counter (+ counter 1)) ; @r{This is the incrementer.}
2473 counter ; @r{This is the counter.}
2478 (The text following the @samp{;} are comments. @xref{Change a
2479 defun, , Change a Function Definition}.)
2481 If you evaluate the first of these expressions, the initializer,
2482 @code{(setq counter 0)}, and then evaluate the third expression,
2483 @code{counter}, the number @code{0} will appear in the echo area. If
2484 you then evaluate the second expression, the incrementer, @code{(setq
2485 counter (+ counter 1))}, the counter will get the value 1. So if you
2486 again evaluate @code{counter}, the number @code{1} will appear in the
2487 echo area. Each time you evaluate the second expression, the value of
2488 the counter will be incremented.
2490 When you evaluate the incrementer, @code{(setq counter (+ counter 1))},
2491 the Lisp interpreter first evaluates the innermost list; this is the
2492 addition. In order to evaluate this list, it must evaluate the variable
2493 @code{counter} and the number @code{1}. When it evaluates the variable
2494 @code{counter}, it receives its current value. It passes this value and
2495 the number @code{1} to the @code{+} which adds them together. The sum
2496 is then returned as the value of the inner list and passed to the
2497 @code{setq} which sets the variable @code{counter} to this new value.
2498 Thus, the value of the variable, @code{counter}, is changed.
2500 @node Summary, Error Message Exercises, set & setq, List Processing
2501 @comment node-name, next, previous, up
2504 Learning Lisp is like climbing a hill in which the first part is the
2505 steepest. You have now climbed the most difficult part; what remains
2506 becomes easier as you progress onwards.
2514 Lisp programs are made up of expressions, which are lists or single atoms.
2517 Lists are made up of zero or more atoms or inner lists, separated by whitespace and
2518 surrounded by parentheses. A list can be empty.
2521 Atoms are multi-character symbols, like @code{forward-paragraph}, single
2522 character symbols like @code{+}, strings of characters between double
2523 quotation marks, or numbers.
2526 A number evaluates to itself.
2529 A string between double quotes also evaluates to itself.
2532 When you evaluate a symbol by itself, its value is returned.
2535 When you evaluate a list, the Lisp interpreter looks at the first symbol
2536 in the list and then at the function definition bound to that symbol.
2537 Then the instructions in the function definition are carried out.
2540 A single quotation mark,
2547 , tells the Lisp interpreter that it should
2548 return the following expression as written, and not evaluate it as it
2549 would if the quote were not there.
2552 Arguments are the information passed to a function. The arguments to a
2553 function are computed by evaluating the rest of the elements of the list
2554 of which the function is the first element.
2557 A function always returns a value when it is evaluated (unless it gets
2558 an error); in addition, it may also carry out some action called a
2559 ``side effect''. In many cases, a function's primary purpose is to
2560 create a side effect.
2563 @node Error Message Exercises, , Summary, List Processing
2564 @comment node-name, next, previous, up
2567 A few simple exercises:
2571 Generate an error message by evaluating an appropriate symbol that is
2572 not within parentheses.
2575 Generate an error message by evaluating an appropriate symbol that is
2576 between parentheses.
2579 Create a counter that increments by two rather than one.
2582 Write an expression that prints a message in the echo area when
2586 @node Practicing Evaluation, Writing Defuns, List Processing, Top
2587 @comment node-name, next, previous, up
2588 @chapter Practicing Evaluation
2589 @cindex Practicing evaluation
2590 @cindex Evaluation practice
2592 Before learning how to write a function definition in Emacs Lisp, it is
2593 useful to spend a little time evaluating various expressions that have
2594 already been written. These expressions will be lists with the
2595 functions as their first (and often only) element. Since some of the
2596 functions associated with buffers are both simple and interesting, we
2597 will start with those. In this section, we will evaluate a few of
2598 these. In another section, we will study the code of several other
2599 buffer-related functions, to see how they were written.
2605 * Switching Buffers::
2606 * Buffer Size & Locations::
2607 * Evaluation Exercise::
2610 @node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation
2612 @unnumberedsec How to Evaluate
2615 @i{Whenever you give an editing command} to Emacs Lisp, such as the
2616 command to move the cursor or to scroll the screen, @i{you are evaluating
2617 an expression,} the first element of which is a function. @i{This is
2620 @cindex @samp{interactive function} defined
2621 @cindex @samp{command} defined
2622 When you type keys, you cause the Lisp interpreter to evaluate an
2623 expression and that is how you get your results. Even typing plain text
2624 involves evaluating an Emacs Lisp function, in this case, one that uses
2625 @code{self-insert-command}, which simply inserts the character you
2626 typed. The functions you evaluate by typing keystrokes are called
2627 @dfn{interactive} functions, or @dfn{commands}; how you make a function
2628 interactive will be illustrated in the chapter on how to write function
2629 definitions. @xref{Interactive, , Making a Function Interactive}.
2631 In addition to typing keyboard commands, we have seen a second way to
2632 evaluate an expression: by positioning the cursor after a list and
2633 typing @kbd{C-x C-e}. This is what we will do in the rest of this
2634 section. There are other ways to evaluate an expression as well; these
2635 will be described as we come to them.
2637 Besides being used for practicing evaluation, the functions shown in the
2638 next few sections are important in their own right. A study of these
2639 functions makes clear the distinction between buffers and files, how to
2640 switch to a buffer, and how to determine a location within it.
2642 @node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation
2643 @comment node-name, next, previous, up
2644 @section Buffer Names
2646 @findex buffer-file-name
2648 The two functions, @code{buffer-name} and @code{buffer-file-name}, show
2649 the difference between a file and a buffer. When you evaluate the
2650 following expression, @code{(buffer-name)}, the name of the buffer
2651 appears in the echo area. When you evaluate @code{(buffer-file-name)},
2652 the name of the file to which the buffer refers appears in the echo
2653 area. Usually, the name returned by @code{(buffer-name)} is the same as
2654 the name of the file to which it refers, and the name returned by
2655 @code{(buffer-file-name)} is the full path-name of the file.
2657 A file and a buffer are two different entities. A file is information
2658 recorded permanently in the computer (unless you delete it). A buffer,
2659 on the other hand, is information inside of Emacs that will vanish at
2660 the end of the editing session (or when you kill the buffer). Usually,
2661 a buffer contains information that you have copied from a file; we say
2662 the buffer is @dfn{visiting} that file. This copy is what you work on
2663 and modify. Changes to the buffer do not change the file, until you
2664 save the buffer. When you save the buffer, the buffer is copied to the file
2665 and is thus saved permanently.
2668 If you are reading this in Info inside of GNU Emacs, you can evaluate
2669 each of the following expressions by positioning the cursor after it and
2670 typing @kbd{C-x C-e}.
2681 When I do this in Info, the value returned by evaluating
2682 @code{(buffer-name)} is @file{"*info*"}, and the value returned by
2683 evaluating @code{(buffer-file-name)} is @file{nil}.
2685 On the other hand, while I am writing this Introduction, the value
2686 returned by evaluating @code{(buffer-name)} is
2687 @file{"introduction.texinfo"}, and the value returned by evaluating
2688 @code{(buffer-file-name)} is
2689 @file{"/gnu/work/intro/introduction.texinfo"}.
2691 @cindex @code{nil}, history of word
2692 The former is the name of the buffer and the latter is the name of the
2693 file. In Info, the buffer name is @file{"*info*"}. Info does not
2694 point to any file, so the result of evaluating
2695 @code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is
2696 from the Latin word for `nothing'; in this case, it means that the
2697 buffer is not associated with any file. (In Lisp, @code{nil} is also
2698 used to mean `false' and is a synonym for the empty list, @code{()}.)
2700 When I am writing, the name of my buffer is
2701 @file{"introduction.texinfo"}. The name of the file to which it
2702 points is @file{"/gnu/work/intro/introduction.texinfo"}.
2704 (In the expressions, the parentheses tell the Lisp interpreter to
2705 treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as
2706 functions; without the parentheses, the interpreter would attempt to
2707 evaluate the symbols as variables. @xref{Variables}.)
2709 In spite of the distinction between files and buffers, you will often
2710 find that people refer to a file when they mean a buffer and vice-verse.
2711 Indeed, most people say, ``I am editing a file,'' rather than saying,
2712 ``I am editing a buffer which I will soon save to a file.'' It is
2713 almost always clear from context what people mean. When dealing with
2714 computer programs, however, it is important to keep the distinction in mind,
2715 since the computer is not as smart as a person.
2717 @cindex Buffer, history of word
2718 The word `buffer', by the way, comes from the meaning of the word as a
2719 cushion that deadens the force of a collision. In early computers, a
2720 buffer cushioned the interaction between files and the computer's
2721 central processing unit. The drums or tapes that held a file and the
2722 central processing unit were pieces of equipment that were very
2723 different from each other, working at their own speeds, in spurts. The
2724 buffer made it possible for them to work together effectively.
2725 Eventually, the buffer grew from being an intermediary, a temporary
2726 holding place, to being the place where work is done. This
2727 transformation is rather like that of a small seaport that grew into a
2728 great city: once it was merely the place where cargo was warehoused
2729 temporarily before being loaded onto ships; then it became a business
2730 and cultural center in its own right.
2732 Not all buffers are associated with files. For example, a
2733 @file{*scratch*} buffer does not visit any file. Similarly, a
2734 @file{*Help*} buffer is not associated with any file.
2736 In the old days, when you lacked a @file{~/.emacs} file and started an
2737 Emacs session by typing the command @code{emacs} alone, without naming
2738 any files, Emacs started with the @file{*scratch*} buffer visible.
2739 Nowadays, you will see a splash screen. You can follow one of the
2740 commands suggested on the splash screen, visit a file, or press the
2741 spacebar to reach the @file{*scratch*} buffer.
2743 If you switch to the @file{*scratch*} buffer, type
2744 @code{(buffer-name)}, position the cursor after it, and then type
2745 @kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"}
2746 will be returned and will appear in the echo area. @code{"*scratch*"}
2747 is the name of the buffer. When you type @code{(buffer-file-name)} in
2748 the @file{*scratch*} buffer and evaluate that, @code{nil} will appear
2749 in the echo area, just as it does when you evaluate
2750 @code{(buffer-file-name)} in Info.
2752 Incidentally, if you are in the @file{*scratch*} buffer and want the
2753 value returned by an expression to appear in the @file{*scratch*}
2754 buffer itself rather than in the echo area, type @kbd{C-u C-x C-e}
2755 instead of @kbd{C-x C-e}. This causes the value returned to appear
2756 after the expression. The buffer will look like this:
2759 (buffer-name)"*scratch*"
2763 You cannot do this in Info since Info is read-only and it will not allow
2764 you to change the contents of the buffer. But you can do this in any
2765 buffer you can edit; and when you write code or documentation (such as
2766 this book), this feature is very useful.
2768 @node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation
2769 @comment node-name, next, previous, up
2770 @section Getting Buffers
2771 @findex current-buffer
2772 @findex other-buffer
2773 @cindex Getting a buffer
2775 The @code{buffer-name} function returns the @emph{name} of the buffer;
2776 to get the buffer @emph{itself}, a different function is needed: the
2777 @code{current-buffer} function. If you use this function in code, what
2778 you get is the buffer itself.
2780 A name and the object or entity to which the name refers are different
2781 from each other. You are not your name. You are a person to whom
2782 others refer by name. If you ask to speak to George and someone hands you
2783 a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r},
2784 @samp{g}, and @samp{e} written on it, you might be amused, but you would
2785 not be satisfied. You do not want to speak to the name, but to the
2786 person to whom the name refers. A buffer is similar: the name of the
2787 scratch buffer is @file{*scratch*}, but the name is not the buffer. To
2788 get a buffer itself, you need to use a function such as
2789 @code{current-buffer}.
2791 However, there is a slight complication: if you evaluate
2792 @code{current-buffer} in an expression on its own, as we will do here,
2793 what you see is a printed representation of the name of the buffer
2794 without the contents of the buffer. Emacs works this way for two
2795 reasons: the buffer may be thousands of lines long---too long to be
2796 conveniently displayed; and, another buffer may have the same contents
2797 but a different name, and it is important to distinguish between them.
2800 Here is an expression containing the function:
2807 If you evaluate this expression in Info in Emacs in the usual way,
2808 @file{#<buffer *info*>} will appear in the echo area. The special
2809 format indicates that the buffer itself is being returned, rather than
2812 Incidentally, while you can type a number or symbol into a program, you
2813 cannot do that with the printed representation of a buffer: the only way
2814 to get a buffer itself is with a function such as @code{current-buffer}.
2816 A related function is @code{other-buffer}. This returns the most
2817 recently selected buffer other than the one you are in currently, not
2818 a printed representation of its name. If you have recently switched
2819 back and forth from the @file{*scratch*} buffer, @code{other-buffer}
2820 will return that buffer.
2823 You can see this by evaluating the expression:
2830 You should see @file{#<buffer *scratch*>} appear in the echo area, or
2831 the name of whatever other buffer you switched back from most
2832 recently@footnote{Actually, by default, if the buffer from which you
2833 just switched is visible to you in another window, @code{other-buffer}
2834 will choose the most recent buffer that you cannot see; this is a
2835 subtlety that I often forget.}.
2837 @node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation
2838 @comment node-name, next, previous, up
2839 @section Switching Buffers
2840 @findex switch-to-buffer
2842 @cindex Switching to a buffer
2844 The @code{other-buffer} function actually provides a buffer when it is
2845 used as an argument to a function that requires one. We can see this
2846 by using @code{other-buffer} and @code{switch-to-buffer} to switch to a
2849 But first, a brief introduction to the @code{switch-to-buffer}
2850 function. When you switched back and forth from Info to the
2851 @file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most
2852 likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or
2853 rather, to save typing, you probably only typed @kbd{RET} if the
2854 default buffer was @file{*scratch*}, or if it was different, then you
2855 typed just part of the name, such as @code{*sc}, pressed your
2856 @kbd{TAB} key to cause it to expand to the full name, and then typed
2857 your @kbd{RET} key.} when prompted in the minibuffer for the name of
2858 the buffer to which you wanted to switch. The keystrokes, @kbd{C-x
2859 b}, cause the Lisp interpreter to evaluate the interactive function
2860 @code{switch-to-buffer}. As we said before, this is how Emacs works:
2861 different keystrokes call or run different functions. For example,
2862 @kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls
2863 @code{forward-sentence}, and so on.
2865 By writing @code{switch-to-buffer} in an expression, and giving it a
2866 buffer to switch to, we can switch buffers just the way @kbd{C-x b}
2870 Here is the Lisp expression:
2873 (switch-to-buffer (other-buffer))
2877 The symbol @code{switch-to-buffer} is the first element of the list,
2878 so the Lisp interpreter will treat it as a function and carry out the
2879 instructions that are attached to it. But before doing that, the
2880 interpreter will note that @code{other-buffer} is inside parentheses
2881 and work on that symbol first. @code{other-buffer} is the first (and
2882 in this case, the only) element of this list, so the Lisp interpreter
2883 calls or runs the function. It returns another buffer. Next, the
2884 interpreter runs @code{switch-to-buffer}, passing to it, as an
2885 argument, the other buffer, which is what Emacs will switch to. If
2886 you are reading this in Info, try this now. Evaluate the expression.
2887 (To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this
2888 expression will move you to your most recent other buffer that you
2889 cannot see. If you really want to go to your most recently selected
2890 buffer, even if you can still see it, you need to evaluate the
2891 following more complex expression:
2894 (switch-to-buffer (other-buffer (current-buffer) t))
2898 In this case, the first argument to @code{other-buffer} tells it which
2899 buffer to skip---the current one---and the second argument tells
2900 @code{other-buffer} it is OK to switch to a visible buffer.
2901 In regular use, @code{switch-to-buffer} takes you to an invisible
2902 window since you would most likely use @kbd{C-x o} (@code{other-window})
2903 to go to another visible buffer.}
2905 In the programming examples in later sections of this document, you will
2906 see the function @code{set-buffer} more often than
2907 @code{switch-to-buffer}. This is because of a difference between
2908 computer programs and humans: humans have eyes and expect to see the
2909 buffer on which they are working on their computer terminals. This is
2910 so obvious, it almost goes without saying. However, programs do not
2911 have eyes. When a computer program works on a buffer, that buffer does
2912 not need to be visible on the screen.
2914 @code{switch-to-buffer} is designed for humans and does two different
2915 things: it switches the buffer to which Emacs' attention is directed; and
2916 it switches the buffer displayed in the window to the new buffer.
2917 @code{set-buffer}, on the other hand, does only one thing: it switches
2918 the attention of the computer program to a different buffer. The buffer
2919 on the screen remains unchanged (of course, normally nothing happens
2920 there until the command finishes running).
2922 @cindex @samp{call} defined
2923 Also, we have just introduced another jargon term, the word @dfn{call}.
2924 When you evaluate a list in which the first symbol is a function, you
2925 are calling that function. The use of the term comes from the notion of
2926 the function as an entity that can do something for you if you `call'
2927 it---just as a plumber is an entity who can fix a leak if you call him
2930 @node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation
2931 @comment node-name, next, previous, up
2932 @section Buffer Size and the Location of Point
2933 @cindex Size of buffer
2935 @cindex Point location
2936 @cindex Location of point
2938 Finally, let's look at several rather simple functions,
2939 @code{buffer-size}, @code{point}, @code{point-min}, and
2940 @code{point-max}. These give information about the size of a buffer and
2941 the location of point within it.
2943 The function @code{buffer-size} tells you the size of the current
2944 buffer; that is, the function returns a count of the number of
2945 characters in the buffer.
2952 You can evaluate this in the usual way, by positioning the
2953 cursor after the expression and typing @kbd{C-x C-e}.
2955 @cindex @samp{point} defined
2956 In Emacs, the current position of the cursor is called @dfn{point}.
2957 The expression @code{(point)} returns a number that tells you where the
2958 cursor is located as a count of the number of characters from the
2959 beginning of the buffer up to point.
2962 You can see the character count for point in this buffer by evaluating
2963 the following expression in the usual way:
2970 As I write this, the value of @code{point} is 65724. The @code{point}
2971 function is frequently used in some of the examples later in this
2975 The value of point depends, of course, on its location within the
2976 buffer. If you evaluate point in this spot, the number will be larger:
2983 For me, the value of point in this location is 66043, which means that
2984 there are 319 characters (including spaces) between the two expressions.
2986 @cindex @samp{narrowing} defined
2987 The function @code{point-min} is somewhat similar to @code{point}, but
2988 it returns the value of the minimum permissible value of point in the
2989 current buffer. This is the number 1 unless @dfn{narrowing} is in
2990 effect. (Narrowing is a mechanism whereby you can restrict yourself,
2991 or a program, to operations on just a part of a buffer.
2992 @xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the
2993 function @code{point-max} returns the value of the maximum permissible
2994 value of point in the current buffer.
2996 @node Evaluation Exercise, , Buffer Size & Locations, Practicing Evaluation
2999 Find a file with which you are working and move towards its middle.
3000 Find its buffer name, file name, length, and your position in the file.
3002 @node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top
3003 @comment node-name, next, previous, up
3004 @chapter How To Write Function Definitions
3005 @cindex Definition writing
3006 @cindex Function definition writing
3007 @cindex Writing a function definition
3009 When the Lisp interpreter evaluates a list, it looks to see whether the
3010 first symbol on the list has a function definition attached to it; or,
3011 put another way, whether the symbol points to a function definition. If
3012 it does, the computer carries out the instructions in the definition. A
3013 symbol that has a function definition is called, simply, a function
3014 (although, properly speaking, the definition is the function and the
3015 symbol refers to it.)
3018 * Primitive Functions::
3022 * Interactive Options::
3023 * Permanent Installation::
3027 * Truth & Falsehood::
3033 @node Primitive Functions, defun, Writing Defuns, Writing Defuns
3035 @unnumberedsec An Aside about Primitive Functions
3037 @cindex Primitive functions
3038 @cindex Functions, primitive
3040 @cindex C language primitives
3041 @cindex Primitives written in C
3042 All functions are defined in terms of other functions, except for a few
3043 @dfn{primitive} functions that are written in the C programming
3044 language. When you write functions' definitions, you will write them in
3045 Emacs Lisp and use other functions as your building blocks. Some of the
3046 functions you will use will themselves be written in Emacs Lisp (perhaps
3047 by you) and some will be primitives written in C. The primitive
3048 functions are used exactly like those written in Emacs Lisp and behave
3049 like them. They are written in C so we can easily run GNU Emacs on any
3050 computer that has sufficient power and can run C.
3052 Let me re-emphasize this: when you write code in Emacs Lisp, you do not
3053 distinguish between the use of functions written in C and the use of
3054 functions written in Emacs Lisp. The difference is irrelevant. I
3055 mention the distinction only because it is interesting to know. Indeed,
3056 unless you investigate, you won't know whether an already-written
3057 function is written in Emacs Lisp or C.
3059 @node defun, Install, Primitive Functions, Writing Defuns
3060 @comment node-name, next, previous, up
3061 @section The @code{defun} Special Form
3063 @cindex Special form of @code{defun}
3065 @cindex @samp{function definition} defined
3066 In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to
3067 it that tells the computer what to do when the function is called.
3068 This code is called the @dfn{function definition} and is created by
3069 evaluating a Lisp expression that starts with the symbol @code{defun}
3070 (which is an abbreviation for @emph{define function}). Because
3071 @code{defun} does not evaluate its arguments in the usual way, it is
3072 called a @dfn{special form}.
3074 In subsequent sections, we will look at function definitions from the
3075 Emacs source code, such as @code{mark-whole-buffer}. In this section,
3076 we will describe a simple function definition so you can see how it
3077 looks. This function definition uses arithmetic because it makes for a
3078 simple example. Some people dislike examples using arithmetic; however,
3079 if you are such a person, do not despair. Hardly any of the code we
3080 will study in the remainder of this introduction involves arithmetic or
3081 mathematics. The examples mostly involve text in one way or another.
3083 A function definition has up to five parts following the word
3088 The name of the symbol to which the function definition should be
3092 A list of the arguments that will be passed to the function. If no
3093 arguments will be passed to the function, this is an empty list,
3097 Documentation describing the function. (Technically optional, but
3098 strongly recommended.)
3101 Optionally, an expression to make the function interactive so you can
3102 use it by typing @kbd{M-x} and then the name of the function; or by
3103 typing an appropriate key or keychord.
3105 @cindex @samp{body} defined
3107 The code that instructs the computer what to do: the @dfn{body} of the
3108 function definition.
3111 It is helpful to think of the five parts of a function definition as
3112 being organized in a template, with slots for each part:
3116 (defun @var{function-name} (@var{arguments}@dots{})
3117 "@var{optional-documentation}@dots{}"
3118 (interactive @var{argument-passing-info}) ; @r{optional}
3123 As an example, here is the code for a function that multiplies its
3124 argument by 7. (This example is not interactive. @xref{Interactive,
3125 , Making a Function Interactive}, for that information.)
3129 (defun multiply-by-seven (number)
3130 "Multiply NUMBER by seven."
3135 This definition begins with a parenthesis and the symbol @code{defun},
3136 followed by the name of the function.
3138 @cindex @samp{argument list} defined
3139 The name of the function is followed by a list that contains the
3140 arguments that will be passed to the function. This list is called
3141 the @dfn{argument list}. In this example, the list has only one
3142 element, the symbol, @code{number}. When the function is used, the
3143 symbol will be bound to the value that is used as the argument to the
3146 Instead of choosing the word @code{number} for the name of the argument,
3147 I could have picked any other name. For example, I could have chosen
3148 the word @code{multiplicand}. I picked the word `number' because it
3149 tells what kind of value is intended for this slot; but I could just as
3150 well have chosen the word `multiplicand' to indicate the role that the
3151 value placed in this slot will play in the workings of the function. I
3152 could have called it @code{foogle}, but that would have been a bad
3153 choice because it would not tell humans what it means. The choice of
3154 name is up to the programmer and should be chosen to make the meaning of
3157 Indeed, you can choose any name you wish for a symbol in an argument
3158 list, even the name of a symbol used in some other function: the name
3159 you use in an argument list is private to that particular definition.
3160 In that definition, the name refers to a different entity than any use
3161 of the same name outside the function definition. Suppose you have a
3162 nick-name `Shorty' in your family; when your family members refer to
3163 `Shorty', they mean you. But outside your family, in a movie, for
3164 example, the name `Shorty' refers to someone else. Because a name in an
3165 argument list is private to the function definition, you can change the
3166 value of such a symbol inside the body of a function without changing
3167 its value outside the function. The effect is similar to that produced
3168 by a @code{let} expression. (@xref{let, , @code{let}}.)
3171 Note also that we discuss the word `number' in two different ways: as a
3172 symbol that appears in the code, and as the name of something that will
3173 be replaced by a something else during the evaluation of the function.
3174 In the first case, @code{number} is a symbol, not a number; it happens
3175 that within the function, it is a variable who value is the number in
3176 question, but our primary interest in it is as a symbol. On the other
3177 hand, when we are talking about the function, our interest is that we
3178 will substitute a number for the word @var{number}. To keep this
3179 distinction clear, we use different typography for the two
3180 circumstances. When we talk about this function, or about how it works,
3181 we refer to this number by writing @var{number}. In the function
3182 itself, we refer to it by writing @code{number}.
3185 The argument list is followed by the documentation string that
3186 describes the function. This is what you see when you type
3187 @w{@kbd{C-h f}} and the name of a function. Incidentally, when you
3188 write a documentation string like this, you should make the first line
3189 a complete sentence since some commands, such as @code{apropos}, print
3190 only the first line of a multi-line documentation string. Also, you
3191 should not indent the second line of a documentation string, if you
3192 have one, because that looks odd when you use @kbd{C-h f}
3193 (@code{describe-function}). The documentation string is optional, but
3194 it is so useful, it should be included in almost every function you
3197 @findex * @r{(multiplication)}
3198 The third line of the example consists of the body of the function
3199 definition. (Most functions' definitions, of course, are longer than
3200 this.) In this function, the body is the list, @code{(* 7 number)}, which
3201 says to multiply the value of @var{number} by 7. (In Emacs Lisp,
3202 @code{*} is the function for multiplication, just as @code{+} is the
3203 function for addition.)
3205 When you use the @code{multiply-by-seven} function, the argument
3206 @code{number} evaluates to the actual number you want used. Here is an
3207 example that shows how @code{multiply-by-seven} is used; but don't try
3208 to evaluate this yet!
3211 (multiply-by-seven 3)
3215 The symbol @code{number}, specified in the function definition in the
3216 next section, is given or ``bound to'' the value 3 in the actual use of
3217 the function. Note that although @code{number} was inside parentheses
3218 in the function definition, the argument passed to the
3219 @code{multiply-by-seven} function is not in parentheses. The
3220 parentheses are written in the function definition so the computer can
3221 figure out where the argument list ends and the rest of the function
3224 If you evaluate this example, you are likely to get an error message.
3225 (Go ahead, try it!) This is because we have written the function
3226 definition, but not yet told the computer about the definition---we have
3227 not yet installed (or `loaded') the function definition in Emacs.
3228 Installing a function is the process that tells the Lisp interpreter the
3229 definition of the function. Installation is described in the next
3232 @node Install, Interactive, defun, Writing Defuns
3233 @comment node-name, next, previous, up
3234 @section Install a Function Definition
3235 @cindex Install a Function Definition
3236 @cindex Definition installation
3237 @cindex Function definition installation
3239 If you are reading this inside of Info in Emacs, you can try out the
3240 @code{multiply-by-seven} function by first evaluating the function
3241 definition and then evaluating @code{(multiply-by-seven 3)}. A copy of
3242 the function definition follows. Place the cursor after the last
3243 parenthesis of the function definition and type @kbd{C-x C-e}. When you
3244 do this, @code{multiply-by-seven} will appear in the echo area. (What
3245 this means is that when a function definition is evaluated, the value it
3246 returns is the name of the defined function.) At the same time, this
3247 action installs the function definition.
3251 (defun multiply-by-seven (number)
3252 "Multiply NUMBER by seven."
3258 By evaluating this @code{defun}, you have just installed
3259 @code{multiply-by-seven} in Emacs. The function is now just as much a
3260 part of Emacs as @code{forward-word} or any other editing function you
3261 use. (@code{multiply-by-seven} will stay installed until you quit
3262 Emacs. To reload code automatically whenever you start Emacs, see
3263 @ref{Permanent Installation, , Installing Code Permanently}.)
3266 * Effect of installation::
3270 @node Effect of installation, Change a defun, Install, Install
3272 @unnumberedsubsec The effect of installation
3275 You can see the effect of installing @code{multiply-by-seven} by
3276 evaluating the following sample. Place the cursor after the following
3277 expression and type @kbd{C-x C-e}. The number 21 will appear in the
3281 (multiply-by-seven 3)
3284 If you wish, you can read the documentation for the function by typing
3285 @kbd{C-h f} (@code{describe-function}) and then the name of the
3286 function, @code{multiply-by-seven}. When you do this, a
3287 @file{*Help*} window will appear on your screen that says:
3291 multiply-by-seven is a Lisp function.
3292 (multiply-by-seven NUMBER)
3294 Multiply NUMBER by seven.
3299 (To return to a single window on your screen, type @kbd{C-x 1}.)
3301 @node Change a defun, , Effect of installation, Install
3302 @comment node-name, next, previous, up
3303 @subsection Change a Function Definition
3304 @cindex Changing a function definition
3305 @cindex Function definition, how to change
3306 @cindex Definition, how to change
3308 If you want to change the code in @code{multiply-by-seven}, just rewrite
3309 it. To install the new version in place of the old one, evaluate the
3310 function definition again. This is how you modify code in Emacs. It is
3313 As an example, you can change the @code{multiply-by-seven} function to
3314 add the number to itself seven times instead of multiplying the number
3315 by seven. It produces the same answer, but by a different path. At
3316 the same time, we will add a comment to the code; a comment is text
3317 that the Lisp interpreter ignores, but that a human reader may find
3318 useful or enlightening. The comment is that this is the ``second
3323 (defun multiply-by-seven (number) ; @r{Second version.}
3324 "Multiply NUMBER by seven."
3325 (+ number number number number number number number))
3329 @cindex Comments in Lisp code
3330 The comment follows a semicolon, @samp{;}. In Lisp, everything on a
3331 line that follows a semicolon is a comment. The end of the line is the
3332 end of the comment. To stretch a comment over two or more lines, begin
3333 each line with a semicolon.
3335 @xref{Beginning a .emacs File, , Beginning a @file{.emacs}
3336 File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp
3337 Reference Manual}, for more about comments.
3339 You can install this version of the @code{multiply-by-seven} function by
3340 evaluating it in the same way you evaluated the first function: place
3341 the cursor after the last parenthesis and type @kbd{C-x C-e}.
3343 In summary, this is how you write code in Emacs Lisp: you write a
3344 function; install it; test it; and then make fixes or enhancements and
3347 @node Interactive, Interactive Options, Install, Writing Defuns
3348 @comment node-name, next, previous, up
3349 @section Make a Function Interactive
3350 @cindex Interactive functions
3353 You make a function interactive by placing a list that begins with
3354 the special form @code{interactive} immediately after the
3355 documentation. A user can invoke an interactive function by typing
3356 @kbd{M-x} and then the name of the function; or by typing the keys to
3357 which it is bound, for example, by typing @kbd{C-n} for
3358 @code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}.
3360 Interestingly, when you call an interactive function interactively,
3361 the value returned is not automatically displayed in the echo area.
3362 This is because you often call an interactive function for its side
3363 effects, such as moving forward by a word or line, and not for the
3364 value returned. If the returned value were displayed in the echo area
3365 each time you typed a key, it would be very distracting.
3368 * Interactive multiply-by-seven::
3369 * multiply-by-seven in detail::
3372 @node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive
3374 @unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview
3377 Both the use of the special form @code{interactive} and one way to
3378 display a value in the echo area can be illustrated by creating an
3379 interactive version of @code{multiply-by-seven}.
3386 (defun multiply-by-seven (number) ; @r{Interactive version.}
3387 "Multiply NUMBER by seven."
3389 (message "The result is %d" (* 7 number)))
3394 You can install this code by placing your cursor after it and typing
3395 @kbd{C-x C-e}. The name of the function will appear in your echo area.
3396 Then, you can use this code by typing @kbd{C-u} and a number and then
3397 typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase
3398 @samp{The result is @dots{}} followed by the product will appear in the
3401 Speaking more generally, you invoke a function like this in either of two
3406 By typing a prefix argument that contains the number to be passed, and
3407 then typing @kbd{M-x} and the name of the function, as with
3408 @kbd{C-u 3 M-x forward-sentence}; or,
3411 By typing whatever key or keychord the function is bound to, as with
3416 Both the examples just mentioned work identically to move point forward
3417 three sentences. (Since @code{multiply-by-seven} is not bound to a key,
3418 it could not be used as an example of key binding.)
3420 (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command
3423 A prefix argument is passed to an interactive function by typing the
3424 @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by
3425 typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you
3426 type @kbd{C-u} without a number, it defaults to 4).
3428 @node multiply-by-seven in detail, , Interactive multiply-by-seven, Interactive
3429 @comment node-name, next, previous, up
3430 @subsection An Interactive @code{multiply-by-seven}
3432 Let's look at the use of the special form @code{interactive} and then at
3433 the function @code{message} in the interactive version of
3434 @code{multiply-by-seven}. You will recall that the function definition
3439 (defun multiply-by-seven (number) ; @r{Interactive version.}
3440 "Multiply NUMBER by seven."
3442 (message "The result is %d" (* 7 number)))
3446 In this function, the expression, @code{(interactive "p")}, is a list of
3447 two elements. The @code{"p"} tells Emacs to pass the prefix argument to
3448 the function and use its value for the argument of the function.
3451 The argument will be a number. This means that the symbol
3452 @code{number} will be bound to a number in the line:
3455 (message "The result is %d" (* 7 number))
3460 For example, if your prefix argument is 5, the Lisp interpreter will
3461 evaluate the line as if it were:
3464 (message "The result is %d" (* 7 5))
3468 (If you are reading this in GNU Emacs, you can evaluate this expression
3469 yourself.) First, the interpreter will evaluate the inner list, which
3470 is @code{(* 7 5)}. This returns a value of 35. Next, it
3471 will evaluate the outer list, passing the values of the second and
3472 subsequent elements of the list to the function @code{message}.
3474 As we have seen, @code{message} is an Emacs Lisp function especially
3475 designed for sending a one line message to a user. (@xref{message, ,
3476 The @code{message} function}.) In summary, the @code{message}
3477 function prints its first argument in the echo area as is, except for
3478 occurrences of @samp{%d} or @samp{%s} (and various other %-sequences
3479 which we have not mentioned). When it sees a control sequence, the
3480 function looks to the second or subsequent arguments and prints the
3481 value of the argument in the location in the string where the control
3482 sequence is located.
3484 In the interactive @code{multiply-by-seven} function, the control string
3485 is @samp{%d}, which requires a number, and the value returned by
3486 evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35
3487 is printed in place of the @samp{%d} and the message is @samp{The result
3490 (Note that when you call the function @code{multiply-by-seven}, the
3491 message is printed without quotes, but when you call @code{message}, the
3492 text is printed in double quotes. This is because the value returned by
3493 @code{message} is what appears in the echo area when you evaluate an
3494 expression whose first element is @code{message}; but when embedded in a
3495 function, @code{message} prints the text as a side effect without
3498 @node Interactive Options, Permanent Installation, Interactive, Writing Defuns
3499 @comment node-name, next, previous, up
3500 @section Different Options for @code{interactive}
3501 @cindex Options for @code{interactive}
3502 @cindex Interactive options
3504 In the example, @code{multiply-by-seven} used @code{"p"} as the
3505 argument to @code{interactive}. This argument told Emacs to interpret
3506 your typing either @kbd{C-u} followed by a number or @key{META}
3507 followed by a number as a command to pass that number to the function
3508 as its argument. Emacs has more than twenty characters predefined for
3509 use with @code{interactive}. In almost every case, one of these
3510 options will enable you to pass the right information interactively to
3511 a function. (@xref{Interactive Codes, , Code Characters for
3512 @code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.)
3515 Consider the function @code{zap-to-char}. Its interactive expression
3519 (interactive "p\ncZap to char: ")
3522 The first part of the argument to @code{interactive} is @samp{p}, with
3523 which you are already familiar. This argument tells Emacs to
3524 interpret a `prefix', as a number to be passed to the function. You
3525 can specify a prefix either by typing @kbd{C-u} followed by a number
3526 or by typing @key{META} followed by a number. The prefix is the
3527 number of specified characters. Thus, if your prefix is three and the
3528 specified character is @samp{x}, then you will delete all the text up
3529 to and including the third next @samp{x}. If you do not set a prefix,
3530 then you delete all the text up to and including the specified
3531 character, but no more.
3533 The @samp{c} tells the function the name of the character to which to delete.
3535 More formally, a function with two or more arguments can have
3536 information passed to each argument by adding parts to the string that
3537 follows @code{interactive}. When you do this, the information is
3538 passed to each argument in the same order it is specified in the
3539 @code{interactive} list. In the string, each part is separated from
3540 the next part by a @samp{\n}, which is a newline. For example, you
3541 can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }.
3542 This causes Emacs to pass the value of the prefix argument (if there
3543 is one) and the character.
3545 In this case, the function definition looks like the following, where
3546 @code{arg} and @code{char} are the symbols to which @code{interactive}
3547 binds the prefix argument and the specified character:
3551 (defun @var{name-of-function} (arg char)
3552 "@var{documentation}@dots{}"
3553 (interactive "p\ncZap to char: ")
3554 @var{body-of-function}@dots{})
3559 (The space after the colon in the prompt makes it look better when you
3560 are prompted. @xref{copy-to-buffer, , The Definition of
3561 @code{copy-to-buffer}}, for an example.)
3563 When a function does not take arguments, @code{interactive} does not
3564 require any. Such a function contains the simple expression
3565 @code{(interactive)}. The @code{mark-whole-buffer} function is like
3568 Alternatively, if the special letter-codes are not right for your
3569 application, you can pass your own arguments to @code{interactive} as
3572 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}},
3573 for an example. @xref{Using Interactive, , Using @code{Interactive},
3574 elisp, The GNU Emacs Lisp Reference Manual}, for a more complete
3575 explanation about this technique.
3577 @node Permanent Installation, let, Interactive Options, Writing Defuns
3578 @comment node-name, next, previous, up
3579 @section Install Code Permanently
3580 @cindex Install code permanently
3581 @cindex Permanent code installation
3582 @cindex Code installation
3584 When you install a function definition by evaluating it, it will stay
3585 installed until you quit Emacs. The next time you start a new session
3586 of Emacs, the function will not be installed unless you evaluate the
3587 function definition again.
3589 At some point, you may want to have code installed automatically
3590 whenever you start a new session of Emacs. There are several ways of
3595 If you have code that is just for yourself, you can put the code for the
3596 function definition in your @file{.emacs} initialization file. When you
3597 start Emacs, your @file{.emacs} file is automatically evaluated and all
3598 the function definitions within it are installed.
3599 @xref{Emacs Initialization, , Your @file{.emacs} File}.
3602 Alternatively, you can put the function definitions that you want
3603 installed in one or more files of their own and use the @code{load}
3604 function to cause Emacs to evaluate and thereby install each of the
3605 functions in the files.
3606 @xref{Loading Files, , Loading Files}.
3609 Thirdly, if you have code that your whole site will use, it is usual
3610 to put it in a file called @file{site-init.el} that is loaded when
3611 Emacs is built. This makes the code available to everyone who uses
3612 your machine. (See the @file{INSTALL} file that is part of the Emacs
3616 Finally, if you have code that everyone who uses Emacs may want, you
3617 can post it on a computer network or send a copy to the Free Software
3618 Foundation. (When you do this, please license the code and its
3619 documentation under a license that permits other people to run, copy,
3620 study, modify, and redistribute the code and which protects you from
3621 having your work taken from you.) If you send a copy of your code to
3622 the Free Software Foundation, and properly protect yourself and
3623 others, it may be included in the next release of Emacs. In large
3624 part, this is how Emacs has grown over the past years, by donations.
3626 @node let, if, Permanent Installation, Writing Defuns
3627 @comment node-name, next, previous, up
3631 The @code{let} expression is a special form in Lisp that you will need
3632 to use in most function definitions.
3634 @code{let} is used to attach or bind a symbol to a value in such a way
3635 that the Lisp interpreter will not confuse the variable with a
3636 variable of the same name that is not part of the function.
3638 To understand why the @code{let} special form is necessary, consider
3639 the situation in which you own a home that you generally refer to as
3640 `the house', as in the sentence, ``The house needs painting.'' If you
3641 are visiting a friend and your host refers to `the house', he is
3642 likely to be referring to @emph{his} house, not yours, that is, to a
3645 If your friend is referring to his house and you think he is referring
3646 to your house, you may be in for some confusion. The same thing could
3647 happen in Lisp if a variable that is used inside of one function has
3648 the same name as a variable that is used inside of another function,
3649 and the two are not intended to refer to the same value. The
3650 @code{let} special form prevents this kind of confusion.
3653 * Prevent confusion::
3654 * Parts of let Expression::
3655 * Sample let Expression::
3656 * Uninitialized let Variables::
3659 @node Prevent confusion, Parts of let Expression, let, let
3661 @unnumberedsubsec @code{let} Prevents Confusion
3664 @cindex @samp{local variable} defined
3665 @cindex @samp{variable, local}, defined
3666 The @code{let} special form prevents confusion. @code{let} creates a
3667 name for a @dfn{local variable} that overshadows any use of the same
3668 name outside the @code{let} expression. This is like understanding
3669 that whenever your host refers to `the house', he means his house, not
3670 yours. (Symbols used in argument lists work the same way.
3671 @xref{defun, , The @code{defun} Special Form}.)
3673 Local variables created by a @code{let} expression retain their value
3674 @emph{only} within the @code{let} expression itself (and within
3675 expressions called within the @code{let} expression); the local
3676 variables have no effect outside the @code{let} expression.
3678 Another way to think about @code{let} is that it is like a @code{setq}
3679 that is temporary and local. The values set by @code{let} are
3680 automatically undone when the @code{let} is finished. The setting
3681 only affects expressions that are inside the bounds of the @code{let}
3682 expression. In computer science jargon, we would say ``the binding of
3683 a symbol is visible only in functions called in the @code{let} form;
3684 in Emacs Lisp, scoping is dynamic, not lexical.''
3686 @code{let} can create more than one variable at once. Also,
3687 @code{let} gives each variable it creates an initial value, either a
3688 value specified by you, or @code{nil}. (In the jargon, this is called
3689 `binding the variable to the value'.) After @code{let} has created
3690 and bound the variables, it executes the code in the body of the
3691 @code{let}, and returns the value of the last expression in the body,
3692 as the value of the whole @code{let} expression. (`Execute' is a jargon
3693 term that means to evaluate a list; it comes from the use of the word
3694 meaning `to give practical effect to' (@cite{Oxford English
3695 Dictionary}). Since you evaluate an expression to perform an action,
3696 `execute' has evolved as a synonym to `evaluate'.)
3698 @node Parts of let Expression, Sample let Expression, Prevent confusion, let
3699 @comment node-name, next, previous, up
3700 @subsection The Parts of a @code{let} Expression
3701 @cindex @code{let} expression, parts of
3702 @cindex Parts of @code{let} expression
3704 @cindex @samp{varlist} defined
3705 A @code{let} expression is a list of three parts. The first part is
3706 the symbol @code{let}. The second part is a list, called a
3707 @dfn{varlist}, each element of which is either a symbol by itself or a
3708 two-element list, the first element of which is a symbol. The third
3709 part of the @code{let} expression is the body of the @code{let}. The
3710 body usually consists of one or more lists.
3713 A template for a @code{let} expression looks like this:
3716 (let @var{varlist} @var{body}@dots{})
3720 The symbols in the varlist are the variables that are given initial
3721 values by the @code{let} special form. Symbols by themselves are given
3722 the initial value of @code{nil}; and each symbol that is the first
3723 element of a two-element list is bound to the value that is returned
3724 when the Lisp interpreter evaluates the second element.
3726 Thus, a varlist might look like this: @code{(thread (needles 3))}. In
3727 this case, in a @code{let} expression, Emacs binds the symbol
3728 @code{thread} to an initial value of @code{nil}, and binds the symbol
3729 @code{needles} to an initial value of 3.
3731 When you write a @code{let} expression, what you do is put the
3732 appropriate expressions in the slots of the @code{let} expression
3735 If the varlist is composed of two-element lists, as is often the case,
3736 the template for the @code{let} expression looks like this:
3740 (let ((@var{variable} @var{value})
3741 (@var{variable} @var{value})
3747 @node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let
3748 @comment node-name, next, previous, up
3749 @subsection Sample @code{let} Expression
3750 @cindex Sample @code{let} expression
3751 @cindex @code{let} expression sample
3753 The following expression creates and gives initial values
3754 to the two variables @code{zebra} and @code{tiger}. The body of the
3755 @code{let} expression is a list which calls the @code{message} function.
3759 (let ((zebra 'stripes)
3761 (message "One kind of animal has %s and another is %s."
3766 Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}.
3768 The two variables are @code{zebra} and @code{tiger}. Each variable is
3769 the first element of a two-element list and each value is the second
3770 element of its two-element list. In the varlist, Emacs binds the
3771 variable @code{zebra} to the value @code{stripes}@footnote{According
3772 to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras
3773 become impossibly dangerous as they grow older'' but the claim here is
3774 that they do not become fierce like a tiger. (1997, W. W. Norton and
3775 Co., ISBN 0-393-03894-2, page 171)}, and binds the
3776 variable @code{tiger} to the value @code{fierce}. In this example,
3777 both values are symbols preceded by a quote. The values could just as
3778 well have been another list or a string. The body of the @code{let}
3779 follows after the list holding the variables. In this example, the
3780 body is a list that uses the @code{message} function to print a string
3784 You may evaluate the example in the usual fashion, by placing the
3785 cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do
3786 this, the following will appear in the echo area:
3789 "One kind of animal has stripes and another is fierce."
3792 As we have seen before, the @code{message} function prints its first
3793 argument, except for @samp{%s}. In this example, the value of the variable
3794 @code{zebra} is printed at the location of the first @samp{%s} and the
3795 value of the variable @code{tiger} is printed at the location of the
3798 @node Uninitialized let Variables, , Sample let Expression, let
3799 @comment node-name, next, previous, up
3800 @subsection Uninitialized Variables in a @code{let} Statement
3801 @cindex Uninitialized @code{let} variables
3802 @cindex @code{let} variables uninitialized
3804 If you do not bind the variables in a @code{let} statement to specific
3805 initial values, they will automatically be bound to an initial value of
3806 @code{nil}, as in the following expression:
3815 "Here are %d variables with %s, %s, and %s value."
3816 birch pine fir oak))
3821 Here, the varlist is @code{((birch 3) pine fir (oak 'some))}.
3824 If you evaluate this expression in the usual way, the following will
3825 appear in your echo area:
3828 "Here are 3 variables with nil, nil, and some value."
3832 In this example, Emacs binds the symbol @code{birch} to the number 3,
3833 binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds
3834 the symbol @code{oak} to the value @code{some}.
3836 Note that in the first part of the @code{let}, the variables @code{pine}
3837 and @code{fir} stand alone as atoms that are not surrounded by
3838 parentheses; this is because they are being bound to @code{nil}, the
3839 empty list. But @code{oak} is bound to @code{some} and so is a part of
3840 the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the
3841 number 3 and so is in a list with that number. (Since a number
3842 evaluates to itself, the number does not need to be quoted. Also, the
3843 number is printed in the message using a @samp{%d} rather than a
3844 @samp{%s}.) The four variables as a group are put into a list to
3845 delimit them from the body of the @code{let}.
3847 @node if, else, let, Writing Defuns
3848 @comment node-name, next, previous, up
3849 @section The @code{if} Special Form
3851 @cindex Conditional with @code{if}
3853 A third special form, in addition to @code{defun} and @code{let}, is the
3854 conditional @code{if}. This form is used to instruct the computer to
3855 make decisions. You can write function definitions without using
3856 @code{if}, but it is used often enough, and is important enough, to be
3857 included here. It is used, for example, in the code for the
3858 function @code{beginning-of-buffer}.
3860 The basic idea behind an @code{if}, is that ``@emph{if} a test is true,
3861 @emph{then} an expression is evaluated.'' If the test is not true, the
3862 expression is not evaluated. For example, you might make a decision
3863 such as, ``if it is warm and sunny, then go to the beach!''
3866 * if in more detail::
3867 * type-of-animal in detail::
3870 @node if in more detail, type-of-animal in detail, if, if
3872 @unnumberedsubsec @code{if} in more detail
3875 @cindex @samp{if-part} defined
3876 @cindex @samp{then-part} defined
3877 An @code{if} expression written in Lisp does not use the word `then';
3878 the test and the action are the second and third elements of the list
3879 whose first element is @code{if}. Nonetheless, the test part of an
3880 @code{if} expression is often called the @dfn{if-part} and the second
3881 argument is often called the @dfn{then-part}.
3883 Also, when an @code{if} expression is written, the true-or-false-test
3884 is usually written on the same line as the symbol @code{if}, but the
3885 action to carry out if the test is true, the ``then-part'', is written
3886 on the second and subsequent lines. This makes the @code{if}
3887 expression easier to read.
3891 (if @var{true-or-false-test}
3892 @var{action-to-carry-out-if-test-is-true})
3897 The true-or-false-test will be an expression that
3898 is evaluated by the Lisp interpreter.
3900 Here is an example that you can evaluate in the usual manner. The test
3901 is whether the number 5 is greater than the number 4. Since it is, the
3902 message @samp{5 is greater than 4!} will be printed.
3906 (if (> 5 4) ; @r{if-part}
3907 (message "5 is greater than 4!")) ; @r{then-part}
3912 (The function @code{>} tests whether its first argument is greater than
3913 its second argument and returns true if it is.)
3914 @findex > (greater than)
3916 Of course, in actual use, the test in an @code{if} expression will not
3917 be fixed for all time as it is by the expression @code{(> 5 4)}.
3918 Instead, at least one of the variables used in the test will be bound to
3919 a value that is not known ahead of time. (If the value were known ahead
3920 of time, we would not need to run the test!)
3922 For example, the value may be bound to an argument of a function
3923 definition. In the following function definition, the character of the
3924 animal is a value that is passed to the function. If the value bound to
3925 @code{characteristic} is @code{fierce}, then the message, @samp{It's a
3926 tiger!} will be printed; otherwise, @code{nil} will be returned.
3930 (defun type-of-animal (characteristic)
3931 "Print message in echo area depending on CHARACTERISTIC.
3932 If the CHARACTERISTIC is the symbol `fierce',
3933 then warn of a tiger."
3934 (if (equal characteristic 'fierce)
3935 (message "It's a tiger!")))
3941 If you are reading this inside of GNU Emacs, you can evaluate the
3942 function definition in the usual way to install it in Emacs, and then you
3943 can evaluate the following two expressions to see the results:
3947 (type-of-animal 'fierce)
3949 (type-of-animal 'zebra)
3954 @c Following sentences rewritten to prevent overfull hbox.
3956 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
3957 following message printed in the echo area: @code{"It's a tiger!"}; and
3958 when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil}
3959 printed in the echo area.
3961 @node type-of-animal in detail, , if in more detail, if
3962 @comment node-name, next, previous, up
3963 @subsection The @code{type-of-animal} Function in Detail
3965 Let's look at the @code{type-of-animal} function in detail.
3967 The function definition for @code{type-of-animal} was written by filling
3968 the slots of two templates, one for a function definition as a whole, and
3969 a second for an @code{if} expression.
3972 The template for every function that is not interactive is:
3976 (defun @var{name-of-function} (@var{argument-list})
3977 "@var{documentation}@dots{}"
3983 The parts of the function that match this template look like this:
3987 (defun type-of-animal (characteristic)
3988 "Print message in echo area depending on CHARACTERISTIC.
3989 If the CHARACTERISTIC is the symbol `fierce',
3990 then warn of a tiger."
3991 @var{body: the} @code{if} @var{expression})
3995 The name of function is @code{type-of-animal}; it is passed the value
3996 of one argument. The argument list is followed by a multi-line
3997 documentation string. The documentation string is included in the
3998 example because it is a good habit to write documentation string for
3999 every function definition. The body of the function definition
4000 consists of the @code{if} expression.
4003 The template for an @code{if} expression looks like this:
4007 (if @var{true-or-false-test}
4008 @var{action-to-carry-out-if-the-test-returns-true})
4013 In the @code{type-of-animal} function, the code for the @code{if}
4018 (if (equal characteristic 'fierce)
4019 (message "It's a tiger!")))
4024 Here, the true-or-false-test is the expression:
4027 (equal characteristic 'fierce)
4031 In Lisp, @code{equal} is a function that determines whether its first
4032 argument is equal to its second argument. The second argument is the
4033 quoted symbol @code{'fierce} and the first argument is the value of the
4034 symbol @code{characteristic}---in other words, the argument passed to
4037 In the first exercise of @code{type-of-animal}, the argument
4038 @code{fierce} is passed to @code{type-of-animal}. Since @code{fierce}
4039 is equal to @code{fierce}, the expression, @code{(equal characteristic
4040 'fierce)}, returns a value of true. When this happens, the @code{if}
4041 evaluates the second argument or then-part of the @code{if}:
4042 @code{(message "It's tiger!")}.
4044 On the other hand, in the second exercise of @code{type-of-animal}, the
4045 argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra}
4046 is not equal to @code{fierce}, so the then-part is not evaluated and
4047 @code{nil} is returned by the @code{if} expression.
4049 @node else, Truth & Falsehood, if, Writing Defuns
4050 @comment node-name, next, previous, up
4051 @section If--then--else Expressions
4054 An @code{if} expression may have an optional third argument, called
4055 the @dfn{else-part}, for the case when the true-or-false-test returns
4056 false. When this happens, the second argument or then-part of the
4057 overall @code{if} expression is @emph{not} evaluated, but the third or
4058 else-part @emph{is} evaluated. You might think of this as the cloudy
4059 day alternative for the decision ``if it is warm and sunny, then go to
4060 the beach, else read a book!''.
4062 The word ``else'' is not written in the Lisp code; the else-part of an
4063 @code{if} expression comes after the then-part. In the written Lisp, the
4064 else-part is usually written to start on a line of its own and is
4065 indented less than the then-part:
4069 (if @var{true-or-false-test}
4070 @var{action-to-carry-out-if-the-test-returns-true}
4071 @var{action-to-carry-out-if-the-test-returns-false})
4075 For example, the following @code{if} expression prints the message @samp{4
4076 is not greater than 5!} when you evaluate it in the usual way:
4080 (if (> 4 5) ; @r{if-part}
4081 (message "5 is greater than 4!") ; @r{then-part}
4082 (message "4 is not greater than 5!")) ; @r{else-part}
4087 Note that the different levels of indentation make it easy to
4088 distinguish the then-part from the else-part. (GNU Emacs has several
4089 commands that automatically indent @code{if} expressions correctly.
4090 @xref{Typing Lists, , GNU Emacs Helps You Type Lists}.)
4092 We can extend the @code{type-of-animal} function to include an
4093 else-part by simply incorporating an additional part to the @code{if}
4097 You can see the consequences of doing this if you evaluate the following
4098 version of the @code{type-of-animal} function definition to install it
4099 and then evaluate the two subsequent expressions to pass different
4100 arguments to the function.
4104 (defun type-of-animal (characteristic) ; @r{Second version.}
4105 "Print message in echo area depending on CHARACTERISTIC.
4106 If the CHARACTERISTIC is the symbol `fierce',
4107 then warn of a tiger;
4108 else say it's not fierce."
4109 (if (equal characteristic 'fierce)
4110 (message "It's a tiger!")
4111 (message "It's not fierce!")))
4118 (type-of-animal 'fierce)
4120 (type-of-animal 'zebra)
4125 @c Following sentence rewritten to prevent overfull hbox.
4127 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
4128 following message printed in the echo area: @code{"It's a tiger!"}; but
4129 when you evaluate @code{(type-of-animal 'zebra)}, you will see
4130 @code{"It's not fierce!"}.
4132 (Of course, if the @var{characteristic} were @code{ferocious}, the
4133 message @code{"It's not fierce!"} would be printed; and it would be
4134 misleading! When you write code, you need to take into account the
4135 possibility that some such argument will be tested by the @code{if}
4136 and write your program accordingly.)
4138 @node Truth & Falsehood, save-excursion, else, Writing Defuns
4139 @comment node-name, next, previous, up
4140 @section Truth and Falsehood in Emacs Lisp
4141 @cindex Truth and falsehood in Emacs Lisp
4142 @cindex Falsehood and truth in Emacs Lisp
4145 There is an important aspect to the truth test in an @code{if}
4146 expression. So far, we have spoken of `true' and `false' as values of
4147 predicates as if they were new kinds of Emacs Lisp objects. In fact,
4148 `false' is just our old friend @code{nil}. Anything else---anything
4151 The expression that tests for truth is interpreted as @dfn{true}
4152 if the result of evaluating it is a value that is not @code{nil}. In
4153 other words, the result of the test is considered true if the value
4154 returned is a number such as 47, a string such as @code{"hello"}, or a
4155 symbol (other than @code{nil}) such as @code{flowers}, or a list (so
4156 long as it is not empty), or even a buffer!
4162 @node nil explained, , Truth & Falsehood, Truth & Falsehood
4164 @unnumberedsubsec An explanation of @code{nil}
4167 Before illustrating a test for truth, we need an explanation of @code{nil}.
4169 In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the
4170 empty list. Second, it means false and is the value returned when a
4171 true-or-false-test tests false. @code{nil} can be written as an empty
4172 list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is
4173 concerned, @code{()} and @code{nil} are the same. Humans, however, tend
4174 to use @code{nil} for false and @code{()} for the empty list.
4176 In Emacs Lisp, any value that is not @code{nil}---is not the empty
4177 list---is considered true. This means that if an evaluation returns
4178 something that is not an empty list, an @code{if} expression will test
4179 true. For example, if a number is put in the slot for the test, it
4180 will be evaluated and will return itself, since that is what numbers
4181 do when evaluated. In this conditional, the @code{if} expression will
4182 test true. The expression tests false only when @code{nil}, an empty
4183 list, is returned by evaluating the expression.
4185 You can see this by evaluating the two expressions in the following examples.
4187 In the first example, the number 4 is evaluated as the test in the
4188 @code{if} expression and returns itself; consequently, the then-part
4189 of the expression is evaluated and returned: @samp{true} appears in
4190 the echo area. In the second example, the @code{nil} indicates false;
4191 consequently, the else-part of the expression is evaluated and
4192 returned: @samp{false} appears in the echo area.
4209 Incidentally, if some other useful value is not available for a test that
4210 returns true, then the Lisp interpreter will return the symbol @code{t}
4211 for true. For example, the expression @code{(> 5 4)} returns @code{t}
4212 when evaluated, as you can see by evaluating it in the usual way:
4220 On the other hand, this function returns @code{nil} if the test is false.
4226 @node save-excursion, Review, Truth & Falsehood, Writing Defuns
4227 @comment node-name, next, previous, up
4228 @section @code{save-excursion}
4229 @findex save-excursion
4230 @cindex Region, what it is
4231 @cindex Preserving point, mark, and buffer
4232 @cindex Point, mark, buffer preservation
4236 The @code{save-excursion} function is the fourth and final special form
4237 that we will discuss in this chapter.
4239 In Emacs Lisp programs used for editing, the @code{save-excursion}
4240 function is very common. It saves the location of point and mark,
4241 executes the body of the function, and then restores point and mark to
4242 their previous positions if their locations were changed. Its primary
4243 purpose is to keep the user from being surprised and disturbed by
4244 unexpected movement of point or mark.
4248 * Template for save-excursion::
4251 @node Point and mark, Template for save-excursion, save-excursion, save-excursion
4253 @unnumberedsubsec Point and Mark
4256 Before discussing @code{save-excursion}, however, it may be useful
4257 first to review what point and mark are in GNU Emacs. @dfn{Point} is
4258 the current location of the cursor. Wherever the cursor
4259 is, that is point. More precisely, on terminals where the cursor
4260 appears to be on top of a character, point is immediately before the
4261 character. In Emacs Lisp, point is an integer. The first character in
4262 a buffer is number one, the second is number two, and so on. The
4263 function @code{point} returns the current position of the cursor as a
4264 number. Each buffer has its own value for point.
4266 The @dfn{mark} is another position in the buffer; its value can be set
4267 with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If
4268 a mark has been set, you can use the command @kbd{C-x C-x}
4269 (@code{exchange-point-and-mark}) to cause the cursor to jump to the mark
4270 and set the mark to be the previous position of point. In addition, if
4271 you set another mark, the position of the previous mark is saved in the
4272 mark ring. Many mark positions can be saved this way. You can jump the
4273 cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more
4276 The part of the buffer between point and mark is called @dfn{the
4277 region}. Numerous commands work on the region, including
4278 @code{center-region}, @code{count-lines-region}, @code{kill-region}, and
4279 @code{print-region}.
4281 The @code{save-excursion} special form saves the locations of point and
4282 mark and restores those positions after the code within the body of the
4283 special form is evaluated by the Lisp interpreter. Thus, if point were
4284 in the beginning of a piece of text and some code moved point to the end
4285 of the buffer, the @code{save-excursion} would put point back to where
4286 it was before, after the expressions in the body of the function were
4289 In Emacs, a function frequently moves point as part of its internal
4290 workings even though a user would not expect this. For example,
4291 @code{count-lines-region} moves point. To prevent the user from being
4292 bothered by jumps that are both unexpected and (from the user's point of
4293 view) unnecessary, @code{save-excursion} is often used to keep point and
4294 mark in the location expected by the user. The use of
4295 @code{save-excursion} is good housekeeping.
4297 To make sure the house stays clean, @code{save-excursion} restores the
4298 values of point and mark even if something goes wrong in the code inside
4299 of it (or, to be more precise and to use the proper jargon, ``in case of
4300 abnormal exit''). This feature is very helpful.
4302 In addition to recording the values of point and mark,
4303 @code{save-excursion} keeps track of the current buffer, and restores
4304 it, too. This means you can write code that will change the buffer and
4305 have @code{save-excursion} switch you back to the original buffer.
4306 This is how @code{save-excursion} is used in @code{append-to-buffer}.
4307 (@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
4309 @node Template for save-excursion, , Point and mark, save-excursion
4310 @comment node-name, next, previous, up
4311 @subsection Template for a @code{save-excursion} Expression
4314 The template for code using @code{save-excursion} is simple:
4324 The body of the function is one or more expressions that will be
4325 evaluated in sequence by the Lisp interpreter. If there is more than
4326 one expression in the body, the value of the last one will be returned
4327 as the value of the @code{save-excursion} function. The other
4328 expressions in the body are evaluated only for their side effects; and
4329 @code{save-excursion} itself is used only for its side effect (which
4330 is restoring the positions of point and mark).
4333 In more detail, the template for a @code{save-excursion} expression
4339 @var{first-expression-in-body}
4340 @var{second-expression-in-body}
4341 @var{third-expression-in-body}
4343 @var{last-expression-in-body})
4348 An expression, of course, may be a symbol on its own or a list.
4350 In Emacs Lisp code, a @code{save-excursion} expression often occurs
4351 within the body of a @code{let} expression. It looks like this:
4361 @node Review, defun Exercises, save-excursion, Writing Defuns
4362 @comment node-name, next, previous, up
4365 In the last few chapters we have introduced a fair number of functions
4366 and special forms. Here they are described in brief, along with a few
4367 similar functions that have not been mentioned yet.
4370 @item eval-last-sexp
4371 Evaluate the last symbolic expression before the current location of
4372 point. The value is printed in the echo area unless the function is
4373 invoked with an argument; in that case, the output is printed in the
4374 current buffer. This command is normally bound to @kbd{C-x C-e}.
4377 Define function. This special form has up to five parts: the name,
4378 a template for the arguments that will be passed to the function,
4379 documentation, an optional interactive declaration, and the body of the
4383 For example, in an early version of Emacs, the function definition was
4384 as follows. (It is slightly more complex now that it seeks the first
4385 non-whitespace character rather than the first visible character.)
4389 (defun back-to-indentation ()
4390 "Move point to first visible character on line."
4392 (beginning-of-line 1)
4393 (skip-chars-forward " \t"))
4400 (defun backward-to-indentation (&optional arg)
4401 "Move backward ARG lines and position at first nonblank character."
4403 (forward-line (- (or arg 1)))
4404 (skip-chars-forward " \t"))
4406 (defun back-to-indentation ()
4407 "Move point to the first non-whitespace character on this line."
4409 (beginning-of-line 1)
4410 (skip-syntax-forward " " (line-end-position))
4411 ;; Move back over chars that have whitespace syntax but have the p flag.
4412 (backward-prefix-chars))
4416 Declare to the interpreter that the function can be used
4417 interactively. This special form may be followed by a string with one
4418 or more parts that pass the information to the arguments of the
4419 function, in sequence. These parts may also tell the interpreter to
4420 prompt for information. Parts of the string are separated by
4421 newlines, @samp{\n}.
4424 Common code characters are:
4428 The name of an existing buffer.
4431 The name of an existing file.
4434 The numeric prefix argument. (Note that this `p' is lower case.)
4437 Point and the mark, as two numeric arguments, smallest first. This
4438 is the only code letter that specifies two successive arguments
4442 @xref{Interactive Codes, , Code Characters for @samp{interactive},
4443 elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of
4447 Declare that a list of variables is for use within the body of the
4448 @code{let} and give them an initial value, either @code{nil} or a
4449 specified value; then evaluate the rest of the expressions in the body
4450 of the @code{let} and return the value of the last one. Inside the
4451 body of the @code{let}, the Lisp interpreter does not see the values of
4452 the variables of the same names that are bound outside of the
4460 (let ((foo (buffer-name))
4461 (bar (buffer-size)))
4463 "This buffer is %s and has %d characters."
4468 @item save-excursion
4469 Record the values of point and mark and the current buffer before
4470 evaluating the body of this special form. Restore the values of point
4471 and mark and buffer afterward.
4478 (message "We are %d characters into this buffer."
4481 (goto-char (point-min)) (point))))
4486 Evaluate the first argument to the function; if it is true, evaluate
4487 the second argument; else evaluate the third argument, if there is one.
4489 The @code{if} special form is called a @dfn{conditional}. There are
4490 other conditionals in Emacs Lisp, but @code{if} is perhaps the most
4499 (number-to-string 22)
4500 (substring (emacs-version) 10 12))
4501 (message "This is version 22 Emacs")
4502 (message "This is not version 22 Emacs"))
4508 Test whether two objects are the same. @code{equal} uses one meaning
4509 of the word `same' and @code{eq} uses another: @code{equal} returns
4510 true if the two objects have a similar structure and contents, such as
4511 two copies of the same book. On the other hand, @code{eq}, returns
4512 true if both arguments are actually the same object.
4521 The @code{<} function tests whether its first argument is smaller than
4522 its second argument. A corresponding function, @code{>}, tests whether
4523 the first argument is greater than the second. Likewise, @code{<=}
4524 tests whether the first argument is less than or equal to the second and
4525 @code{>=} tests whether the first argument is greater than or equal to
4526 the second. In all cases, both arguments must be numbers or markers
4527 (markers indicate positions in buffers).
4530 The @code{=} function tests whether two arguments, , both numbers or
4537 The @code{string-lessp} function tests whether its first argument is
4538 smaller than the second argument. A shorter, alternative name for the
4539 same function (a @code{defalias}) is @code{string<}.
4541 The arguments to @code{string-lessp} must be strings or symbols; the
4542 ordering is lexicographic, so case is significant. The print names of
4543 symbols are used instead of the symbols themselves.
4545 @cindex @samp{empty string} defined
4546 An empty string, @samp{""}, a string with no characters in it, is
4547 smaller than any string of characters.
4549 @code{string-equal} provides the corresponding test for equality. Its
4550 shorter, alternative name is @code{string=}. There are no string test
4551 functions that correspond to @var{>}, @code{>=}, or @code{<=}.
4554 Print a message in the echo area. The first argument is a string that
4555 can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of
4556 arguments that follow the string. The argument used by @samp{%s} must
4557 be a string or a symbol; the argument used by @samp{%d} must be a
4558 number. The argument used by @samp{%c} must be an @sc{ascii} code
4559 number; it will be printed as the character with that @sc{ascii} code.
4560 (Various other %-sequences have not been mentioned.)
4564 The @code{setq} function sets the value of its first argument to the
4565 value of the second argument. The first argument is automatically
4566 quoted by @code{setq}. It does the same for succeeding pairs of
4567 arguments. Another function, @code{set}, takes only two arguments and
4568 evaluates both of them before setting the value returned by its first
4569 argument to the value returned by its second argument.
4572 Without an argument, return the name of the buffer, as a string.
4574 @itemx buffer-file-name
4575 Without an argument, return the name of the file the buffer is
4578 @item current-buffer
4579 Return the buffer in which Emacs is active; it may not be
4580 the buffer that is visible on the screen.
4583 Return the most recently selected buffer (other than the buffer passed
4584 to @code{other-buffer} as an argument and other than the current
4587 @item switch-to-buffer
4588 Select a buffer for Emacs to be active in and display it in the current
4589 window so users can look at it. Usually bound to @kbd{C-x b}.
4592 Switch Emacs' attention to a buffer on which programs will run. Don't
4593 alter what the window is showing.
4596 Return the number of characters in the current buffer.
4599 Return the value of the current position of the cursor, as an
4600 integer counting the number of characters from the beginning of the
4604 Return the minimum permissible value of point in
4605 the current buffer. This is 1, unless narrowing is in effect.
4608 Return the value of the maximum permissible value of point in the
4609 current buffer. This is the end of the buffer, unless narrowing is in
4614 @node defun Exercises, , Review, Writing Defuns
4619 Write a non-interactive function that doubles the value of its
4620 argument, a number. Make that function interactive.
4623 Write a function that tests whether the current value of
4624 @code{fill-column} is greater than the argument passed to the function,
4625 and if so, prints an appropriate message.
4628 @node Buffer Walk Through, More Complex, Writing Defuns, Top
4629 @comment node-name, next, previous, up
4630 @chapter A Few Buffer--Related Functions
4632 In this chapter we study in detail several of the functions used in GNU
4633 Emacs. This is called a ``walk-through''. These functions are used as
4634 examples of Lisp code, but are not imaginary examples; with the
4635 exception of the first, simplified function definition, these functions
4636 show the actual code used in GNU Emacs. You can learn a great deal from
4637 these definitions. The functions described here are all related to
4638 buffers. Later, we will study other functions.
4642 * simplified-beginning-of-buffer::
4643 * mark-whole-buffer::
4644 * append-to-buffer::
4645 * Buffer Related Review::
4646 * Buffer Exercises::
4649 @node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through
4650 @section Finding More Information
4652 @findex describe-function, @r{introduced}
4653 @cindex Find function documentation
4654 In this walk-through, I will describe each new function as we come to
4655 it, sometimes in detail and sometimes briefly. If you are interested,
4656 you can get the full documentation of any Emacs Lisp function at any
4657 time by typing @kbd{C-h f} and then the name of the function (and then
4658 @key{RET}). Similarly, you can get the full documentation for a
4659 variable by typing @kbd{C-h v} and then the name of the variable (and
4662 @cindex Find source of function
4664 When a function is written in Emacs Lisp, @code{describe-function}
4665 will also tell you the location of the function definition.
4667 Put point into the name of the file that contains the function and
4668 press the @key{RET} key. In this case, @key{RET} means
4669 @code{push-button} rather than `return' or `enter'. Emacs will take
4670 you directly to the function definition.
4675 If you move point over the file name and press
4676 the @key{RET} key, which in this case means @code{help-follow} rather
4677 than `return' or `enter', Emacs will take you directly to the function
4681 More generally, if you want to see a function in its original source
4682 file, you can use the @code{find-tags} function to jump to it.
4683 @code{find-tags} works with a wide variety of languages, not just
4684 Lisp, and C, and it works with non-programming text as well. For
4685 example, @code{find-tags} will jump to the various nodes in the
4686 Texinfo source file of this document.
4688 The @code{find-tags} function depends on `tags tables' that record
4689 the locations of the functions, variables, and other items to which
4690 @code{find-tags} jumps.
4692 To use the @code{find-tags} command, type @kbd{M-.} (i.e., press the
4693 period key while holding down the @key{META} key, or else type the
4694 @key{ESC} key and then type the period key), and then, at the prompt,
4695 type in the name of the function whose source code you want to see,
4696 such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will
4697 switch buffers and display the source code for the function on your
4698 screen. To switch back to your current buffer, type @kbd{C-x b
4699 @key{RET}}. (On some keyboards, the @key{META} key is labelled
4702 @c !!! 22.0.100 tags table location in this paragraph
4703 @cindex TAGS table, specifying
4705 Depending on how the initial default values of your copy of Emacs are
4706 set, you may also need to specify the location of your `tags table',
4707 which is a file called @file{TAGS}. For example, if you are
4708 interested in Emacs sources, the tags table you will most likely want,
4709 if it has already been created for you, will be in a subdirectory of
4710 the @file{/usr/local/share/emacs/} directory; thus you would use the
4711 @code{M-x visit-tags-table} command and specify a pathname such as
4712 @file{/usr/local/share/emacs/22.0.100/lisp/TAGS}. If the tags table
4713 has not already been created, you will have to create it yourself. It
4714 will in a file such as @file{/usr/local/src/emacs/src/TAGS}.
4717 To create a @file{TAGS} file in a specific directory, switch to that
4718 directory in Emacs using @kbd{M-x cd} command, or list the directory
4719 with @kbd{C-x d} (@code{dired}). Then run the compile command, with
4720 @w{@code{etags *.el}} as the command to execute:
4723 M-x compile RET etags *.el RET
4726 For more information, see @ref{etags, , Create Your Own @file{TAGS} File}.
4728 After you become more familiar with Emacs Lisp, you will find that you will
4729 frequently use @code{find-tags} to navigate your way around source code;
4730 and you will create your own @file{TAGS} tables.
4732 @cindex Library, as term for `file'
4733 Incidentally, the files that contain Lisp code are conventionally
4734 called @dfn{libraries}. The metaphor is derived from that of a
4735 specialized library, such as a law library or an engineering library,
4736 rather than a general library. Each library, or file, contains
4737 functions that relate to a particular topic or activity, such as
4738 @file{abbrev.el} for handling abbreviations and other typing
4739 shortcuts, and @file{help.el} for on-line help. (Sometimes several
4740 libraries provide code for a single activity, as the various
4741 @file{rmail@dots{}} files provide code for reading electronic mail.)
4742 In @cite{The GNU Emacs Manual}, you will see sentences such as ``The
4743 @kbd{C-h p} command lets you search the standard Emacs Lisp libraries
4744 by topic keywords.''
4746 @node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through
4747 @comment node-name, next, previous, up
4748 @section A Simplified @code{beginning-of-buffer} Definition
4749 @findex simplified-beginning-of-buffer
4751 The @code{beginning-of-buffer} command is a good function to start with
4752 since you are likely to be familiar with it and it is easy to
4753 understand. Used as an interactive command, @code{beginning-of-buffer}
4754 moves the cursor to the beginning of the buffer, leaving the mark at the
4755 previous position. It is generally bound to @kbd{M-<}.
4757 In this section, we will discuss a shortened version of the function
4758 that shows how it is most frequently used. This shortened function
4759 works as written, but it does not contain the code for a complex option.
4760 In another section, we will describe the entire function.
4761 (@xref{beginning-of-buffer, , Complete Definition of
4762 @code{beginning-of-buffer}}.)
4764 Before looking at the code, let's consider what the function
4765 definition has to contain: it must include an expression that makes
4766 the function interactive so it can be called by typing @kbd{M-x
4767 beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it
4768 must include code to leave a mark at the original position in the
4769 buffer; and it must include code to move the cursor to the beginning
4773 Here is the complete text of the shortened version of the function:
4777 (defun simplified-beginning-of-buffer ()
4778 "Move point to the beginning of the buffer;
4779 leave mark at previous position."
4782 (goto-char (point-min)))
4786 Like all function definitions, this definition has five parts following
4787 the special form @code{defun}:
4791 The name: in this example, @code{simplified-beginning-of-buffer}.
4794 A list of the arguments: in this example, an empty list, @code{()},
4797 The documentation string.
4800 The interactive expression.
4807 In this function definition, the argument list is empty; this means that
4808 this function does not require any arguments. (When we look at the
4809 definition for the complete function, we will see that it may be passed
4810 an optional argument.)
4812 The interactive expression tells Emacs that the function is intended to
4813 be used interactively. In this example, @code{interactive} does not have
4814 an argument because @code{simplified-beginning-of-buffer} does not
4818 The body of the function consists of the two lines:
4823 (goto-char (point-min))
4827 The first of these lines is the expression, @code{(push-mark)}. When
4828 this expression is evaluated by the Lisp interpreter, it sets a mark at
4829 the current position of the cursor, wherever that may be. The position
4830 of this mark is saved in the mark ring.
4832 The next line is @code{(goto-char (point-min))}. This expression
4833 jumps the cursor to the minimum point in the buffer, that is, to the
4834 beginning of the buffer (or to the beginning of the accessible portion
4835 of the buffer if it is narrowed. @xref{Narrowing & Widening, ,
4836 Narrowing and Widening}.)
4838 The @code{push-mark} command sets a mark at the place where the cursor
4839 was located before it was moved to the beginning of the buffer by the
4840 @code{(goto-char (point-min))} expression. Consequently, you can, if
4841 you wish, go back to where you were originally by typing @kbd{C-x C-x}.
4843 That is all there is to the function definition!
4845 @findex describe-function
4846 When you are reading code such as this and come upon an unfamiliar
4847 function, such as @code{goto-char}, you can find out what it does by
4848 using the @code{describe-function} command. To use this command, type
4849 @kbd{C-h f} and then type in the name of the function and press
4850 @key{RET}. The @code{describe-function} command will print the
4851 function's documentation string in a @file{*Help*} window. For
4852 example, the documentation for @code{goto-char} is:
4856 Set point to POSITION, a number or marker.
4857 Beginning of buffer is position (point-min), end is (point-max).
4862 The function's one argument is the desired position.
4865 (The prompt for @code{describe-function} will offer you the symbol
4866 under or preceding the cursor, so you can save typing by positioning
4867 the cursor right over or after the function and then typing @kbd{C-h f
4870 The @code{end-of-buffer} function definition is written in the same way as
4871 the @code{beginning-of-buffer} definition except that the body of the
4872 function contains the expression @code{(goto-char (point-max))} in place
4873 of @code{(goto-char (point-min))}.
4875 @node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through
4876 @comment node-name, next, previous, up
4877 @section The Definition of @code{mark-whole-buffer}
4878 @findex mark-whole-buffer
4880 The @code{mark-whole-buffer} function is no harder to understand than the
4881 @code{simplified-beginning-of-buffer} function. In this case, however,
4882 we will look at the complete function, not a shortened version.
4884 The @code{mark-whole-buffer} function is not as commonly used as the
4885 @code{beginning-of-buffer} function, but is useful nonetheless: it
4886 marks a whole buffer as a region by putting point at the beginning and
4887 a mark at the end of the buffer. It is generally bound to @kbd{C-x
4891 * mark-whole-buffer overview::
4892 * Body of mark-whole-buffer::
4895 @node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer
4897 @unnumberedsubsec An overview of @code{mark-whole-buffer}
4901 In GNU Emacs 22, the code for the complete function looks like this:
4905 (defun mark-whole-buffer ()
4906 "Put point at beginning and mark at end of buffer.
4907 You probably should not use this function in Lisp programs;
4908 it is usually a mistake for a Lisp function to use any subroutine
4909 that uses or sets the mark."
4912 (push-mark (point-max) nil t)
4913 (goto-char (point-min)))
4918 Like all other functions, the @code{mark-whole-buffer} function fits
4919 into the template for a function definition. The template looks like
4924 (defun @var{name-of-function} (@var{argument-list})
4925 "@var{documentation}@dots{}"
4926 (@var{interactive-expression}@dots{})
4931 Here is how the function works: the name of the function is
4932 @code{mark-whole-buffer}; it is followed by an empty argument list,
4933 @samp{()}, which means that the function does not require arguments.
4934 The documentation comes next.
4936 The next line is an @code{(interactive)} expression that tells Emacs
4937 that the function will be used interactively. These details are similar
4938 to the @code{simplified-beginning-of-buffer} function described in the
4942 @node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer
4943 @comment node-name, next, previous, up
4944 @subsection Body of @code{mark-whole-buffer}
4946 The body of the @code{mark-whole-buffer} function consists of three
4953 (push-mark (point-max) nil t)
4954 (goto-char (point-min))
4958 The first of these lines is the expression, @code{(push-mark (point))}.
4960 This line does exactly the same job as the first line of the body of
4961 the @code{simplified-beginning-of-buffer} function, which is written
4962 @code{(push-mark)}. In both cases, the Lisp interpreter sets a mark
4963 at the current position of the cursor.
4965 I don't know why the expression in @code{mark-whole-buffer} is written
4966 @code{(push-mark (point))} and the expression in
4967 @code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps
4968 whoever wrote the code did not know that the arguments for
4969 @code{push-mark} are optional and that if @code{push-mark} is not
4970 passed an argument, the function automatically sets mark at the
4971 location of point by default. Or perhaps the expression was written
4972 so as to parallel the structure of the next line. In any case, the
4973 line causes Emacs to determine the position of point and set a mark
4976 In earlier versions of GNU Emacs, the next line of
4977 @code{mark-whole-buffer} was @code{(push-mark (point-max))}. This
4978 expression sets a mark at the point in the buffer that has the highest
4979 number. This will be the end of the buffer (or, if the buffer is
4980 narrowed, the end of the accessible portion of the buffer.
4981 @xref{Narrowing & Widening, , Narrowing and Widening}, for more about
4982 narrowing.) After this mark has been set, the previous mark, the one
4983 set at point, is no longer set, but Emacs remembers its position, just
4984 as all other recent marks are always remembered. This means that you
4985 can, if you wish, go back to that position by typing @kbd{C-u
4989 In GNU Emacs 22, the @code{(point-max)} is slightly more complicated.
4993 (push-mark (point-max) nil t)
4997 The expression works nearly the same as before. It sets a mark at the
4998 highest numbered place in the buffer that it can. However, in this
4999 version, @code{push-mark} has two additional arguments. The second
5000 argument to @code{push-mark} is @code{nil}. This tells the function
5001 it @emph{should} display a message that says `Mark set' when it pushes
5002 the mark. The third argument is @code{t}. This tells
5003 @code{push-mark} to activate the mark when Transient Mark mode is
5004 turned on. Transient Mark mode highlights the currently active
5005 region. It is often turned off.
5007 Finally, the last line of the function is @code{(goto-char
5008 (point-min)))}. This is written exactly the same way as it is written
5009 in @code{beginning-of-buffer}. The expression moves the cursor to
5010 the minimum point in the buffer, that is, to the beginning of the buffer
5011 (or to the beginning of the accessible portion of the buffer). As a
5012 result of this, point is placed at the beginning of the buffer and mark
5013 is set at the end of the buffer. The whole buffer is, therefore, the
5016 @node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through
5017 @comment node-name, next, previous, up
5018 @section The Definition of @code{append-to-buffer}
5019 @findex append-to-buffer
5021 The @code{append-to-buffer} command is more complex than the
5022 @code{mark-whole-buffer} command. What it does is copy the region
5023 (that is, the part of the buffer between point and mark) from the
5024 current buffer to a specified buffer.
5027 * append-to-buffer overview::
5028 * append interactive::
5029 * append-to-buffer body::
5030 * append save-excursion::
5033 @node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer
5035 @unnumberedsubsec An Overview of @code{append-to-buffer}
5038 @findex insert-buffer-substring
5039 The @code{append-to-buffer} command uses the
5040 @code{insert-buffer-substring} function to copy the region.
5041 @code{insert-buffer-substring} is described by its name: it takes a
5042 string of characters from part of a buffer, a ``substring'', and
5043 inserts them into another buffer.
5045 Most of @code{append-to-buffer} is
5046 concerned with setting up the conditions for
5047 @code{insert-buffer-substring} to work: the code must specify both the
5048 buffer to which the text will go, the window it comes from and goes
5049 to, and the region that will be copied.
5052 Here is the complete text of the function:
5056 (defun append-to-buffer (buffer start end)
5057 "Append to specified buffer the text of the region.
5058 It is inserted into that buffer before its point.
5062 When calling from a program, give three arguments:
5063 BUFFER (or buffer name), START and END.
5064 START and END specify the portion of the current buffer to be copied."
5066 (list (read-buffer "Append to buffer: " (other-buffer
5067 (current-buffer) t))
5068 (region-beginning) (region-end)))
5071 (let ((oldbuf (current-buffer)))
5073 (let* ((append-to (get-buffer-create buffer))
5074 (windows (get-buffer-window-list append-to t t))
5076 (set-buffer append-to)
5077 (setq point (point))
5078 (barf-if-buffer-read-only)
5079 (insert-buffer-substring oldbuf start end)
5080 (dolist (window windows)
5081 (when (= (window-point window) point)
5082 (set-window-point window (point))))))))
5086 The function can be understood by looking at it as a series of
5087 filled-in templates.
5089 The outermost template is for the function definition. In this
5090 function, it looks like this (with several slots filled in):
5094 (defun append-to-buffer (buffer start end)
5095 "@var{documentation}@dots{}"
5096 (interactive @dots{})
5101 The first line of the function includes its name and three arguments.
5102 The arguments are the @code{buffer} to which the text will be copied, and
5103 the @code{start} and @code{end} of the region in the current buffer that
5106 The next part of the function is the documentation, which is clear and
5107 complete. As is conventional, the three arguments are written in
5108 upper case so you will notice them easily. Even better, they are
5109 described in the same order as in the argument list.
5111 Note that the documentation distinguishes between a buffer and its
5112 name. (The function can handle either.)
5114 @node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer
5115 @comment node-name, next, previous, up
5116 @subsection The @code{append-to-buffer} Interactive Expression
5118 Since the @code{append-to-buffer} function will be used interactively,
5119 the function must have an @code{interactive} expression. (For a
5120 review of @code{interactive}, see @ref{Interactive, , Making a
5121 Function Interactive}.) The expression reads as follows:
5126 "Append to buffer: "
5127 (other-buffer (current-buffer) t))
5133 This expression is not one with letters standing for parts, as
5134 described earlier. Instead, it starts a list with thee parts.
5136 The first part of the list is an expression to read the name of a
5137 buffer and return it as a string. That is @code{read-buffer}. The
5138 function requires a prompt as its first argument, @samp{"Append to
5139 buffer: "}. Its second argument tells the command what value to
5140 provide if you don't specify anything.
5142 In this case that second argument is an expression containing the
5143 function @code{other-buffer}, an exception, and a @samp{t}, standing
5146 The first argument to @code{other-buffer}, the exception, is yet
5147 another function, @code{current-buffer}. That is not going to be
5148 returned. The second argument is the symbol for true, @code{t}. that
5149 tells @code{other-buffer} that it may show visible buffers (except in
5150 this case, it will not show the current buffer, which makes sense).
5153 The expression looks like this:
5156 (other-buffer (current-buffer) t)
5159 The second and third arguments to the @code{list} expression are
5160 @code{(region-beginning)} and @code{(region-end)}. These two
5161 functions specify the beginning and end of the text to be appended.
5164 Originally, the command used the letters @samp{B} and @samp{r}.
5165 The whole @code{interactive} expression looked like this:
5168 (interactive "BAppend to buffer:@: \nr")
5172 But when that was done, the default value of the buffer switched to
5173 was invisible. That was not wanted.
5175 (The prompt was separated from the second argument with a newline,
5176 @samp{\n}. It was followed by an @samp{r} that told Emacs to bind the
5177 two arguments that follow the symbol @code{buffer} in the function's
5178 argument list (that is, @code{start} and @code{end}) to the values of
5179 point and mark. That argument worked fine.)
5181 @node append-to-buffer body, append save-excursion, append interactive, append-to-buffer
5182 @comment node-name, next, previous, up
5183 @subsection The Body of @code{append-to-buffer}
5186 in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el
5188 (defun append-to-buffer (buffer start end)
5189 "Append to specified buffer the text of the region.
5190 It is inserted into that buffer before its point.
5192 When calling from a program, give three arguments:
5193 BUFFER (or buffer name), START and END.
5194 START and END specify the portion of the current buffer to be copied."
5196 (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t))
5197 (region-beginning) (region-end)))
5198 (let ((oldbuf (current-buffer)))
5200 (let* ((append-to (get-buffer-create buffer))
5201 (windows (get-buffer-window-list append-to t t))
5203 (set-buffer append-to)
5204 (setq point (point))
5205 (barf-if-buffer-read-only)
5206 (insert-buffer-substring oldbuf start end)
5207 (dolist (window windows)
5208 (when (= (window-point window) point)
5209 (set-window-point window (point))))))))
5212 The body of the @code{append-to-buffer} function begins with @code{let}.
5214 As we have seen before (@pxref{let, , @code{let}}), the purpose of a
5215 @code{let} expression is to create and give initial values to one or
5216 more variables that will only be used within the body of the
5217 @code{let}. This means that such a variable will not be confused with
5218 any variable of the same name outside the @code{let} expression.
5220 We can see how the @code{let} expression fits into the function as a
5221 whole by showing a template for @code{append-to-buffer} with the
5222 @code{let} expression in outline:
5226 (defun append-to-buffer (buffer start end)
5227 "@var{documentation}@dots{}"
5228 (interactive @dots{})
5229 (let ((@var{variable} @var{value}))
5234 The @code{let} expression has three elements:
5238 The symbol @code{let};
5241 A varlist containing, in this case, a single two-element list,
5242 @code{(@var{variable} @var{value})};
5245 The body of the @code{let} expression.
5249 In the @code{append-to-buffer} function, the varlist looks like this:
5252 (oldbuf (current-buffer))
5256 In this part of the @code{let} expression, the one variable,
5257 @code{oldbuf}, is bound to the value returned by the
5258 @code{(current-buffer)} expression. The variable, @code{oldbuf}, is
5259 used to keep track of the buffer in which you are working and from
5260 which you will copy.
5262 The element or elements of a varlist are surrounded by a set of
5263 parentheses so the Lisp interpreter can distinguish the varlist from
5264 the body of the @code{let}. As a consequence, the two-element list
5265 within the varlist is surrounded by a circumscribing set of parentheses.
5266 The line looks like this:
5270 (let ((oldbuf (current-buffer)))
5276 The two parentheses before @code{oldbuf} might surprise you if you did
5277 not realize that the first parenthesis before @code{oldbuf} marks the
5278 boundary of the varlist and the second parenthesis marks the beginning
5279 of the two-element list, @code{(oldbuf (current-buffer))}.
5281 @node append save-excursion, , append-to-buffer body, append-to-buffer
5282 @comment node-name, next, previous, up
5283 @subsection @code{save-excursion} in @code{append-to-buffer}
5285 The body of the @code{let} expression in @code{append-to-buffer}
5286 consists of a @code{save-excursion} expression.
5288 The @code{save-excursion} function saves the locations of point and
5289 mark, and restores them to those positions after the expressions in the
5290 body of the @code{save-excursion} complete execution. In addition,
5291 @code{save-excursion} keeps track of the original buffer, and
5292 restores it. This is how @code{save-excursion} is used in
5293 @code{append-to-buffer}.
5296 @cindex Indentation for formatting
5297 @cindex Formatting convention
5298 Incidentally, it is worth noting here that a Lisp function is normally
5299 formatted so that everything that is enclosed in a multi-line spread is
5300 indented more to the right than the first symbol. In this function
5301 definition, the @code{let} is indented more than the @code{defun}, and
5302 the @code{save-excursion} is indented more than the @code{let}, like
5318 This formatting convention makes it easy to see that the lines in
5319 the body of the @code{save-excursion} are enclosed by the parentheses
5320 associated with @code{save-excursion}, just as the
5321 @code{save-excursion} itself is enclosed by the parentheses associated
5322 with the @code{let}:
5326 (let ((oldbuf (current-buffer)))
5329 (set-buffer @dots{})
5330 (insert-buffer-substring oldbuf start end)
5336 The use of the @code{save-excursion} function can be viewed as a process
5337 of filling in the slots of a template:
5342 @var{first-expression-in-body}
5343 @var{second-expression-in-body}
5345 @var{last-expression-in-body})
5351 In this function, the body of the @code{save-excursion} contains only
5352 one expression, the @code{let*} expression. You know about a
5353 @code{let} function. The @code{let*} function is different. It has a
5354 @samp{*} in its name. It enables Emacs to set each variable in its
5355 varlist in sequence, one after another.
5357 Its critical feature is that variables later in the varlist can make
5358 use of the values to which Emacs set variables earlier in the varlist.
5359 @xref{fwd-para let, , The @code{let*} expression}.
5361 We will skip functions like @code{let*} and focus on two: the
5362 @code{set-buffer} function and the @code{insert-buffer-substring}
5366 In the old days, the @code{set-buffer} expression was simply
5369 (set-buffer (get-buffer-create buffer))
5377 (set-buffer append-to)
5381 @code{append-to} is bound to @code{(get-buffer-create buffer)} earlier
5382 on in the @code{let*} expression. That extra binding would not be
5383 necessary except for that @code{append-to} is used later in the
5384 varlist as an argument to @code{get-buffer-window-list}.
5389 (let ((oldbuf (current-buffer)))
5391 (let* ((append-to (get-buffer-create buffer))
5392 (windows (get-buffer-window-list append-to t t))
5394 (set-buffer append-to)
5395 (setq point (point))
5396 (barf-if-buffer-read-only)
5397 (insert-buffer-substring oldbuf start end)
5398 (dolist (window windows)
5399 (when (= (window-point window) point)
5400 (set-window-point window (point))))))))
5403 The @code{append-to-buffer} function definition inserts text from the
5404 buffer in which you are currently to a named buffer. It happens that
5405 @code{insert-buffer-substring} copies text from another buffer to the
5406 current buffer, just the reverse---that is why the
5407 @code{append-to-buffer} definition starts out with a @code{let} that
5408 binds the local symbol @code{oldbuf} to the value returned by
5409 @code{current-buffer}.
5412 The @code{insert-buffer-substring} expression looks like this:
5415 (insert-buffer-substring oldbuf start end)
5419 The @code{insert-buffer-substring} function copies a string
5420 @emph{from} the buffer specified as its first argument and inserts the
5421 string into the present buffer. In this case, the argument to
5422 @code{insert-buffer-substring} is the value of the variable created
5423 and bound by the @code{let}, namely the value of @code{oldbuf}, which
5424 was the current buffer when you gave the @code{append-to-buffer}
5427 After @code{insert-buffer-substring} has done its work,
5428 @code{save-excursion} will restore the action to the original buffer
5429 and @code{append-to-buffer} will have done its job.
5432 Written in skeletal form, the workings of the body look like this:
5436 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5437 (save-excursion ; @r{Keep track of buffer.}
5439 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})
5441 @var{change-back-to-original-buffer-when-finished}
5442 @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished}
5446 In summary, @code{append-to-buffer} works as follows: it saves the
5447 value of the current buffer in the variable called @code{oldbuf}. It
5448 gets the new buffer (creating one if need be) and switches Emacs'
5449 attention to it. Using the value of @code{oldbuf}, it inserts the
5450 region of text from the old buffer into the new buffer; and then using
5451 @code{save-excursion}, it brings you back to your original buffer.
5453 In looking at @code{append-to-buffer}, you have explored a fairly
5454 complex function. It shows how to use @code{let} and
5455 @code{save-excursion}, and how to change to and come back from another
5456 buffer. Many function definitions use @code{let},
5457 @code{save-excursion}, and @code{set-buffer} this way.
5459 @node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through
5460 @comment node-name, next, previous, up
5463 Here is a brief summary of the various functions discussed in this chapter.
5466 @item describe-function
5467 @itemx describe-variable
5468 Print the documentation for a function or variable.
5469 Conventionally bound to @kbd{C-h f} and @kbd{C-h v}.
5472 Find the file containing the source for a function or variable and
5473 switch buffers to it, positioning point at the beginning of the item.
5474 Conventionally bound to @kbd{M-.} (that's a period following the
5477 @item save-excursion
5478 Save the location of point and mark and restore their values after the
5479 arguments to @code{save-excursion} have been evaluated. Also, remember
5480 the current buffer and return to it.
5483 Set mark at a location and record the value of the previous mark on the
5484 mark ring. The mark is a location in the buffer that will keep its
5485 relative position even if text is added to or removed from the buffer.
5488 Set point to the location specified by the value of the argument, which
5489 can be a number, a marker, or an expression that returns the number of
5490 a position, such as @code{(point-min)}.
5492 @item insert-buffer-substring
5493 Copy a region of text from a buffer that is passed to the function as
5494 an argument and insert the region into the current buffer.
5496 @item mark-whole-buffer
5497 Mark the whole buffer as a region. Normally bound to @kbd{C-x h}.
5500 Switch the attention of Emacs to another buffer, but do not change the
5501 window being displayed. Used when the program rather than a human is
5502 to work on a different buffer.
5504 @item get-buffer-create
5506 Find a named buffer or create one if a buffer of that name does not
5507 exist. The @code{get-buffer} function returns @code{nil} if the named
5508 buffer does not exist.
5512 @node Buffer Exercises, , Buffer Related Review, Buffer Walk Through
5517 Write your own @code{simplified-end-of-buffer} function definition;
5518 then test it to see whether it works.
5521 Use @code{if} and @code{get-buffer} to write a function that prints a
5522 message telling you whether a buffer exists.
5525 Using @code{find-tag}, find the source for the @code{copy-to-buffer}
5529 @node More Complex, Narrowing & Widening, Buffer Walk Through, Top
5530 @comment node-name, next, previous, up
5531 @chapter A Few More Complex Functions
5533 In this chapter, we build on what we have learned in previous chapters
5534 by looking at more complex functions. The @code{copy-to-buffer}
5535 function illustrates use of two @code{save-excursion} expressions in
5536 one definition, while the @code{insert-buffer} function illustrates
5537 use of an asterisk in an @code{interactive} expression, use of
5538 @code{or}, and the important distinction between a name and the object
5539 to which the name refers.
5544 * beginning-of-buffer::
5545 * Second Buffer Related Review::
5546 * optional Exercise::
5549 @node copy-to-buffer, insert-buffer, More Complex, More Complex
5550 @comment node-name, next, previous, up
5551 @section The Definition of @code{copy-to-buffer}
5552 @findex copy-to-buffer
5554 After understanding how @code{append-to-buffer} works, it is easy to
5555 understand @code{copy-to-buffer}. This function copies text into a
5556 buffer, but instead of adding to the second buffer, it replaces all the
5557 previous text in the second buffer.
5560 The body of @code{copy-to-buffer} looks like this,
5565 (interactive "BCopy to buffer: \nr")
5566 (let ((oldbuf (current-buffer)))
5567 (with-current-buffer (get-buffer-create buffer)
5568 (barf-if-buffer-read-only)
5571 (insert-buffer-substring oldbuf start end)))))
5575 The @code{copy-to-buffer} function has a simpler @code{interactive}
5576 expression than @code{append-to-buffer}.
5579 The definition then says
5582 (with-current-buffer (get-buffer-create buffer) @dots{}
5585 First, look at the earliest inner expression; that is evaluated first.
5586 That expression starts with @code{get-buffer-create buffer}. The
5587 function tells the computer to use the buffer with the name specified
5588 as the one to which you are copying, or if such a buffer does not
5589 exist, to create it. Then, the @code{with-current-buffer} function
5590 evaluates its body with that buffer temporarily current.
5592 (This demonstrates another way to shift the computer's attention but
5593 not the user's. The @code{append-to-buffer} function showed how to do
5594 the same with @code{save-excursion} and @code{set-buffer}.
5595 @code{with-current-buffer} is a newer, and arguably easier,
5598 The @code{barf-if-buffer-read-only} function sends you an error
5599 message saying the buffer is read-only if you cannot modify it.
5601 The next line has the @code{erase-buffer} function as its sole
5602 contents. That function erases the buffer.
5604 Finally, the last two lines contain the @code{save-excursion}
5605 expression with @code{insert-buffer-substring} as its body.
5606 The @code{insert-buffer-substring} expression copies the text from
5607 the buffer you are in (and you have not seen the computer shift its
5608 attention, so you don't know that that buffer is now called
5611 Incidentally, this is what is meant by `replacement'. To replace text,
5612 Emacs erases the previous text and then inserts new text.
5615 In outline, the body of @code{copy-to-buffer} looks like this:
5619 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5620 (@var{with-the-buffer-you-are-copying-to}
5621 (@var{but-do-not-erase-or-copy-to-a-read-only-buffer})
5624 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})))
5628 @node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex
5629 @comment node-name, next, previous, up
5630 @section The Definition of @code{insert-buffer}
5631 @findex insert-buffer
5633 @code{insert-buffer} is yet another buffer-related function. This
5634 command copies another buffer @emph{into} the current buffer. It is the
5635 reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they
5636 copy a region of text @emph{from} the current buffer to another buffer.
5638 Here is a discussion based on the original code. The code was
5639 simplified in 2003 and is harder to understand.
5641 @xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see
5642 a discussion of the new body.)
5644 In addition, this code illustrates the use of @code{interactive} with a
5645 buffer that might be @dfn{read-only} and the important distinction
5646 between the name of an object and the object actually referred to.
5649 * insert-buffer code::
5650 * insert-buffer interactive::
5651 * insert-buffer body::
5655 * New insert-buffer ::
5658 @node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer
5660 @unnumberedsubsec The Code for @code{insert-buffer}
5664 Here is the earlier code:
5668 (defun insert-buffer (buffer)
5669 "Insert after point the contents of BUFFER.
5670 Puts mark after the inserted text.
5671 BUFFER may be a buffer or a buffer name."
5672 (interactive "*bInsert buffer:@: ")
5675 (or (bufferp buffer)
5676 (setq buffer (get-buffer buffer)))
5677 (let (start end newmark)
5681 (setq start (point-min) end (point-max)))
5684 (insert-buffer-substring buffer start end)
5685 (setq newmark (point)))
5686 (push-mark newmark)))
5691 As with other function definitions, you can use a template to see an
5692 outline of the function:
5696 (defun insert-buffer (buffer)
5697 "@var{documentation}@dots{}"
5698 (interactive "*bInsert buffer:@: ")
5703 @node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer
5704 @comment node-name, next, previous, up
5705 @subsection The Interactive Expression in @code{insert-buffer}
5706 @findex interactive, @r{example use of}
5708 In @code{insert-buffer}, the argument to the @code{interactive}
5709 declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert
5713 * Read-only buffer::
5714 * b for interactive::
5717 @node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive
5718 @comment node-name, next, previous, up
5719 @unnumberedsubsubsec A Read-only Buffer
5720 @cindex Read-only buffer
5721 @cindex Asterisk for read-only buffer
5722 @findex * @r{for read-only buffer}
5724 The asterisk is for the situation when the current buffer is a
5725 read-only buffer---a buffer that cannot be modified. If
5726 @code{insert-buffer} is called when the current buffer is read-only, a
5727 message to this effect is printed in the echo area and the terminal
5728 may beep or blink at you; you will not be permitted to insert anything
5729 into current buffer. The asterisk does not need to be followed by a
5730 newline to separate it from the next argument.
5732 @node b for interactive, , Read-only buffer, insert-buffer interactive
5733 @comment node-name, next, previous, up
5734 @unnumberedsubsubsec @samp{b} in an Interactive Expression
5736 The next argument in the interactive expression starts with a lower
5737 case @samp{b}. (This is different from the code for
5738 @code{append-to-buffer}, which uses an upper-case @samp{B}.
5739 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
5740 The lower-case @samp{b} tells the Lisp interpreter that the argument
5741 for @code{insert-buffer} should be an existing buffer or else its
5742 name. (The upper-case @samp{B} option provides for the possibility
5743 that the buffer does not exist.) Emacs will prompt you for the name
5744 of the buffer, offering you a default buffer, with name completion
5745 enabled. If the buffer does not exist, you receive a message that
5746 says ``No match''; your terminal may beep at you as well.
5748 The new and simplified code generates a list for @code{interactive}.
5749 It uses the @code{barf-if-buffer-read-only} and @code{read-buffer}
5750 functions with which we are already familiar and the @code{progn}
5751 special form with which we are not. (It will be described later.)
5753 @node insert-buffer body, if & or, insert-buffer interactive, insert-buffer
5754 @comment node-name, next, previous, up
5755 @subsection The Body of the @code{insert-buffer} Function
5757 The body of the @code{insert-buffer} function has two major parts: an
5758 @code{or} expression and a @code{let} expression. The purpose of the
5759 @code{or} expression is to ensure that the argument @code{buffer} is
5760 bound to a buffer and not just the name of a buffer. The body of the
5761 @code{let} expression contains the code which copies the other buffer
5762 into the current buffer.
5765 In outline, the two expressions fit into the @code{insert-buffer}
5770 (defun insert-buffer (buffer)
5771 "@var{documentation}@dots{}"
5772 (interactive "*bInsert buffer:@: ")
5777 (let (@var{varlist})
5778 @var{body-of-}@code{let}@dots{} )
5782 To understand how the @code{or} expression ensures that the argument
5783 @code{buffer} is bound to a buffer and not to the name of a buffer, it
5784 is first necessary to understand the @code{or} function.
5786 Before doing this, let me rewrite this part of the function using
5787 @code{if} so that you can see what is done in a manner that will be familiar.
5789 @node if & or, Insert or, insert-buffer body, insert-buffer
5790 @comment node-name, next, previous, up
5791 @subsection @code{insert-buffer} With an @code{if} Instead of an @code{or}
5793 The job to be done is to make sure the value of @code{buffer} is a
5794 buffer itself and not the name of a buffer. If the value is the name,
5795 then the buffer itself must be got.
5797 You can imagine yourself at a conference where an usher is wandering
5798 around holding a list with your name on it and looking for you: the
5799 usher is ``bound'' to your name, not to you; but when the usher finds
5800 you and takes your arm, the usher becomes ``bound'' to you.
5803 In Lisp, you might describe this situation like this:
5807 (if (not (holding-on-to-guest))
5808 (find-and-take-arm-of-guest))
5812 We want to do the same thing with a buffer---if we do not have the
5813 buffer itself, we want to get it.
5816 Using a predicate called @code{bufferp} that tells us whether we have a
5817 buffer (rather than its name), we can write the code like this:
5821 (if (not (bufferp buffer)) ; @r{if-part}
5822 (setq buffer (get-buffer buffer))) ; @r{then-part}
5827 Here, the true-or-false-test of the @code{if} expression is
5828 @w{@code{(not (bufferp buffer))}}; and the then-part is the expression
5829 @w{@code{(setq buffer (get-buffer buffer))}}.
5831 In the test, the function @code{bufferp} returns true if its argument is
5832 a buffer---but false if its argument is the name of the buffer. (The
5833 last character of the function name @code{bufferp} is the character
5834 @samp{p}; as we saw earlier, such use of @samp{p} is a convention that
5835 indicates that the function is a predicate, which is a term that means
5836 that the function will determine whether some property is true or false.
5837 @xref{Wrong Type of Argument, , Using the Wrong Type Object as an
5841 The function @code{not} precedes the expression @code{(bufferp buffer)},
5842 so the true-or-false-test looks like this:
5845 (not (bufferp buffer))
5849 @code{not} is a function that returns true if its argument is false
5850 and false if its argument is true. So if @code{(bufferp buffer)}
5851 returns true, the @code{not} expression returns false and vice-verse:
5852 what is ``not true'' is false and what is ``not false'' is true.
5854 Using this test, the @code{if} expression works as follows: when the
5855 value of the variable @code{buffer} is actually a buffer rather than
5856 its name, the true-or-false-test returns false and the @code{if}
5857 expression does not evaluate the then-part. This is fine, since we do
5858 not need to do anything to the variable @code{buffer} if it really is
5861 On the other hand, when the value of @code{buffer} is not a buffer
5862 itself, but the name of a buffer, the true-or-false-test returns true
5863 and the then-part of the expression is evaluated. In this case, the
5864 then-part is @code{(setq buffer (get-buffer buffer))}. This
5865 expression uses the @code{get-buffer} function to return an actual
5866 buffer itself, given its name. The @code{setq} then sets the variable
5867 @code{buffer} to the value of the buffer itself, replacing its previous
5868 value (which was the name of the buffer).
5870 @node Insert or, Insert let, if & or, insert-buffer
5871 @comment node-name, next, previous, up
5872 @subsection The @code{or} in the Body
5874 The purpose of the @code{or} expression in the @code{insert-buffer}
5875 function is to ensure that the argument @code{buffer} is bound to a
5876 buffer and not just to the name of a buffer. The previous section shows
5877 how the job could have been done using an @code{if} expression.
5878 However, the @code{insert-buffer} function actually uses @code{or}.
5879 To understand this, it is necessary to understand how @code{or} works.
5882 An @code{or} function can have any number of arguments. It evaluates
5883 each argument in turn and returns the value of the first of its
5884 arguments that is not @code{nil}. Also, and this is a crucial feature
5885 of @code{or}, it does not evaluate any subsequent arguments after
5886 returning the first non-@code{nil} value.
5889 The @code{or} expression looks like this:
5893 (or (bufferp buffer)
5894 (setq buffer (get-buffer buffer)))
5899 The first argument to @code{or} is the expression @code{(bufferp buffer)}.
5900 This expression returns true (a non-@code{nil} value) if the buffer is
5901 actually a buffer, and not just the name of a buffer. In the @code{or}
5902 expression, if this is the case, the @code{or} expression returns this
5903 true value and does not evaluate the next expression---and this is fine
5904 with us, since we do not want to do anything to the value of
5905 @code{buffer} if it really is a buffer.
5907 On the other hand, if the value of @code{(bufferp buffer)} is @code{nil},
5908 which it will be if the value of @code{buffer} is the name of a buffer,
5909 the Lisp interpreter evaluates the next element of the @code{or}
5910 expression. This is the expression @code{(setq buffer (get-buffer
5911 buffer))}. This expression returns a non-@code{nil} value, which
5912 is the value to which it sets the variable @code{buffer}---and this
5913 value is a buffer itself, not the name of a buffer.
5915 The result of all this is that the symbol @code{buffer} is always
5916 bound to a buffer itself rather than to the name of a buffer. All
5917 this is necessary because the @code{set-buffer} function in a
5918 following line only works with a buffer itself, not with the name to a
5922 Incidentally, using @code{or}, the situation with the usher would be
5926 (or (holding-on-to-guest) (find-and-take-arm-of-guest))
5929 @node Insert let, New insert-buffer , Insert or, insert-buffer
5930 @comment node-name, next, previous, up
5931 @subsection The @code{let} Expression in @code{insert-buffer}
5933 After ensuring that the variable @code{buffer} refers to a buffer itself
5934 and not just to the name of a buffer, the @code{insert-buffer function}
5935 continues with a @code{let} expression. This specifies three local
5936 variables, @code{start}, @code{end}, and @code{newmark} and binds them
5937 to the initial value @code{nil}. These variables are used inside the
5938 remainder of the @code{let} and temporarily hide any other occurrence of
5939 variables of the same name in Emacs until the end of the @code{let}.
5942 The body of the @code{let} contains two @code{save-excursion}
5943 expressions. First, we will look at the inner @code{save-excursion}
5944 expression in detail. The expression looks like this:
5950 (setq start (point-min) end (point-max)))
5955 The expression @code{(set-buffer buffer)} changes Emacs' attention
5956 from the current buffer to the one from which the text will copied.
5957 In that buffer, the variables @code{start} and @code{end} are set to
5958 the beginning and end of the buffer, using the commands
5959 @code{point-min} and @code{point-max}. Note that we have here an
5960 illustration of how @code{setq} is able to set two variables in the
5961 same expression. The first argument of @code{setq} is set to the
5962 value of its second, and its third argument is set to the value of its
5965 After the body of the inner @code{save-excursion} is evaluated, the
5966 @code{save-excursion} restores the original buffer, but @code{start} and
5967 @code{end} remain set to the values of the beginning and end of the
5968 buffer from which the text will be copied.
5971 The outer @code{save-excursion} expression looks like this:
5976 (@var{inner-}@code{save-excursion}@var{-expression}
5977 (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end})
5978 (insert-buffer-substring buffer start end)
5979 (setq newmark (point)))
5984 The @code{insert-buffer-substring} function copies the text
5985 @emph{into} the current buffer @emph{from} the region indicated by
5986 @code{start} and @code{end} in @code{buffer}. Since the whole of the
5987 second buffer lies between @code{start} and @code{end}, the whole of
5988 the second buffer is copied into the buffer you are editing. Next,
5989 the value of point, which will be at the end of the inserted text, is
5990 recorded in the variable @code{newmark}.
5992 After the body of the outer @code{save-excursion} is evaluated, point
5993 and mark are relocated to their original places.
5995 However, it is convenient to locate a mark at the end of the newly
5996 inserted text and locate point at its beginning. The @code{newmark}
5997 variable records the end of the inserted text. In the last line of
5998 the @code{let} expression, the @code{(push-mark newmark)} expression
5999 function sets a mark to this location. (The previous location of the
6000 mark is still accessible; it is recorded on the mark ring and you can
6001 go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is
6002 located at the beginning of the inserted text, which is where it was
6003 before you called the insert function, the position of which was saved
6004 by the first @code{save-excursion}.
6007 The whole @code{let} expression looks like this:
6011 (let (start end newmark)
6015 (setq start (point-min) end (point-max)))
6016 (insert-buffer-substring buffer start end)
6017 (setq newmark (point)))
6018 (push-mark newmark))
6022 Like the @code{append-to-buffer} function, the @code{insert-buffer}
6023 function uses @code{let}, @code{save-excursion}, and
6024 @code{set-buffer}. In addition, the function illustrates one way to
6025 use @code{or}. All these functions are building blocks that we will
6026 find and use again and again.
6028 @node New insert-buffer , , Insert let, insert-buffer
6029 @comment node-name, next, previous, up
6030 @subsection New Body for @code{insert-buffer}
6031 @findex insert-buffer, new version body
6032 @findex new version body for insert-buffer
6034 The body in the GNU Emacs 22 version is more confusing than the original.
6037 It consists of two expressions,
6043 (insert-buffer-substring (get-buffer buffer))
6051 except, and this is what confuses novices, very important work is done
6052 inside the @code{push-mark} expression.
6054 The @code{get-buffer} function returns a buffer with the name
6055 provided. You will note that the function is @emph{not} called
6056 @code{get-buffer-create}; it does not create a buffer if one does not
6057 already exist. The buffer returned by @code{get-buffer}, an existing
6058 buffer, is passed to @code{insert-buffer-substring}, which inserts the
6059 whole of the buffer (since you did not specify anything else).
6061 The location into which the buffer is inserted is recorded by
6062 @code{push-mark}. Then the function returns @code{nil}, the value of
6063 its last command. Put another way, the @code{insert-buffer} function
6064 exists only to produce a side effect, inserting another buffer, not to
6067 @node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex
6068 @comment node-name, next, previous, up
6069 @section Complete Definition of @code{beginning-of-buffer}
6070 @findex beginning-of-buffer
6072 The basic structure of the @code{beginning-of-buffer} function has
6073 already been discussed. (@xref{simplified-beginning-of-buffer, , A
6074 Simplified @code{beginning-of-buffer} Definition}.)
6075 This section describes the complex part of the definition.
6077 As previously described, when invoked without an argument,
6078 @code{beginning-of-buffer} moves the cursor to the beginning of the
6079 buffer (in truth, the accessible portion of the buffer), leaving the
6080 mark at the previous position. However, when the command is invoked
6081 with a number between one and ten, the function considers that number
6082 to be a fraction of the length of the buffer, measured in tenths, and
6083 Emacs moves the cursor that fraction of the way from the beginning of
6084 the buffer. Thus, you can either call this function with the key
6085 command @kbd{M-<}, which will move the cursor to the beginning of the
6086 buffer, or with a key command such as @kbd{C-u 7 M-<} which will move
6087 the cursor to a point 70% of the way through the buffer. If a number
6088 bigger than ten is used for the argument, it moves to the end of the
6091 The @code{beginning-of-buffer} function can be called with or without an
6092 argument. The use of the argument is optional.
6095 * Optional Arguments::
6096 * beginning-of-buffer opt arg::
6097 * beginning-of-buffer complete::
6100 @node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer
6101 @subsection Optional Arguments
6103 Unless told otherwise, Lisp expects that a function with an argument in
6104 its function definition will be called with a value for that argument.
6105 If that does not happen, you get an error and a message that says
6106 @samp{Wrong number of arguments}.
6108 @cindex Optional arguments
6111 However, optional arguments are a feature of Lisp: a particular
6112 @dfn{keyword} is used to tell the Lisp interpreter that an argument is
6113 optional. The keyword is @code{&optional}. (The @samp{&} in front of
6114 @samp{optional} is part of the keyword.) In a function definition, if
6115 an argument follows the keyword @code{&optional}, no value need be
6116 passed to that argument when the function is called.
6119 The first line of the function definition of @code{beginning-of-buffer}
6120 therefore looks like this:
6123 (defun beginning-of-buffer (&optional arg)
6127 In outline, the whole function looks like this:
6131 (defun beginning-of-buffer (&optional arg)
6132 "@var{documentation}@dots{}"
6134 (or (@var{is-the-argument-a-cons-cell} arg)
6135 (and @var{are-both-transient-mark-mode-and-mark-active-true})
6137 (let (@var{determine-size-and-set-it})
6139 (@var{if-there-is-an-argument}
6140 @var{figure-out-where-to-go}
6147 The function is similar to the @code{simplified-beginning-of-buffer}
6148 function except that the @code{interactive} expression has @code{"P"}
6149 as an argument and the @code{goto-char} function is followed by an
6150 if-then-else expression that figures out where to put the cursor if
6151 there is an argument that is not a cons cell.
6153 (Since I do not explain a cons cell for many more chapters, please
6154 consider ignoring the function @code{consp}. @xref{List
6155 Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type,
6156 , Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference
6159 The @code{"P"} in the @code{interactive} expression tells Emacs to
6160 pass a prefix argument, if there is one, to the function in raw form.
6161 A prefix argument is made by typing the @key{META} key followed by a
6162 number, or by typing @kbd{C-u} and then a number. (If you don't type
6163 a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase
6164 @code{"p"} in the @code{interactive} expression causes the function to
6165 convert a prefix arg to a number.)
6167 The true-or-false-test of the @code{if} expression looks complex, but
6168 it is not: it checks whether @code{arg} has a value that is not
6169 @code{nil} and whether it is a cons cell. (That is what @code{consp}
6170 does; it checks whether its argument is a cons cell.) If @code{arg}
6171 has a value that is not @code{nil} (and is not a cons cell), which
6172 will be the case if @code{beginning-of-buffer} is called with a
6173 numeric argument, then this true-or-false-test will return true and
6174 the then-part of the @code{if} expression will be evaluated. On the
6175 other hand, if @code{beginning-of-buffer} is not called with an
6176 argument, the value of @code{arg} will be @code{nil} and the else-part
6177 of the @code{if} expression will be evaluated. The else-part is
6178 simply @code{point-min}, and when this is the outcome, the whole
6179 @code{goto-char} expression is @code{(goto-char (point-min))}, which
6180 is how we saw the @code{beginning-of-buffer} function in its
6183 @node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer
6184 @subsection @code{beginning-of-buffer} with an Argument
6186 When @code{beginning-of-buffer} is called with an argument, an
6187 expression is evaluated which calculates what value to pass to
6188 @code{goto-char}. This expression is rather complicated at first sight.
6189 It includes an inner @code{if} expression and much arithmetic. It looks
6194 (if (> (buffer-size) 10000)
6195 ;; @r{Avoid overflow for large buffer sizes!}
6196 (* (prefix-numeric-value arg)
6201 size (prefix-numeric-value arg))) 10)))
6206 * Disentangle beginning-of-buffer::
6207 * Large buffer case::
6208 * Small buffer case::
6211 @node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg
6213 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer}
6216 Like other complex-looking expressions, the conditional expression
6217 within @code{beginning-of-buffer} can be disentangled by looking at it
6218 as parts of a template, in this case, the template for an if-then-else
6219 expression. In skeletal form, the expression looks like this:
6223 (if (@var{buffer-is-large}
6224 @var{divide-buffer-size-by-10-and-multiply-by-arg}
6225 @var{else-use-alternate-calculation}
6229 The true-or-false-test of this inner @code{if} expression checks the
6230 size of the buffer. The reason for this is that the old Version 18
6231 Emacs used numbers that are no bigger than eight million or so
6232 and in the computation that followed, the programmer feared that Emacs
6233 might try to use over-large numbers if the buffer were large. The
6234 term `overflow', mentioned in the comment, means numbers that are over
6235 large. Version 21 Emacs uses larger numbers, but this code has not
6236 been touched, if only because people now look at buffers that are far,
6237 far larger than ever before.
6239 There are two cases: if the buffer is large and if it is not.
6241 @node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg
6242 @comment node-name, next, previous, up
6243 @unnumberedsubsubsec What happens in a large buffer
6245 In @code{beginning-of-buffer}, the inner @code{if} expression tests
6246 whether the size of the buffer is greater than 10,000 characters. To do
6247 this, it uses the @code{>} function and the computation of @code{size}
6248 that comes from the let expression.
6250 In the old days, the function @code{buffer-size} was used. Not only
6251 was that function called several times, it gave the size of the whole
6252 buffer, not the accessible part. The computation makes much more
6253 sense when it handles just the accessible part. (@xref{Narrowing &
6254 Widening, , Narrowing and Widening}, for more information on focusing
6255 attention to an `accessible' part.)
6258 The line looks like this:
6266 When the buffer is large, the then-part of the @code{if} expression is
6267 evaluated. It reads like this (after formatting for easy reading):
6272 (prefix-numeric-value arg)
6278 This expression is a multiplication, with two arguments to the function
6281 The first argument is @code{(prefix-numeric-value arg)}. When
6282 @code{"P"} is used as the argument for @code{interactive}, the value
6283 passed to the function as its argument is passed a ``raw prefix
6284 argument'', and not a number. (It is a number in a list.) To perform
6285 the arithmetic, a conversion is necessary, and
6286 @code{prefix-numeric-value} does the job.
6288 @findex / @r{(division)}
6290 The second argument is @code{(/ size 10)}. This expression divides
6291 the numeric value by ten --- the numeric value of the size of the
6292 accessible portion of the buffer. This produces a number that tells
6293 how many characters make up one tenth of the buffer size. (In Lisp,
6294 @code{/} is used for division, just as @code{*} is used for
6298 In the multiplication expression as a whole, this amount is multiplied
6299 by the value of the prefix argument---the multiplication looks like this:
6303 (* @var{numeric-value-of-prefix-arg}
6304 @var{number-of-characters-in-one-tenth-of-the-accessible-buffer})
6309 If, for example, the prefix argument is @samp{7}, the one-tenth value
6310 will be multiplied by 7 to give a position 70% of the way through.
6313 The result of all this is that if the accessible portion of the buffer
6314 is large, the @code{goto-char} expression reads like this:
6318 (goto-char (* (prefix-numeric-value arg)
6323 This puts the cursor where we want it.
6325 @node Small buffer case, , Large buffer case, beginning-of-buffer opt arg
6326 @comment node-name, next, previous, up
6327 @unnumberedsubsubsec What happens in a small buffer
6329 If the buffer contains fewer than 10,000 characters, a slightly
6330 different computation is performed. You might think this is not
6331 necessary, since the first computation could do the job. However, in
6332 a small buffer, the first method may not put the cursor on exactly the
6333 desired line; the second method does a better job.
6336 The code looks like this:
6338 @c Keep this on one line.
6340 (/ (+ 10 (* size (prefix-numeric-value arg))) 10))
6345 This is code in which you figure out what happens by discovering how the
6346 functions are embedded in parentheses. It is easier to read if you
6347 reformat it with each expression indented more deeply than its
6348 enclosing expression:
6356 (prefix-numeric-value arg)))
6363 Looking at parentheses, we see that the innermost operation is
6364 @code{(prefix-numeric-value arg)}, which converts the raw argument to
6365 a number. In the following expression, this number is multiplied by
6366 the size of the accessible portion of the buffer:
6369 (* size (prefix-numeric-value arg))
6373 This multiplication creates a number that may be larger than the size of
6374 the buffer---seven times larger if the argument is 7, for example. Ten
6375 is then added to this number and finally the large number is divided by
6376 ten to provide a value that is one character larger than the percentage
6377 position in the buffer.
6379 The number that results from all this is passed to @code{goto-char} and
6380 the cursor is moved to that point.
6383 @node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer
6384 @comment node-name, next, previous, up
6385 @subsection The Complete @code{beginning-of-buffer}
6388 Here is the complete text of the @code{beginning-of-buffer} function:
6394 (defun beginning-of-buffer (&optional arg)
6395 "Move point to the beginning of the buffer;
6396 leave mark at previous position.
6397 With \\[universal-argument] prefix,
6398 do not set mark at previous position.
6400 put point N/10 of the way from the beginning.
6402 If the buffer is narrowed,
6403 this command uses the beginning and size
6404 of the accessible part of the buffer.
6408 Don't use this command in Lisp programs!
6409 \(goto-char (point-min)) is faster
6410 and avoids clobbering the mark."
6413 (and transient-mark-mode mark-active)
6417 (let ((size (- (point-max) (point-min))))
6418 (goto-char (if (and arg (not (consp arg)))
6421 ;; Avoid overflow for large buffer sizes!
6422 (* (prefix-numeric-value arg)
6424 (/ (+ 10 (* size (prefix-numeric-value arg))) 10)))
6426 (if arg (forward-line 1)))
6431 From before GNU Emacs 22
6434 (defun beginning-of-buffer (&optional arg)
6435 "Move point to the beginning of the buffer;
6436 leave mark at previous position.
6437 With arg N, put point N/10 of the way
6438 from the true beginning.
6441 Don't use this in Lisp programs!
6442 \(goto-char (point-min)) is faster
6443 and does not set the mark."
6450 (if (> (buffer-size) 10000)
6451 ;; @r{Avoid overflow for large buffer sizes!}
6452 (* (prefix-numeric-value arg)
6453 (/ (buffer-size) 10))
6456 (/ (+ 10 (* (buffer-size)
6457 (prefix-numeric-value arg)))
6460 (if arg (forward-line 1)))
6466 Except for two small points, the previous discussion shows how this
6467 function works. The first point deals with a detail in the
6468 documentation string, and the second point concerns the last line of
6472 In the documentation string, there is reference to an expression:
6475 \\[universal-argument]
6479 A @samp{\\} is used before the first square bracket of this
6480 expression. This @samp{\\} tells the Lisp interpreter to substitute
6481 whatever key is currently bound to the @samp{[@dots{}]}. In the case
6482 of @code{universal-argument}, that is usually @kbd{C-u}, but it might
6483 be different. (@xref{Documentation Tips, , Tips for Documentation
6484 Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more
6488 Finally, the last line of the @code{beginning-of-buffer} command says
6489 to move point to the beginning of the next line if the command is
6490 invoked with an argument:
6493 (if arg (forward-line 1)))
6497 This puts the cursor at the beginning of the first line after the
6498 appropriate tenths position in the buffer. This is a flourish that
6499 means that the cursor is always located @emph{at least} the requested
6500 tenths of the way through the buffer, which is a nicety that is,
6501 perhaps, not necessary, but which, if it did not occur, would be sure
6504 On the other hand, it also means that if you specify the command with
6505 a @kbd{C-u}, but without a number, that is to say, if the `raw prefix
6506 argument' is simply a cons cell, then the command puts you at the
6507 beginning of the second line @dots{} I don't know whether this is
6508 intended or whether no one has dealt with the code to avoid this
6511 @node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex
6512 @comment node-name, next, previous, up
6515 Here is a brief summary of some of the topics covered in this chapter.
6519 Evaluate each argument in sequence, and return the value of the first
6520 argument that is not @code{nil}; if none return a value that is not
6521 @code{nil}, return @code{nil}. In brief, return the first true value
6522 of the arguments; return a true value if one @emph{or} any of the
6526 Evaluate each argument in sequence, and if any are @code{nil}, return
6527 @code{nil}; if none are @code{nil}, return the value of the last
6528 argument. In brief, return a true value only if all the arguments are
6529 true; return a true value if one @emph{and} each of the others is
6533 A keyword used to indicate that an argument to a function definition
6534 is optional; this means that the function can be evaluated without the
6535 argument, if desired.
6537 @item prefix-numeric-value
6538 Convert the `raw prefix argument' produced by @code{(interactive
6539 "P")} to a numeric value.
6542 Move point forward to the beginning of the next line, or if the argument
6543 is greater than one, forward that many lines. If it can't move as far
6544 forward as it is supposed to, @code{forward-line} goes forward as far as
6545 it can and then returns a count of the number of additional lines it was
6546 supposed to move but couldn't.
6549 Delete the entire contents of the current buffer.
6552 Return @code{t} if its argument is a buffer; otherwise return @code{nil}.
6555 @node optional Exercise, , Second Buffer Related Review, More Complex
6556 @section @code{optional} Argument Exercise
6558 Write an interactive function with an optional argument that tests
6559 whether its argument, a number, is greater than or equal to, or else,
6560 less than the value of @code{fill-column}, and tells you which, in a
6561 message. However, if you do not pass an argument to the function, use
6562 56 as a default value.
6564 @node Narrowing & Widening, car cdr & cons, More Complex, Top
6565 @comment node-name, next, previous, up
6566 @chapter Narrowing and Widening
6567 @cindex Focusing attention (narrowing)
6571 Narrowing is a feature of Emacs that makes it possible for you to focus
6572 on a specific part of a buffer, and work without accidentally changing
6573 other parts. Narrowing is normally disabled since it can confuse
6577 * Narrowing advantages::
6578 * save-restriction::
6583 @node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening
6585 @unnumberedsec The Advantages of Narrowing
6588 With narrowing, the rest of a buffer is made invisible, as if it weren't
6589 there. This is an advantage if, for example, you want to replace a word
6590 in one part of a buffer but not in another: you narrow to the part you want
6591 and the replacement is carried out only in that section, not in the rest
6592 of the buffer. Searches will only work within a narrowed region, not
6593 outside of one, so if you are fixing a part of a document, you can keep
6594 yourself from accidentally finding parts you do not need to fix by
6595 narrowing just to the region you want.
6596 (The key binding for @code{narrow-to-region} is @kbd{C-x n n}.)
6598 However, narrowing does make the rest of the buffer invisible, which
6599 can scare people who inadvertently invoke narrowing and think they
6600 have deleted a part of their file. Moreover, the @code{undo} command
6601 (which is usually bound to @kbd{C-x u}) does not turn off narrowing
6602 (nor should it), so people can become quite desperate if they do not
6603 know that they can return the rest of a buffer to visibility with the
6604 @code{widen} command.
6605 (The key binding for @code{widen} is @kbd{C-x n w}.)
6607 Narrowing is just as useful to the Lisp interpreter as to a human.
6608 Often, an Emacs Lisp function is designed to work on just part of a
6609 buffer; or conversely, an Emacs Lisp function needs to work on all of a
6610 buffer that has been narrowed. The @code{what-line} function, for
6611 example, removes the narrowing from a buffer, if it has any narrowing
6612 and when it has finished its job, restores the narrowing to what it was.
6613 On the other hand, the @code{count-lines} function, which is called by
6614 @code{what-line}, uses narrowing to restrict itself to just that portion
6615 of the buffer in which it is interested and then restores the previous
6618 @node save-restriction, what-line, Narrowing advantages, Narrowing & Widening
6619 @comment node-name, next, previous, up
6620 @section The @code{save-restriction} Special Form
6621 @findex save-restriction
6623 In Emacs Lisp, you can use the @code{save-restriction} special form to
6624 keep track of whatever narrowing is in effect, if any. When the Lisp
6625 interpreter meets with @code{save-restriction}, it executes the code
6626 in the body of the @code{save-restriction} expression, and then undoes
6627 any changes to narrowing that the code caused. If, for example, the
6628 buffer is narrowed and the code that follows @code{save-restriction}
6629 gets rid of the narrowing, @code{save-restriction} returns the buffer
6630 to its narrowed region afterwards. In the @code{what-line} command,
6631 any narrowing the buffer may have is undone by the @code{widen}
6632 command that immediately follows the @code{save-restriction} command.
6633 Any original narrowing is restored just before the completion of the
6637 The template for a @code{save-restriction} expression is simple:
6647 The body of the @code{save-restriction} is one or more expressions that
6648 will be evaluated in sequence by the Lisp interpreter.
6650 Finally, a point to note: when you use both @code{save-excursion} and
6651 @code{save-restriction}, one right after the other, you should use
6652 @code{save-excursion} outermost. If you write them in reverse order,
6653 you may fail to record narrowing in the buffer to which Emacs switches
6654 after calling @code{save-excursion}. Thus, when written together,
6655 @code{save-excursion} and @code{save-restriction} should be written
6666 In other circumstances, when not written together, the
6667 @code{save-excursion} and @code{save-restriction} special forms must
6668 be written in the order appropriate to the function.
6684 /usr/local/src/emacs/lisp/simple.el
6687 "Print the current buffer line number and narrowed line number of point."
6689 (let ((start (point-min))
6690 (n (line-number-at-pos)))
6692 (message "Line %d" n)
6696 (message "line %d (narrowed line %d)"
6697 (+ n (line-number-at-pos start) -1) n))))))
6699 (defun line-number-at-pos (&optional pos)
6700 "Return (narrowed) buffer line number at position POS.
6701 If POS is nil, use current buffer location.
6702 Counting starts at (point-min), so the value refers
6703 to the contents of the accessible portion of the buffer."
6704 (let ((opoint (or pos (point))) start)
6706 (goto-char (point-min))
6707 (setq start (point))
6710 (1+ (count-lines start (point))))))
6712 (defun count-lines (start end)
6713 "Return number of lines between START and END.
6714 This is usually the number of newlines between them,
6715 but can be one more if START is not equal to END
6716 and the greater of them is not at the start of a line."
6719 (narrow-to-region start end)
6720 (goto-char (point-min))
6721 (if (eq selective-display t)
6724 (while (re-search-forward "[\n\C-m]" nil t 40)
6725 (setq done (+ 40 done)))
6726 (while (re-search-forward "[\n\C-m]" nil t 1)
6727 (setq done (+ 1 done)))
6728 (goto-char (point-max))
6729 (if (and (/= start end)
6733 (- (buffer-size) (forward-line (buffer-size)))))))
6736 @node what-line, narrow Exercise, save-restriction, Narrowing & Widening
6737 @comment node-name, next, previous, up
6738 @section @code{what-line}
6740 @cindex Widening, example of
6742 The @code{what-line} command tells you the number of the line in which
6743 the cursor is located. The function illustrates the use of the
6744 @code{save-restriction} and @code{save-excursion} commands. Here is the
6745 original text of the function:
6750 "Print the current line number (in the buffer) of point."
6757 (1+ (count-lines 1 (point)))))))
6761 (In recent versions of GNU Emacs, the @code{what-line} function has
6762 been expanded to tell you your line number in a narrowed buffer as
6763 well as your line number in a widened buffer. The recent version is
6764 more complex than the version shown here. If you feel adventurous,
6765 you might want to look at it after figuring out how this version
6766 works. You will probably need to use @kbd{C-h f}
6767 (@code{describe-function}). The newer version uses a conditional to
6768 determine whether the buffer has been narrowed.
6770 (Also, it uses @code{line-number-at-pos}, which among other simple
6771 expressions, such as @code{(goto-char (point-min))}, moves point to
6772 the beginning of the current line with @code{(forward-line 0)} rather
6773 than @code{beginning-of-line}.)
6775 The @code{what-line} function as shown here has a documentation line
6776 and is interactive, as you would expect. The next two lines use the
6777 functions @code{save-restriction} and @code{widen}.
6779 The @code{save-restriction} special form notes whatever narrowing is in
6780 effect, if any, in the current buffer and restores that narrowing after
6781 the code in the body of the @code{save-restriction} has been evaluated.
6783 The @code{save-restriction} special form is followed by @code{widen}.
6784 This function undoes any narrowing the current buffer may have had
6785 when @code{what-line} was called. (The narrowing that was there is
6786 the narrowing that @code{save-restriction} remembers.) This widening
6787 makes it possible for the line counting commands to count from the
6788 beginning of the buffer. Otherwise, they would have been limited to
6789 counting within the accessible region. Any original narrowing is
6790 restored just before the completion of the function by the
6791 @code{save-restriction} special form.
6793 The call to @code{widen} is followed by @code{save-excursion}, which
6794 saves the location of the cursor (i.e., of point) and of the mark, and
6795 restores them after the code in the body of the @code{save-excursion}
6796 uses the @code{beginning-of-line} function to move point.
6798 (Note that the @code{(widen)} expression comes between the
6799 @code{save-restriction} and @code{save-excursion} special forms. When
6800 you write the two @code{save- @dots{}} expressions in sequence, write
6801 @code{save-excursion} outermost.)
6804 The last two lines of the @code{what-line} function are functions to
6805 count the number of lines in the buffer and then print the number in the
6811 (1+ (count-lines 1 (point)))))))
6815 The @code{message} function prints a one-line message at the bottom of
6816 the Emacs screen. The first argument is inside of quotation marks and
6817 is printed as a string of characters. However, it may contain a
6818 @samp{%d} expression to print a following argument. @samp{%d} prints
6819 the argument as a decimal, so the message will say something such as
6823 The number that is printed in place of the @samp{%d} is computed by the
6824 last line of the function:
6827 (1+ (count-lines 1 (point)))
6833 (defun count-lines (start end)
6834 "Return number of lines between START and END.
6835 This is usually the number of newlines between them,
6836 but can be one more if START is not equal to END
6837 and the greater of them is not at the start of a line."
6840 (narrow-to-region start end)
6841 (goto-char (point-min))
6842 (if (eq selective-display t)
6845 (while (re-search-forward "[\n\C-m]" nil t 40)
6846 (setq done (+ 40 done)))
6847 (while (re-search-forward "[\n\C-m]" nil t 1)
6848 (setq done (+ 1 done)))
6849 (goto-char (point-max))
6850 (if (and (/= start end)
6854 (- (buffer-size) (forward-line (buffer-size)))))))
6858 What this does is count the lines from the first position of the
6859 buffer, indicated by the @code{1}, up to @code{(point)}, and then add
6860 one to that number. (The @code{1+} function adds one to its
6861 argument.) We add one to it because line 2 has only one line before
6862 it, and @code{count-lines} counts only the lines @emph{before} the
6865 After @code{count-lines} has done its job, and the message has been
6866 printed in the echo area, the @code{save-excursion} restores point and
6867 mark to their original positions; and @code{save-restriction} restores
6868 the original narrowing, if any.
6870 @node narrow Exercise, , what-line, Narrowing & Widening
6871 @section Exercise with Narrowing
6873 Write a function that will display the first 60 characters of the
6874 current buffer, even if you have narrowed the buffer to its latter
6875 half so that the first line is inaccessible. Restore point, mark, and
6876 narrowing. For this exercise, you need to use a whole potpourri of
6877 functions, including @code{save-restriction}, @code{widen},
6878 @code{goto-char}, @code{point-min}, @code{message}, and
6879 @code{buffer-substring}.
6881 @cindex Properties, mention of @code{buffer-substring-no-properties}
6882 (@code{buffer-substring} is a previously unmentioned function you will
6883 have to investigate yourself; or perhaps you will have to use
6884 @code{buffer-substring-no-properties} or
6885 @code{filter-buffer-substring} @dots{}, yet other functions. Text
6886 properties are a feature otherwise not discussed here. @xref{Text
6887 Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference
6890 Additionally, do you really need @code{goto-char} or @code{point-min}?
6891 Or can you write the function without them?)
6893 @node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top
6894 @comment node-name, next, previous, up
6895 @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
6896 @findex car, @r{introduced}
6897 @findex cdr, @r{introduced}
6899 In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental
6900 functions. The @code{cons} function is used to construct lists, and
6901 the @code{car} and @code{cdr} functions are used to take them apart.
6903 In the walk through of the @code{copy-region-as-kill} function, we
6904 will see @code{cons} as well as two variants on @code{cdr},
6905 namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.)
6918 @node Strange Names, car & cdr, car cdr & cons, car cdr & cons
6920 @unnumberedsec Strange Names
6923 The name of the @code{cons} function is not unreasonable: it is an
6924 abbreviation of the word `construct'. The origins of the names for
6925 @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car}
6926 is an acronym from the phrase `Contents of the Address part of the
6927 Register'; and @code{cdr} (pronounced `could-er') is an acronym from
6928 the phrase `Contents of the Decrement part of the Register'. These
6929 phrases refer to specific pieces of hardware on the very early
6930 computer on which the original Lisp was developed. Besides being
6931 obsolete, the phrases have been completely irrelevant for more than 25
6932 years to anyone thinking about Lisp. Nonetheless, although a few
6933 brave scholars have begun to use more reasonable names for these
6934 functions, the old terms are still in use. In particular, since the
6935 terms are used in the Emacs Lisp source code, we will use them in this
6938 @node car & cdr, cons, Strange Names, car cdr & cons
6939 @comment node-name, next, previous, up
6940 @section @code{car} and @code{cdr}
6942 The @sc{car} of a list is, quite simply, the first item in the list.
6943 Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is
6947 If you are reading this in Info in GNU Emacs, you can see this by
6948 evaluating the following:
6951 (car '(rose violet daisy buttercup))
6955 After evaluating the expression, @code{rose} will appear in the echo
6958 Clearly, a more reasonable name for the @code{car} function would be
6959 @code{first} and this is often suggested.
6961 @code{car} does not remove the first item from the list; it only reports
6962 what it is. After @code{car} has been applied to a list, the list is
6963 still the same as it was. In the jargon, @code{car} is
6964 `non-destructive'. This feature turns out to be important.
6966 The @sc{cdr} of a list is the rest of the list, that is, the
6967 @code{cdr} function returns the part of the list that follows the
6968 first item. Thus, while the @sc{car} of the list @code{'(rose violet
6969 daisy buttercup)} is @code{rose}, the rest of the list, the value
6970 returned by the @code{cdr} function, is @code{(violet daisy
6974 You can see this by evaluating the following in the usual way:
6977 (cdr '(rose violet daisy buttercup))
6981 When you evaluate this, @code{(violet daisy buttercup)} will appear in
6984 Like @code{car}, @code{cdr} does not remove any elements from the
6985 list---it just returns a report of what the second and subsequent
6988 Incidentally, in the example, the list of flowers is quoted. If it were
6989 not, the Lisp interpreter would try to evaluate the list by calling
6990 @code{rose} as a function. In this example, we do not want to do that.
6992 Clearly, a more reasonable name for @code{cdr} would be @code{rest}.
6994 (There is a lesson here: when you name new functions, consider very
6995 carefully what you are doing, since you may be stuck with the names
6996 for far longer than you expect. The reason this document perpetuates
6997 these names is that the Emacs Lisp source code uses them, and if I did
6998 not use them, you would have a hard time reading the code; but do,
6999 please, try to avoid using these terms yourself. The people who come
7000 after you will be grateful to you.)
7002 When @code{car} and @code{cdr} are applied to a list made up of symbols,
7003 such as the list @code{(pine fir oak maple)}, the element of the list
7004 returned by the function @code{car} is the symbol @code{pine} without
7005 any parentheses around it. @code{pine} is the first element in the
7006 list. However, the @sc{cdr} of the list is a list itself, @code{(fir
7007 oak maple)}, as you can see by evaluating the following expressions in
7012 (car '(pine fir oak maple))
7014 (cdr '(pine fir oak maple))
7018 On the other hand, in a list of lists, the first element is itself a
7019 list. @code{car} returns this first element as a list. For example,
7020 the following list contains three sub-lists, a list of carnivores, a
7021 list of herbivores and a list of sea mammals:
7025 (car '((lion tiger cheetah)
7026 (gazelle antelope zebra)
7027 (whale dolphin seal)))
7032 In this example, the first element or @sc{car} of the list is the list of
7033 carnivores, @code{(lion tiger cheetah)}, and the rest of the list is
7034 @code{((gazelle antelope zebra) (whale dolphin seal))}.
7038 (cdr '((lion tiger cheetah)
7039 (gazelle antelope zebra)
7040 (whale dolphin seal)))
7044 It is worth saying again that @code{car} and @code{cdr} are
7045 non-destructive---that is, they do not modify or change lists to which
7046 they are applied. This is very important for how they are used.
7048 Also, in the first chapter, in the discussion about atoms, I said that
7049 in Lisp, ``certain kinds of atom, such as an array, can be separated
7050 into parts; but the mechanism for doing this is different from the
7051 mechanism for splitting a list. As far as Lisp is concerned, the
7052 atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The
7053 @code{car} and @code{cdr} functions are used for splitting lists and
7054 are considered fundamental to Lisp. Since they cannot split or gain
7055 access to the parts of an array, an array is considered an atom.
7056 Conversely, the other fundamental function, @code{cons}, can put
7057 together or construct a list, but not an array. (Arrays are handled
7058 by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU
7059 Emacs Lisp Reference Manual}.)
7061 @node cons, nthcdr, car & cdr, car cdr & cons
7062 @comment node-name, next, previous, up
7063 @section @code{cons}
7064 @findex cons, @r{introduced}
7066 The @code{cons} function constructs lists; it is the inverse of
7067 @code{car} and @code{cdr}. For example, @code{cons} can be used to make
7068 a four element list from the three element list, @code{(fir oak maple)}:
7071 (cons 'pine '(fir oak maple))
7076 After evaluating this list, you will see
7079 (pine fir oak maple)
7083 appear in the echo area. @code{cons} causes the creation of a new
7084 list in which the element is followed by the elements of the original
7087 We often say that `@code{cons} puts a new element at the beginning of
7088 a list; it attaches or pushes elements onto the list', but this
7089 phrasing can be misleading, since @code{cons} does not change an
7090 existing list, but creates a new one.
7092 Like @code{car} and @code{cdr}, @code{cons} is non-destructive.
7099 @node Build a list, length, cons, cons
7101 @unnumberedsubsec Build a list
7104 @code{cons} must have a list to attach to.@footnote{Actually, you can
7105 @code{cons} an element to an atom to produce a dotted pair. Dotted
7106 pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted
7107 Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You
7108 cannot start from absolutely nothing. If you are building a list, you
7109 need to provide at least an empty list at the beginning. Here is a
7110 series of @code{cons} expressions that build up a list of flowers. If
7111 you are reading this in Info in GNU Emacs, you can evaluate each of
7112 the expressions in the usual way; the value is printed in this text
7113 after @samp{@result{}}, which you may read as `evaluates to'.
7117 (cons 'buttercup ())
7118 @result{} (buttercup)
7122 (cons 'daisy '(buttercup))
7123 @result{} (daisy buttercup)
7127 (cons 'violet '(daisy buttercup))
7128 @result{} (violet daisy buttercup)
7132 (cons 'rose '(violet daisy buttercup))
7133 @result{} (rose violet daisy buttercup)
7138 In the first example, the empty list is shown as @code{()} and a list
7139 made up of @code{buttercup} followed by the empty list is constructed.
7140 As you can see, the empty list is not shown in the list that was
7141 constructed. All that you see is @code{(buttercup)}. The empty list is
7142 not counted as an element of a list because there is nothing in an empty
7143 list. Generally speaking, an empty list is invisible.
7145 The second example, @code{(cons 'daisy '(buttercup))} constructs a new,
7146 two element list by putting @code{daisy} in front of @code{buttercup};
7147 and the third example constructs a three element list by putting
7148 @code{violet} in front of @code{daisy} and @code{buttercup}.
7150 @node length, , Build a list, cons
7151 @comment node-name, next, previous, up
7152 @subsection Find the Length of a List: @code{length}
7155 You can find out how many elements there are in a list by using the Lisp
7156 function @code{length}, as in the following examples:
7160 (length '(buttercup))
7165 (length '(daisy buttercup))
7170 (length (cons 'violet '(daisy buttercup)))
7176 In the third example, the @code{cons} function is used to construct a
7177 three element list which is then passed to the @code{length} function as
7181 We can also use @code{length} to count the number of elements in an
7192 As you would expect, the number of elements in an empty list is zero.
7194 An interesting experiment is to find out what happens if you try to find
7195 the length of no list at all; that is, if you try to call @code{length}
7196 without giving it an argument, not even an empty list:
7204 What you see, if you evaluate this, is the error message
7207 Lisp error: (wrong-number-of-arguments length 0)
7211 This means that the function receives the wrong number of
7212 arguments, zero, when it expects some other number of arguments. In
7213 this case, one argument is expected, the argument being a list whose
7214 length the function is measuring. (Note that @emph{one} list is
7215 @emph{one} argument, even if the list has many elements inside it.)
7217 The part of the error message that says @samp{length} is the name of
7221 @code{length} is still a subroutine, but you need C-h f to discover that.
7223 In an earlier version:
7224 This is written with a special notation, @samp{#<subr},
7225 that indicates that the function @code{length} is one of the primitive
7226 functions written in C rather than in Emacs Lisp. (@samp{subr} is an
7227 abbreviation for `subroutine'.) @xref{What Is a Function, , What Is a
7228 Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more
7232 @node nthcdr, nth, cons, car cdr & cons
7233 @comment node-name, next, previous, up
7234 @section @code{nthcdr}
7237 The @code{nthcdr} function is associated with the @code{cdr} function.
7238 What it does is take the @sc{cdr} of a list repeatedly.
7240 If you take the @sc{cdr} of the list @code{(pine fir
7241 oak maple)}, you will be returned the list @code{(fir oak maple)}. If you
7242 repeat this on what was returned, you will be returned the list
7243 @code{(oak maple)}. (Of course, repeated @sc{cdr}ing on the original
7244 list will just give you the original @sc{cdr} since the function does
7245 not change the list. You need to evaluate the @sc{cdr} of the
7246 @sc{cdr} and so on.) If you continue this, eventually you will be
7247 returned an empty list, which in this case, instead of being shown as
7248 @code{()} is shown as @code{nil}.
7251 For review, here is a series of repeated @sc{cdr}s, the text following
7252 the @samp{@result{}} shows what is returned.
7256 (cdr '(pine fir oak maple))
7257 @result{}(fir oak maple)
7261 (cdr '(fir oak maple))
7262 @result{} (oak maple)
7287 You can also do several @sc{cdr}s without printing the values in
7292 (cdr (cdr '(pine fir oak maple)))
7293 @result{} (oak maple)
7298 In this example, the Lisp interpreter evaluates the innermost list first.
7299 The innermost list is quoted, so it just passes the list as it is to the
7300 innermost @code{cdr}. This @code{cdr} passes a list made up of the
7301 second and subsequent elements of the list to the outermost @code{cdr},
7302 which produces a list composed of the third and subsequent elements of
7303 the original list. In this example, the @code{cdr} function is repeated
7304 and returns a list that consists of the original list without its
7307 The @code{nthcdr} function does the same as repeating the call to
7308 @code{cdr}. In the following example, the argument 2 is passed to the
7309 function @code{nthcdr}, along with the list, and the value returned is
7310 the list without its first two items, which is exactly the same
7311 as repeating @code{cdr} twice on the list:
7315 (nthcdr 2 '(pine fir oak maple))
7316 @result{} (oak maple)
7321 Using the original four element list, we can see what happens when
7322 various numeric arguments are passed to @code{nthcdr}, including 0, 1,
7327 ;; @r{Leave the list as it was.}
7328 (nthcdr 0 '(pine fir oak maple))
7329 @result{} (pine fir oak maple)
7333 ;; @r{Return a copy without the first element.}
7334 (nthcdr 1 '(pine fir oak maple))
7335 @result{} (fir oak maple)
7339 ;; @r{Return a copy of the list without three elements.}
7340 (nthcdr 3 '(pine fir oak maple))
7345 ;; @r{Return a copy lacking all four elements.}
7346 (nthcdr 4 '(pine fir oak maple))
7351 ;; @r{Return a copy lacking all elements.}
7352 (nthcdr 5 '(pine fir oak maple))
7357 @node nth, setcar, nthcdr, car cdr & cons
7358 @comment node-name, next, previous, up
7362 The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly.
7363 The @code{nth} function takes the @sc{car} of the result returned by
7364 @code{nthcdr}. It returns the Nth element of the list.
7367 Thus, if it were not defined in C for speed, the definition of
7368 @code{nth} would be:
7373 "Returns the Nth element of LIST.
7374 N counts from zero. If LIST is not that long, nil is returned."
7375 (car (nthcdr n list)))
7380 (Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el},
7381 but its definition was redone in C in the 1980s.)
7383 The @code{nth} function returns a single element of a list.
7384 This can be very convenient.
7386 Note that the elements are numbered from zero, not one. That is to
7387 say, the first element of a list, its @sc{car} is the zeroth element.
7388 This is called `zero-based' counting and often bothers people who
7389 are accustomed to the first element in a list being number one, which
7397 (nth 0 '("one" "two" "three"))
7400 (nth 1 '("one" "two" "three"))
7405 It is worth mentioning that @code{nth}, like @code{nthcdr} and
7406 @code{cdr}, does not change the original list---the function is
7407 non-destructive. This is in sharp contrast to the @code{setcar} and
7408 @code{setcdr} functions.
7410 @node setcar, setcdr, nth, car cdr & cons
7411 @comment node-name, next, previous, up
7412 @section @code{setcar}
7415 As you might guess from their names, the @code{setcar} and @code{setcdr}
7416 functions set the @sc{car} or the @sc{cdr} of a list to a new value.
7417 They actually change the original list, unlike @code{car} and @code{cdr}
7418 which leave the original list as it was. One way to find out how this
7419 works is to experiment. We will start with the @code{setcar} function.
7422 First, we can make a list and then set the value of a variable to the
7423 list, using the @code{setq} function. Here is a list of animals:
7426 (setq animals '(antelope giraffe lion tiger))
7430 If you are reading this in Info inside of GNU Emacs, you can evaluate
7431 this expression in the usual fashion, by positioning the cursor after
7432 the expression and typing @kbd{C-x C-e}. (I'm doing this right here
7433 as I write this. This is one of the advantages of having the
7434 interpreter built into the computing environment. Incidentally, when
7435 there is nothing on the line after the final parentheses, such as a
7436 comment, point can be on the next line. Thus, if your cursor is in
7437 the first column of the next line, you do not need to move it.
7438 Indeed, Emacs permits any amount of white space after the final
7442 When we evaluate the variable @code{animals}, we see that it is bound to
7443 the list @code{(antelope giraffe lion tiger)}:
7448 @result{} (antelope giraffe lion tiger)
7453 Put another way, the variable @code{animals} points to the list
7454 @code{(antelope giraffe lion tiger)}.
7456 Next, evaluate the function @code{setcar} while passing it two
7457 arguments, the variable @code{animals} and the quoted symbol
7458 @code{hippopotamus}; this is done by writing the three element list
7459 @code{(setcar animals 'hippopotamus)} and then evaluating it in the
7463 (setcar animals 'hippopotamus)
7468 After evaluating this expression, evaluate the variable @code{animals}
7469 again. You will see that the list of animals has changed:
7474 @result{} (hippopotamus giraffe lion tiger)
7479 The first element on the list, @code{antelope} is replaced by
7480 @code{hippopotamus}.
7482 So we can see that @code{setcar} did not add a new element to the list
7483 as @code{cons} would have; it replaced @code{antelope} with
7484 @code{hippopotamus}; it @emph{changed} the list.
7486 @node setcdr, cons Exercise, setcar, car cdr & cons
7487 @comment node-name, next, previous, up
7488 @section @code{setcdr}
7491 The @code{setcdr} function is similar to the @code{setcar} function,
7492 except that the function replaces the second and subsequent elements of
7493 a list rather than the first element.
7495 (To see how to change the last element of a list, look ahead to
7496 @ref{kill-new function, , The @code{kill-new} function}, which uses
7497 the @code{nthcdr} and @code{setcdr} functions.)
7500 To see how this works, set the value of the variable to a list of
7501 domesticated animals by evaluating the following expression:
7504 (setq domesticated-animals '(horse cow sheep goat))
7509 If you now evaluate the list, you will be returned the list
7510 @code{(horse cow sheep goat)}:
7514 domesticated-animals
7515 @result{} (horse cow sheep goat)
7520 Next, evaluate @code{setcdr} with two arguments, the name of the
7521 variable which has a list as its value, and the list to which the
7522 @sc{cdr} of the first list will be set;
7525 (setcdr domesticated-animals '(cat dog))
7529 If you evaluate this expression, the list @code{(cat dog)} will appear
7530 in the echo area. This is the value returned by the function. The
7531 result we are interested in is the ``side effect'', which we can see by
7532 evaluating the variable @code{domesticated-animals}:
7536 domesticated-animals
7537 @result{} (horse cat dog)
7542 Indeed, the list is changed from @code{(horse cow sheep goat)} to
7543 @code{(horse cat dog)}. The @sc{cdr} of the list is changed from
7544 @code{(cow sheep goat)} to @code{(cat dog)}.
7546 @node cons Exercise, , setcdr, car cdr & cons
7549 Construct a list of four birds by evaluating several expressions with
7550 @code{cons}. Find out what happens when you @code{cons} a list onto
7551 itself. Replace the first element of the list of four birds with a
7552 fish. Replace the rest of that list with a list of other fish.
7554 @node Cutting & Storing Text, List Implementation, car cdr & cons, Top
7555 @comment node-name, next, previous, up
7556 @chapter Cutting and Storing Text
7557 @cindex Cutting and storing text
7558 @cindex Storing and cutting text
7559 @cindex Killing text
7560 @cindex Clipping text
7561 @cindex Erasing text
7562 @cindex Deleting text
7564 Whenever you cut or clip text out of a buffer with a `kill' command in
7565 GNU Emacs, it is stored in a list and you can bring it back with a
7568 (The use of the word `kill' in Emacs for processes which specifically
7569 @emph{do not} destroy the values of the entities is an unfortunate
7570 historical accident. A much more appropriate word would be `clip' since
7571 that is what the kill commands do; they clip text out of a buffer and
7572 put it into storage from which it can be brought back. I have often
7573 been tempted to replace globally all occurrences of `kill' in the Emacs
7574 sources with `clip' and all occurrences of `killed' with `clipped'.)
7580 * copy-region-as-kill::
7581 * Digression into C::
7583 * cons & search-fwd Review::
7584 * search Exercises::
7587 @node Storing Text, zap-to-char, Cutting & Storing Text, Cutting & Storing Text
7589 @unnumberedsec Storing Text in a List
7592 When text is cut out of a buffer, it is stored on a list. Successive
7593 pieces of text are stored on the list successively, so the list might
7597 ("a piece of text" "previous piece")
7602 The function @code{cons} can be used to create a new list from a piece
7603 of text (an `atom', to use the jargon) and an existing list, like
7608 (cons "another piece"
7609 '("a piece of text" "previous piece"))
7615 If you evaluate this expression, a list of three elements will appear in
7619 ("another piece" "a piece of text" "previous piece")
7622 With the @code{car} and @code{nthcdr} functions, you can retrieve
7623 whichever piece of text you want. For example, in the following code,
7624 @code{nthcdr 1 @dots{}} returns the list with the first item removed;
7625 and the @code{car} returns the first element of that remainder---the
7626 second element of the original list:
7630 (car (nthcdr 1 '("another piece"
7633 @result{} "a piece of text"
7637 The actual functions in Emacs are more complex than this, of course.
7638 The code for cutting and retrieving text has to be written so that
7639 Emacs can figure out which element in the list you want---the first,
7640 second, third, or whatever. In addition, when you get to the end of
7641 the list, Emacs should give you the first element of the list, rather
7642 than nothing at all.
7644 The list that holds the pieces of text is called the @dfn{kill ring}.
7645 This chapter leads up to a description of the kill ring and how it is
7646 used by first tracing how the @code{zap-to-char} function works. This
7647 function uses (or `calls') a function that invokes a function that
7648 manipulates the kill ring. Thus, before reaching the mountains, we
7649 climb the foothills.
7651 A subsequent chapter describes how text that is cut from the buffer is
7652 retrieved. @xref{Yanking, , Yanking Text Back}.
7654 @node zap-to-char, kill-region, Storing Text, Cutting & Storing Text
7655 @comment node-name, next, previous, up
7656 @section @code{zap-to-char}
7659 The @code{zap-to-char} function changed a little between GNU Emacs
7660 version 19 and GNU Emacs version 22. However, @code{zap-to-char}
7661 calls another function, @code{kill-region}, which enjoyed a major
7664 The @code{kill-region} function in Emacs 19 is complex, but does not
7665 use code that is important at this time. We will skip it.
7667 The @code{kill-region} function in Emacs 22 is easier to read than the
7668 same function in Emacs 19 and introduces a very important concept,
7669 that of error handling. We will walk through the function.
7671 But first, let us look at the interactive @code{zap-to-char} function.
7674 * Complete zap-to-char::
7675 * zap-to-char interactive::
7676 * zap-to-char body::
7679 * Summing up zap-to-char::
7682 @node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char
7684 @unnumberedsubsec The Complete @code{zap-to-char} Implementation
7687 The GNU Emacs version 19 and version 21 implementations of the
7688 @code{zap-to-char} function are nearly identical in form, and they
7689 work alike. The function removes the text in the region between the
7690 location of the cursor (i.e., of point) up to and including the next
7691 occurrence of a specified character. The text that @code{zap-to-char}
7692 removes is put in the kill ring; and it can be retrieved from the kill
7693 ring by typing @kbd{C-y} (@code{yank}). If the command is given an
7694 argument, it removes text through that number of occurrences. Thus,
7695 if the cursor were at the beginning of this sentence and the character
7696 were @samp{s}, @samp{Thus} would be removed. If the argument were
7697 two, @samp{Thus, if the curs} would be removed, up to and including
7698 the @samp{s} in @samp{cursor}.
7700 If the specified character is not found, @code{zap-to-char} will say
7701 ``Search failed'', tell you the character you typed, and not remove
7704 In order to determine how much text to remove, @code{zap-to-char} uses
7705 a search function. Searches are used extensively in code that
7706 manipulates text, and we will focus attention on them as well as on the
7710 @c GNU Emacs version 19
7711 (defun zap-to-char (arg char) ; version 19 implementation
7712 "Kill up to and including ARG'th occurrence of CHAR.
7713 Goes backward if ARG is negative; error if CHAR not found."
7714 (interactive "*p\ncZap to char: ")
7715 (kill-region (point)
7718 (char-to-string char) nil nil arg)
7723 Here is the complete text of the version 22 implementation of the function:
7728 (defun zap-to-char (arg char)
7729 "Kill up to and including ARG'th occurrence of CHAR.
7730 Case is ignored if `case-fold-search' is non-nil in the current buffer.
7731 Goes backward if ARG is negative; error if CHAR not found."
7732 (interactive "p\ncZap to char: ")
7733 (if (char-table-p translation-table-for-input)
7734 (setq char (or (aref translation-table-for-input char) char)))
7735 (kill-region (point) (progn
7736 (search-forward (char-to-string char) nil nil arg)
7741 @node zap-to-char interactive, zap-to-char body, Complete zap-to-char, zap-to-char
7742 @comment node-name, next, previous, up
7743 @subsection The @code{interactive} Expression
7746 The interactive expression in the @code{zap-to-char} command looks like
7750 (interactive "p\ncZap to char: ")
7753 The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies
7754 two different things. First, and most simply, is the @samp{p}.
7755 This part is separated from the next part by a newline, @samp{\n}.
7756 The @samp{p} means that the first argument to the function will be
7757 passed the value of a `processed prefix'. The prefix argument is
7758 passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If
7759 the function is called interactively without a prefix, 1 is passed to
7762 The second part of @code{"p\ncZap to char:@: "} is
7763 @samp{cZap to char:@: }. In this part, the lower case @samp{c}
7764 indicates that @code{interactive} expects a prompt and that the
7765 argument will be a character. The prompt follows the @samp{c} and is
7766 the string @samp{Zap to char:@: } (with a space after the colon to
7769 What all this does is prepare the arguments to @code{zap-to-char} so they
7770 are of the right type, and give the user a prompt.
7772 In a read-only buffer, the @code{zap-to-char} function copies the text
7773 to the kill ring, but does not remove it. The echo area displays a
7774 message saying that the buffer is read-only. Also, the terminal may
7775 beep or blink at you.
7777 Let us continue with the interactive specification.
7779 @node zap-to-char body, search-forward, zap-to-char interactive, zap-to-char
7780 @comment node-name, next, previous, up
7781 @subsection The Body of @code{zap-to-char}
7783 The body of the @code{zap-to-char} function contains the code that
7784 kills (that is, removes) the text in the region from the current
7785 position of the cursor up to and including the specified character.
7787 The documentation is thorough. You do need to know the jargon meaning
7790 The first part of the code looks like this:
7793 (if (char-table-p translation-table-for-input)
7794 (setq char (or (aref translation-table-for-input char) char)))
7795 (kill-region (point) (progn
7796 (search-forward (char-to-string char) nil nil arg)
7801 @code{char-table-p} is an hitherto unseen function. It determines
7802 whether its argument is a character table. When it is, it sets the
7803 character passed to @code{zap-to-char} to one of them, if that
7804 character exists, or to the character itself. (This becomes important
7805 for certain characters in non-European languages. The @code{aref}
7806 function extracts an element from an array. It is an array-specific
7807 function that is not described in this document. @xref{Arrays, ,
7808 Arrays, elisp, The GNU Emacs Lisp Reference Manual}.)
7811 @code{(point)} is the current position of the cursor.
7813 The next part of the code is an expression using @code{progn}. The body
7814 of the @code{progn} consists of calls to @code{search-forward} and
7817 It is easier to understand how @code{progn} works after learning about
7818 @code{search-forward}, so we will look at @code{search-forward} and
7819 then at @code{progn}.
7821 @node search-forward, progn, zap-to-char body, zap-to-char
7822 @comment node-name, next, previous, up
7823 @subsection The @code{search-forward} Function
7824 @findex search-forward
7826 The @code{search-forward} function is used to locate the
7827 zapped-for-character in @code{zap-to-char}. If the search is
7828 successful, @code{search-forward} leaves point immediately after the
7829 last character in the target string. (In @code{zap-to-char}, the
7830 target string is just one character long. @code{zap-to-char} uses the
7831 function @code{char-to-string} to ensure that the computer treats that
7832 character as a string.) If the search is backwards,
7833 @code{search-forward} leaves point just before the first character in
7834 the target. Also, @code{search-forward} returns @code{t} for true.
7835 (Moving point is therefore a `side effect'.)
7838 In @code{zap-to-char}, the @code{search-forward} function looks like this:
7841 (search-forward (char-to-string char) nil nil arg)
7844 The @code{search-forward} function takes four arguments:
7848 The first argument is the target, what is searched for. This must be a
7849 string, such as @samp{"z"}.
7851 As it happens, the argument passed to @code{zap-to-char} is a single
7852 character. Because of the way computers are built, the Lisp
7853 interpreter may treat a single character as being different from a
7854 string of characters. Inside the computer, a single character has a
7855 different electronic format than a string of one character. (A single
7856 character can often be recorded in the computer using exactly one
7857 byte; but a string may be longer, and the computer needs to be ready
7858 for this.) Since the @code{search-forward} function searches for a
7859 string, the character that the @code{zap-to-char} function receives as
7860 its argument must be converted inside the computer from one format to
7861 the other; otherwise the @code{search-forward} function will fail.
7862 The @code{char-to-string} function is used to make this conversion.
7865 The second argument bounds the search; it is specified as a position in
7866 the buffer. In this case, the search can go to the end of the buffer,
7867 so no bound is set and the second argument is @code{nil}.
7870 The third argument tells the function what it should do if the search
7871 fails---it can signal an error (and print a message) or it can return
7872 @code{nil}. A @code{nil} as the third argument causes the function to
7873 signal an error when the search fails.
7876 The fourth argument to @code{search-forward} is the repeat count---how
7877 many occurrences of the string to look for. This argument is optional
7878 and if the function is called without a repeat count, this argument is
7879 passed the value 1. If this argument is negative, the search goes
7884 In template form, a @code{search-forward} expression looks like this:
7888 (search-forward "@var{target-string}"
7889 @var{limit-of-search}
7890 @var{what-to-do-if-search-fails}
7895 We will look at @code{progn} next.
7897 @node progn, Summing up zap-to-char, search-forward, zap-to-char
7898 @comment node-name, next, previous, up
7899 @subsection The @code{progn} Special Form
7902 @code{progn} is a special form that causes each of its arguments to be
7903 evaluated in sequence and then returns the value of the last one. The
7904 preceding expressions are evaluated only for the side effects they
7905 perform. The values produced by them are discarded.
7908 The template for a @code{progn} expression is very simple:
7917 In @code{zap-to-char}, the @code{progn} expression has to do two things:
7918 put point in exactly the right position; and return the location of
7919 point so that @code{kill-region} will know how far to kill to.
7921 The first argument to the @code{progn} is @code{search-forward}. When
7922 @code{search-forward} finds the string, the function leaves point
7923 immediately after the last character in the target string. (In this
7924 case the target string is just one character long.) If the search is
7925 backwards, @code{search-forward} leaves point just before the first
7926 character in the target. The movement of point is a side effect.
7928 The second and last argument to @code{progn} is the expression
7929 @code{(point)}. This expression returns the value of point, which in
7930 this case will be the location to which it has been moved by
7931 @code{search-forward}. (In the source, a line that tells the function
7932 to go to the previous character, if it is going forward, was commented
7933 out in 1999; I don't remember whether that feature or mis-feature was
7934 ever a part of the distributed source.) The value of @code{point} is
7935 returned by the @code{progn} expression and is passed to
7936 @code{kill-region} as @code{kill-region}'s second argument.
7938 @node Summing up zap-to-char, , progn, zap-to-char
7939 @comment node-name, next, previous, up
7940 @subsection Summing up @code{zap-to-char}
7942 Now that we have seen how @code{search-forward} and @code{progn} work,
7943 we can see how the @code{zap-to-char} function works as a whole.
7945 The first argument to @code{kill-region} is the position of the cursor
7946 when the @code{zap-to-char} command is given---the value of point at
7947 that time. Within the @code{progn}, the search function then moves
7948 point to just after the zapped-to-character and @code{point} returns the
7949 value of this location. The @code{kill-region} function puts together
7950 these two values of point, the first one as the beginning of the region
7951 and the second one as the end of the region, and removes the region.
7953 The @code{progn} special form is necessary because the
7954 @code{kill-region} command takes two arguments; and it would fail if
7955 @code{search-forward} and @code{point} expressions were written in
7956 sequence as two additional arguments. The @code{progn} expression is
7957 a single argument to @code{kill-region} and returns the one value that
7958 @code{kill-region} needs for its second argument.
7960 @node kill-region, copy-region-as-kill, zap-to-char, Cutting & Storing Text
7961 @comment node-name, next, previous, up
7962 @section @code{kill-region}
7965 The @code{zap-to-char} function uses the @code{kill-region} function.
7966 This function clips text from a region and copies that text to
7967 the kill ring, from which it may be retrieved.
7972 (defun kill-region (beg end &optional yank-handler)
7973 "Kill (\"cut\") text between point and mark.
7974 This deletes the text from the buffer and saves it in the kill ring.
7975 The command \\[yank] can retrieve it from there.
7976 \(If you want to kill and then yank immediately, use \\[kill-ring-save].)
7978 If you want to append the killed region to the last killed text,
7979 use \\[append-next-kill] before \\[kill-region].
7981 If the buffer is read-only, Emacs will beep and refrain from deleting
7982 the text, but put the text in the kill ring anyway. This means that
7983 you can use the killing commands to copy text from a read-only buffer.
7985 This is the primitive for programs to kill text (as opposed to deleting it).
7986 Supply two arguments, character positions indicating the stretch of text
7988 Any command that calls this function is a \"kill command\".
7989 If the previous command was also a kill command,
7990 the text killed this time appends to the text killed last time
7991 to make one entry in the kill ring.
7993 In Lisp code, optional third arg YANK-HANDLER, if non-nil,
7994 specifies the yank-handler text property to be set on the killed
7995 text. See `insert-for-yank'."
7996 ;; Pass point first, then mark, because the order matters
7997 ;; when calling kill-append.
7998 (interactive (list (point) (mark)))
7999 (unless (and beg end)
8000 (error "The mark is not set now, so there is no region"))
8002 (let ((string (filter-buffer-substring beg end t)))
8003 (when string ;STRING is nil if BEG = END
8004 ;; Add that string to the kill ring, one way or another.
8005 (if (eq last-command 'kill-region)
8006 (kill-append string (< end beg) yank-handler)
8007 (kill-new string nil yank-handler)))
8008 (when (or string (eq last-command 'kill-region))
8009 (setq this-command 'kill-region))
8011 ((buffer-read-only text-read-only)
8012 ;; The code above failed because the buffer, or some of the characters
8013 ;; in the region, are read-only.
8014 ;; We should beep, in case the user just isn't aware of this.
8015 ;; However, there's no harm in putting
8016 ;; the region's text in the kill ring, anyway.
8017 (copy-region-as-kill beg end)
8018 ;; Set this-command now, so it will be set even if we get an error.
8019 (setq this-command 'kill-region)
8020 ;; This should barf, if appropriate, and give us the correct error.
8021 (if kill-read-only-ok
8022 (progn (message "Read only text copied to kill ring") nil)
8023 ;; Signal an error if the buffer is read-only.
8024 (barf-if-buffer-read-only)
8025 ;; If the buffer isn't read-only, the text is.
8026 (signal 'text-read-only (list (current-buffer)))))))
8029 The Emacs 22 version of that function uses @code{condition-case} and
8030 @code{copy-region-as-kill}, both of which we will explain.
8031 @code{condition-case} is an important special form.
8033 In essence, the @code{kill-region} function calls
8034 @code{condition-case}, which takes three arguments. In this function,
8035 the first argument does nothing. The second argument contains the
8036 code that does the work when all goes well. The third argument
8037 contains the code that is called in the event of an error.
8040 * Complete kill-region::
8045 @node Complete kill-region, condition-case, kill-region, kill-region
8047 @unnumberedsubsec The Complete @code{kill-region} Definition
8051 We will go through the @code{condition-case} code in a moment. First,
8052 let us look at the definition of @code{kill-region}, with comments
8058 (defun kill-region (beg end)
8059 "Kill (\"cut\") text between point and mark.
8060 This deletes the text from the buffer and saves it in the kill ring.
8061 The command \\[yank] can retrieve it from there. @dots{} "
8065 ;; @bullet{} Since order matters, pass point first.
8066 (interactive (list (point) (mark)))
8067 ;; @bullet{} And tell us if we cannot cut the text.
8068 (unless (and beg end)
8069 (error "The mark is not set now, so there is no region"))
8073 ;; @bullet{} `condition-case' takes three arguments.
8074 ;; If the first argument is nil, as it is here,
8075 ;; information about the error signal is not
8076 ;; stored for use by another function.
8081 ;; @bullet{} The second argument to `condition-case' tells the
8082 ;; Lisp interpreter what to do when all goes well.
8086 ;; It starts with a `let' function that extracts the string
8087 ;; and tests whether it exists. If so (that is what the
8088 ;; `when' checks), it calls an `if' function that determines
8089 ;; whether the previous command was another call to
8090 ;; `kill-region'; if it was, then the new text is appended to
8091 ;; the previous text; if not, then a different function,
8092 ;; `kill-new', is called.
8096 ;; The `kill-append' function concatenates the new string and
8097 ;; the old. The `kill-new' function inserts text into a new
8098 ;; item in the kill ring.
8102 ;; `when' is an `if' without an else-part. The second `when'
8103 ;; again checks whether the current string exists; in
8104 ;; addition, it checks whether the previous command was
8105 ;; another call to `kill-region'. If one or the other
8106 ;; condition is true, then it sets the current command to
8107 ;; be `kill-region'.
8110 (let ((string (filter-buffer-substring beg end t)))
8111 (when string ;STRING is nil if BEG = END
8112 ;; Add that string to the kill ring, one way or another.
8113 (if (eq last-command 'kill-region)
8116 ;; @minus{} `yank-handler' is an optional argument to
8117 ;; `kill-region' that tells the `kill-append' and
8118 ;; `kill-new' functions how deal with properties
8119 ;; added to the text, such as `bold' or `italics'.
8120 (kill-append string (< end beg) yank-handler)
8121 (kill-new string nil yank-handler)))
8122 (when (or string (eq last-command 'kill-region))
8123 (setq this-command 'kill-region))
8128 ;; @bullet{} The third argument to `condition-case' tells the interpreter
8129 ;; what to do with an error.
8132 ;; The third argument has a conditions part and a body part.
8133 ;; If the conditions are met (in this case,
8134 ;; if text or buffer are read-only)
8135 ;; then the body is executed.
8138 ;; The first part of the third argument is the following:
8139 ((buffer-read-only text-read-only) ;; the if-part
8140 ;; @dots{} the then-part
8141 (copy-region-as-kill beg end)
8144 ;; Next, also as part of the then-part, set this-command, so
8145 ;; it will be set in an error
8146 (setq this-command 'kill-region)
8147 ;; Finally, in the then-part, send a message if you may copy
8148 ;; the text to the kill ring without signally an error, but
8149 ;; don't if you may not.
8152 (if kill-read-only-ok
8153 (progn (message "Read only text copied to kill ring") nil)
8154 (barf-if-buffer-read-only)
8155 ;; If the buffer isn't read-only, the text is.
8156 (signal 'text-read-only (list (current-buffer)))))
8164 (defun kill-region (beg end)
8165 "Kill between point and mark.
8166 The text is deleted but saved in the kill ring."
8171 ;; 1. `condition-case' takes three arguments.
8172 ;; If the first argument is nil, as it is here,
8173 ;; information about the error signal is not
8174 ;; stored for use by another function.
8179 ;; 2. The second argument to `condition-case'
8180 ;; tells the Lisp interpreter what to do when all goes well.
8184 ;; The `delete-and-extract-region' function usually does the
8185 ;; work. If the beginning and ending of the region are both
8186 ;; the same, then the variable `string' will be empty, or nil
8187 (let ((string (delete-and-extract-region beg end)))
8191 ;; `when' is an `if' clause that cannot take an `else-part'.
8192 ;; Emacs normally sets the value of `last-command' to the
8193 ;; previous command.
8196 ;; `kill-append' concatenates the new string and the old.
8197 ;; `kill-new' inserts text into a new item in the kill ring.
8199 (if (eq last-command 'kill-region)
8200 ;; if true, prepend string
8201 (kill-append string (< end beg))
8203 (setq this-command 'kill-region))
8207 ;; 3. The third argument to `condition-case' tells the interpreter
8208 ;; what to do with an error.
8211 ;; The third argument has a conditions part and a body part.
8212 ;; If the conditions are met (in this case,
8213 ;; if text or buffer are read-only)
8214 ;; then the body is executed.
8217 ((buffer-read-only text-read-only) ;; this is the if-part
8219 (copy-region-as-kill beg end)
8222 (if kill-read-only-ok ;; usually this variable is nil
8223 (message "Read only text copied to kill ring")
8224 ;; or else, signal an error if the buffer is read-only;
8225 (barf-if-buffer-read-only)
8226 ;; and, in any case, signal that the text is read-only.
8227 (signal 'text-read-only (list (current-buffer)))))))
8232 @node condition-case, Lisp macro, Complete kill-region, kill-region
8233 @comment node-name, next, previous, up
8234 @subsection @code{condition-case}
8235 @findex condition-case
8237 As we have seen earlier (@pxref{Making Errors, , Generate an Error
8238 Message}), when the Emacs Lisp interpreter has trouble evaluating an
8239 expression, it provides you with help; in the jargon, this is called
8240 ``signaling an error''. Usually, the computer stops the program and
8241 shows you a message.
8243 However, some programs undertake complicated actions. They should not
8244 simply stop on an error. In the @code{kill-region} function, the most
8245 likely error is that you will try to kill text that is read-only and
8246 cannot be removed. So the @code{kill-region} function contains code
8247 to handle this circumstance. This code, which makes up the body of
8248 the @code{kill-region} function, is inside of a @code{condition-case}
8252 The template for @code{condition-case} looks like this:
8259 @var{error-handler}@dots{})
8263 The second argument, @var{bodyform}, is straightforward. The
8264 @code{condition-case} special form causes the Lisp interpreter to
8265 evaluate the code in @var{bodyform}. If no error occurs, the special
8266 form returns the code's value and produces the side-effects, if any.
8268 In short, the @var{bodyform} part of a @code{condition-case}
8269 expression determines what should happen when everything works
8272 However, if an error occurs, among its other actions, the function
8273 generating the error signal will define one or more error condition
8276 An error handler is the third argument to @code{condition case}.
8277 An error handler has two parts, a @var{condition-name} and a
8278 @var{body}. If the @var{condition-name} part of an error handler
8279 matches a condition name generated by an error, then the @var{body}
8280 part of the error handler is run.
8282 As you will expect, the @var{condition-name} part of an error handler
8283 may be either a single condition name or a list of condition names.
8285 Also, a complete @code{condition-case} expression may contain more
8286 than one error handler. When an error occurs, the first applicable
8289 Lastly, the first argument to the @code{condition-case} expression,
8290 the @var{var} argument, is sometimes bound to a variable that
8291 contains information about the error. However, if that argument is
8292 nil, as is the case in @code{kill-region}, that information is
8296 In brief, in the @code{kill-region} function, the code
8297 @code{condition-case} works like this:
8301 @var{If no errors}, @var{run only this code}
8302 @var{but}, @var{if errors}, @var{run this other code}.
8309 copy-region-as-kill is short, 12 lines, and uses
8310 filter-buffer-substring, which is longer, 39 lines
8311 and has delete-and-extract-region in it.
8312 delete-and-extract-region is written in C.
8314 see Initializing a Variable with @code{defvar}
8316 Initializing a Variable with @code{defvar} includes line 8350
8319 @node Lisp macro, , condition-case, kill-region
8320 @comment node-name, next, previous, up
8321 @subsection Lisp macro
8325 The part of the @code{condition-case} expression that is evaluated in
8326 the expectation that all goes well has a @code{when}. The code uses
8327 @code{when} to determine whether the @code{string} variable points to
8330 A @code{when} expression is simply a programmers' convenience. It is
8331 an @code{if} without the possibility of an else clause. In your mind,
8332 you can replace @code{when} with @code{if} and understand what goes
8333 on. That is what the Lisp interpreter does.
8335 Technically speaking, @code{when} is a Lisp macro. A Lisp @dfn{macro}
8336 enables you to define new control constructs and other language
8337 features. It tells the interpreter how to compute another Lisp
8338 expression which will in turn compute the value. In this case, the
8339 `other expression' is an @code{if} expression. For more about Lisp
8340 macros, see @ref{Macros, , Macros, elisp, The GNU Emacs Lisp Reference
8341 Manual}. The C programming language also provides macros. These are
8342 different, but also useful.
8345 We will briefly look at C macros in
8346 @ref{Digression into C}.
8350 If the string has content, then another conditional expression is
8351 executed. This is an @code{if} with both a then-part and an else-part.
8355 (if (eq last-command 'kill-region)
8356 (kill-append string (< end beg) yank-handler)
8357 (kill-new string nil yank-handler))
8361 The then-part is evaluated if the previous command was another call to
8362 @code{kill-region}; if not, the else-part is evaluated.
8364 @code{yank-handler} is an optional argument to @code{kill-region} that
8365 tells the @code{kill-append} and @code{kill-new} functions how deal
8366 with properties added to the text, such as `bold' or `italics'.
8368 @code{last-command} is a variable that comes with Emacs that we have
8369 not seen before. Normally, whenever a function is executed, Emacs
8370 sets the value of @code{last-command} to the previous command.
8373 In this segment of the definition, the @code{if} expression checks
8374 whether the previous command was @code{kill-region}. If it was,
8377 (kill-append string (< end beg) yank-handler)
8381 concatenates a copy of the newly clipped text to the just previously
8382 clipped text in the kill ring.
8384 @node copy-region-as-kill, Digression into C, kill-region, Cutting & Storing Text
8385 @comment node-name, next, previous, up
8386 @section @code{copy-region-as-kill}
8387 @findex copy-region-as-kill
8390 The @code{copy-region-as-kill} function copies a region of text from a
8391 buffer and (via either @code{kill-append} or @code{kill-new}) saves it
8392 in the @code{kill-ring}.
8394 If you call @code{copy-region-as-kill} immediately after a
8395 @code{kill-region} command, Emacs appends the newly copied text to the
8396 previously copied text. This means that if you yank back the text, you
8397 get it all, from both this and the previous operation. On the other
8398 hand, if some other command precedes the @code{copy-region-as-kill},
8399 the function copies the text into a separate entry in the kill ring.
8402 * Complete copy-region-as-kill::
8403 * copy-region-as-kill body::
8406 @node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
8408 @unnumberedsubsec The complete @code{copy-region-as-kill} function definition
8412 Here is the complete text of the version 22 @code{copy-region-as-kill}
8417 (defun copy-region-as-kill (beg end)
8418 "Save the region as if killed, but don't kill it.
8419 In Transient Mark mode, deactivate the mark.
8420 If `interprogram-cut-function' is non-nil, also save the text for a window
8421 system cut and paste."
8425 (if (eq last-command 'kill-region)
8426 (kill-append (filter-buffer-substring beg end) (< end beg))
8427 (kill-new (filter-buffer-substring beg end)))
8430 (if transient-mark-mode
8431 (setq deactivate-mark t))
8437 As usual, this function can be divided into its component parts:
8441 (defun copy-region-as-kill (@var{argument-list})
8442 "@var{documentation}@dots{}"
8448 The arguments are @code{beg} and @code{end} and the function is
8449 interactive with @code{"r"}, so the two arguments must refer to the
8450 beginning and end of the region. If you have been reading though this
8451 document from the beginning, understanding these parts of a function is
8452 almost becoming routine.
8454 The documentation is somewhat confusing unless you remember that the
8455 word `kill' has a meaning different from usual. The `Transient Mark'
8456 and @code{interprogram-cut-function} comments explain certain
8459 After you once set a mark, a buffer always contains a region. If you
8460 wish, you can use Transient Mark mode to highlight the region
8461 temporarily. (No one wants to highlight the region all the time, so
8462 Transient Mark mode highlights it only at appropriate times. Many
8463 people turn off Transient Mark mode, so the region is never
8466 Also, a windowing system allows you to copy, cut, and paste among
8467 different programs. In the X windowing system, for example, the
8468 @code{interprogram-cut-function} function is @code{x-select-text},
8469 which works with the windowing system's equivalent of the Emacs kill
8472 The body of the @code{copy-region-as-kill} function starts with an
8473 @code{if} clause. What this clause does is distinguish between two
8474 different situations: whether or not this command is executed
8475 immediately after a previous @code{kill-region} command. In the first
8476 case, the new region is appended to the previously copied text.
8477 Otherwise, it is inserted into the beginning of the kill ring as a
8478 separate piece of text from the previous piece.
8480 The last two lines of the function prevent the region from lighting up
8481 if Transient Mark mode is turned on.
8483 The body of @code{copy-region-as-kill} merits discussion in detail.
8485 @node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill
8486 @comment node-name, next, previous, up
8487 @subsection The Body of @code{copy-region-as-kill}
8489 The @code{copy-region-as-kill} function works in much the same way as
8490 the @code{kill-region} function. Both are written so that two or more
8491 kills in a row combine their text into a single entry. If you yank
8492 back the text from the kill ring, you get it all in one piece.
8493 Moreover, kills that kill forward from the current position of the
8494 cursor are added to the end of the previously copied text and commands
8495 that copy text backwards add it to the beginning of the previously
8496 copied text. This way, the words in the text stay in the proper
8499 Like @code{kill-region}, the @code{copy-region-as-kill} function makes
8500 use of the @code{last-command} variable that keeps track of the
8501 previous Emacs command.
8504 * last-command & this-command::
8505 * kill-append function::
8506 * kill-new function::
8509 @node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body
8511 @unnumberedsubsubsec @code{last-command} and @code{this-command}
8514 Normally, whenever a function is executed, Emacs sets the value of
8515 @code{this-command} to the function being executed (which in this case
8516 would be @code{copy-region-as-kill}). At the same time, Emacs sets
8517 the value of @code{last-command} to the previous value of
8518 @code{this-command}.
8520 In the first part of the body of the @code{copy-region-as-kill}
8521 function, an @code{if} expression determines whether the value of
8522 @code{last-command} is @code{kill-region}. If so, the then-part of
8523 the @code{if} expression is evaluated; it uses the @code{kill-append}
8524 function to concatenate the text copied at this call to the function
8525 with the text already in the first element (the @sc{car}) of the kill
8526 ring. On the other hand, if the value of @code{last-command} is not
8527 @code{kill-region}, then the @code{copy-region-as-kill} function
8528 attaches a new element to the kill ring using the @code{kill-new}
8532 The @code{if} expression reads as follows; it uses @code{eq}, which is
8533 a function we have not yet seen:
8537 (if (eq last-command 'kill-region)
8539 (kill-append (filter-buffer-substring beg end) (< end beg))
8541 (kill-new (filter-buffer-substring beg end)))
8545 @findex filter-buffer-substring
8546 (The @code{filter-buffer-substring} function returns a filtered
8547 substring of the buffer, if any. Optionally---the arguments are not
8548 here, so neither is done---the function may delete the initial text or
8549 return the text without its properties; this function is a replacement
8550 for the older @code{buffer-substring} function, which came before text
8551 properties were implemented.)
8553 @findex eq @r{(example of use)}
8555 The @code{eq} function tests whether its first argument is the same Lisp
8556 object as its second argument. The @code{eq} function is similar to the
8557 @code{equal} function in that it is used to test for equality, but
8558 differs in that it determines whether two representations are actually
8559 the same object inside the computer, but with different names.
8560 @code{equal} determines whether the structure and contents of two
8561 expressions are the same.
8563 If the previous command was @code{kill-region}, then the Emacs Lisp
8564 interpreter calls the @code{kill-append} function
8566 @node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body
8567 @unnumberedsubsubsec The @code{kill-append} function
8571 The @code{kill-append} function looks like this:
8576 (defun kill-append (string before-p &optional yank-handler)
8577 "Append STRING to the end of the latest kill in the kill ring.
8578 If BEFORE-P is non-nil, prepend STRING to the kill.
8580 (let* ((cur (car kill-ring)))
8581 (kill-new (if before-p (concat string cur) (concat cur string))
8582 (or (= (length cur) 0)
8583 (equal yank-handler (get-text-property 0 'yank-handler cur)))
8590 (defun kill-append (string before-p)
8591 "Append STRING to the end of the latest kill in the kill ring.
8592 If BEFORE-P is non-nil, prepend STRING to the kill.
8593 If `interprogram-cut-function' is set, pass the resulting kill to
8595 (kill-new (if before-p
8596 (concat string (car kill-ring))
8597 (concat (car kill-ring) string))
8602 The @code{kill-append} function is fairly straightforward. It uses
8603 the @code{kill-new} function, which we will discuss in more detail in
8606 (Also, the function provides an optional argument called
8607 @code{yank-handler}; when invoked, this argument tells the function
8608 how to deal with properties added to the text, such as `bold' or
8611 @c !!! bug in GNU Emacs 22 version of kill-append ?
8612 It has a @code{let*} function to set the value of the first element of
8613 the kill ring to @code{cur}. (I do not know why the function does not
8614 use @code{let} instead; only one value is set in the expression.
8615 Perhaps this is a bug that produces no problems?)
8617 Consider the conditional that is one of the two arguments to
8618 @code{kill-new}. It uses @code{concat} to concatenate the new text to
8619 the @sc{car} of the kill ring. Whether it prepends or appends the
8620 text depends on the results of an @code{if} expression:
8624 (if before-p ; @r{if-part}
8625 (concat string cur) ; @r{then-part}
8626 (concat cur string)) ; @r{else-part}
8631 If the region being killed is before the region that was killed in the
8632 last command, then it should be prepended before the material that was
8633 saved in the previous kill; and conversely, if the killed text follows
8634 what was just killed, it should be appended after the previous text.
8635 The @code{if} expression depends on the predicate @code{before-p} to
8636 decide whether the newly saved text should be put before or after the
8637 previously saved text.
8639 The symbol @code{before-p} is the name of one of the arguments to
8640 @code{kill-append}. When the @code{kill-append} function is
8641 evaluated, it is bound to the value returned by evaluating the actual
8642 argument. In this case, this is the expression @code{(< end beg)}.
8643 This expression does not directly determine whether the killed text in
8644 this command is located before or after the kill text of the last
8645 command; what it does is determine whether the value of the variable
8646 @code{end} is less than the value of the variable @code{beg}. If it
8647 is, it means that the user is most likely heading towards the
8648 beginning of the buffer. Also, the result of evaluating the predicate
8649 expression, @code{(< end beg)}, will be true and the text will be
8650 prepended before the previous text. On the other hand, if the value of
8651 the variable @code{end} is greater than the value of the variable
8652 @code{beg}, the text will be appended after the previous text.
8655 When the newly saved text will be prepended, then the string with the new
8656 text will be concatenated before the old text:
8664 But if the text will be appended, it will be concatenated
8668 (concat cur string))
8671 To understand how this works, we first need to review the
8672 @code{concat} function. The @code{concat} function links together or
8673 unites two strings of text. The result is a string. For example:
8677 (concat "abc" "def")
8683 (car '("first element" "second element")))
8684 @result{} "new first element"
8687 '("first element" "second element")) " modified")
8688 @result{} "first element modified"
8692 We can now make sense of @code{kill-append}: it modifies the contents
8693 of the kill ring. The kill ring is a list, each element of which is
8694 saved text. The @code{kill-append} function uses the @code{kill-new}
8695 function which in turn uses the @code{setcar} function.
8697 @node kill-new function, , kill-append function, copy-region-as-kill body
8698 @unnumberedsubsubsec The @code{kill-new} function
8701 @c in GNU Emacs 22, additional documentation to kill-new:
8703 Optional third arguments YANK-HANDLER controls how the STRING is later
8704 inserted into a buffer; see `insert-for-yank' for details.
8705 When a yank handler is specified, STRING must be non-empty (the yank
8706 handler, if non-nil, is stored as a `yank-handler' text property on STRING).
8708 When the yank handler has a non-nil PARAM element, the original STRING
8709 argument is not used by `insert-for-yank'. However, since Lisp code
8710 may access and use elements from the kill ring directly, the STRING
8711 argument should still be a \"useful\" string for such uses."
8714 The @code{kill-new} function looks like this:
8718 (defun kill-new (string &optional replace yank-handler)
8719 "Make STRING the latest kill in the kill ring.
8720 Set `kill-ring-yank-pointer' to point to it.
8722 If `interprogram-cut-function' is non-nil, apply it to STRING.
8723 Optional second argument REPLACE non-nil means that STRING will replace
8724 the front of the kill ring, rather than being added to the list.
8728 (if (> (length string) 0)
8730 (put-text-property 0 (length string)
8731 'yank-handler yank-handler string))
8733 (signal 'args-out-of-range
8734 (list string "yank-handler specified for empty string"))))
8737 (if (fboundp 'menu-bar-update-yank-menu)
8738 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8741 (if (and replace kill-ring)
8742 (setcar kill-ring string)
8743 (push string kill-ring)
8744 (if (> (length kill-ring) kill-ring-max)
8745 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8748 (setq kill-ring-yank-pointer kill-ring)
8749 (if interprogram-cut-function
8750 (funcall interprogram-cut-function string (not replace))))
8755 (defun kill-new (string &optional replace)
8756 "Make STRING the latest kill in the kill ring.
8757 Set the kill-ring-yank pointer to point to it.
8758 If `interprogram-cut-function' is non-nil, apply it to STRING.
8759 Optional second argument REPLACE non-nil means that STRING will replace
8760 the front of the kill ring, rather than being added to the list."
8761 (and (fboundp 'menu-bar-update-yank-menu)
8762 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8763 (if (and replace kill-ring)
8764 (setcar kill-ring string)
8765 (setq kill-ring (cons string kill-ring))
8766 (if (> (length kill-ring) kill-ring-max)
8767 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8768 (setq kill-ring-yank-pointer kill-ring)
8769 (if interprogram-cut-function
8770 (funcall interprogram-cut-function string (not replace))))
8774 (Notice that the function is not interactive.)
8776 As usual, we can look at this function in parts.
8778 The function definition has an optional @code{yank-handler} argument,
8779 which when invoked tells the function how to deal with properties
8780 added to the text, such as `bold' or `italics'. We will skip that.
8783 The first line of the documentation makes sense:
8786 Make STRING the latest kill in the kill ring.
8790 Let's skip over the rest of the documentation for the moment.
8792 Also, let's skip over the initial @code{if} expression and those lines
8793 of code involving @code{menu-bar-update-yank-menu}. We will explain
8797 The critical lines are these:
8801 (if (and replace kill-ring)
8803 (setcar kill-ring string)
8807 (push string kill-ring)
8810 (setq kill-ring (cons string kill-ring))
8811 (if (> (length kill-ring) kill-ring-max)
8812 ;; @r{avoid overly long kill ring}
8813 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8816 (setq kill-ring-yank-pointer kill-ring)
8817 (if interprogram-cut-function
8818 (funcall interprogram-cut-function string (not replace))))
8822 The conditional test is @w{@code{(and replace kill-ring)}}.
8823 This will be true when two conditions are met: the kill ring has
8824 something in it, and the @code{replace} variable is true.
8827 When the @code{kill-append} function sets @code{replace} to be true
8828 and when the kill ring has at least one item in it, the @code{setcar}
8829 expression is executed:
8832 (setcar kill-ring string)
8835 The @code{setcar} function actually changes the first element of the
8836 @code{kill-ring} list to the value of @code{string}. It replaces the
8840 On the other hand, if the kill ring is empty, or replace is false, the
8841 else-part of the condition is executed:
8844 (push string kill-ring)
8849 @code{push} puts its first argument onto the second. It is the same
8853 (setq kill-ring (cons string kill-ring))
8861 (add-to-list kill-ring string)
8865 When it is false, the expression first constructs a new version of the
8866 kill ring by prepending @code{string} to the existing kill ring as a
8867 new element (that is what the @code{push} does). Then it executes a
8868 second @code{if} clause. This second @code{if} clause keeps the kill
8869 ring from growing too long.
8871 Let's look at these two expressions in order.
8873 The @code{push} line of the else-part sets the new value of the kill
8874 ring to what results from adding the string being killed to the old
8877 We can see how this works with an example.
8883 (setq example-list '("here is a clause" "another clause"))
8888 After evaluating this expression with @kbd{C-x C-e}, you can evaluate
8889 @code{example-list} and see what it returns:
8894 @result{} ("here is a clause" "another clause")
8900 Now, we can add a new element on to this list by evaluating the
8901 following expression:
8902 @findex push, @r{example}
8905 (push "a third clause" example-list)
8910 When we evaluate @code{example-list}, we find its value is:
8915 @result{} ("a third clause" "here is a clause" "another clause")
8920 Thus, the third clause is added to the list by @code{push}.
8923 Now for the second part of the @code{if} clause. This expression
8924 keeps the kill ring from growing too long. It looks like this:
8928 (if (> (length kill-ring) kill-ring-max)
8929 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
8933 The code checks whether the length of the kill ring is greater than
8934 the maximum permitted length. This is the value of
8935 @code{kill-ring-max} (which is 60, by default). If the length of the
8936 kill ring is too long, then this code sets the last element of the
8937 kill ring to @code{nil}. It does this by using two functions,
8938 @code{nthcdr} and @code{setcdr}.
8940 We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
8941 It sets the @sc{cdr} of a list, just as @code{setcar} sets the
8942 @sc{car} of a list. In this case, however, @code{setcdr} will not be
8943 setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
8944 function is used to cause it to set the @sc{cdr} of the next to last
8945 element of the kill ring---this means that since the @sc{cdr} of the
8946 next to last element is the last element of the kill ring, it will set
8947 the last element of the kill ring.
8949 @findex nthcdr, @r{example}
8950 The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
8951 list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
8952 @dots{} It does this @var{N} times and returns the results.
8953 (@xref{nthcdr, , @code{nthcdr}}.)
8955 @findex setcdr, @r{example}
8956 Thus, if we had a four element list that was supposed to be three
8957 elements long, we could set the @sc{cdr} of the next to last element
8958 to @code{nil}, and thereby shorten the list. (If you sent the last
8959 element to some other value than @code{nil}, which you could do, then
8960 you would not have shortened the list. @xref{setcdr, ,
8963 You can see shortening by evaluating the following three expressions
8964 in turn. First set the value of @code{trees} to @code{(maple oak pine
8965 birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
8966 and then find the value of @code{trees}:
8970 (setq trees '(maple oak pine birch))
8971 @result{} (maple oak pine birch)
8975 (setcdr (nthcdr 2 trees) nil)
8979 @result{} (maple oak pine)
8984 (The value returned by the @code{setcdr} expression is @code{nil} since
8985 that is what the @sc{cdr} is set to.)
8987 To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
8988 @sc{cdr} a number of times that is one less than the maximum permitted
8989 size of the kill ring and @code{setcdr} sets the @sc{cdr} of that
8990 element (which will be the rest of the elements in the kill ring) to
8991 @code{nil}. This prevents the kill ring from growing too long.
8994 The next to last expression in the @code{kill-new} function is
8997 (setq kill-ring-yank-pointer kill-ring)
9000 The @code{kill-ring-yank-pointer} is a global variable that is set to be
9001 the @code{kill-ring}.
9003 Even though the @code{kill-ring-yank-pointer} is called a
9004 @samp{pointer}, it is a variable just like the kill ring. However, the
9005 name has been chosen to help humans understand how the variable is used.
9006 The variable is used in functions such as @code{yank} and
9007 @code{yank-pop} (@pxref{Yanking, , Yanking Text Back}).
9010 Now, to return to an early expression in the body of the function:
9014 (if (fboundp 'menu-bar-update-yank-menu)
9015 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
9020 It starts with an @code{if} expression
9022 In this case, the expression tests first to see whether
9023 @code{menu-bar-update-yank-menu} exists as a function, and if so,
9024 calls it. The @code{fboundp} function returns true if the symbol it
9025 is testing has a function definition that `is not void'. If the
9026 symbol's function definition were void, we would receive an error
9027 message, as we did when we created errors intentionally (@pxref{Making
9028 Errors, , Generate an Error Message}).
9031 The then-part contains an expression whose first element is the
9032 function @code{and}.
9035 The @code{and} special form evaluates each of its arguments until one
9036 of the arguments returns a value of @code{nil}, in which case the
9037 @code{and} expression returns @code{nil}; however, if none of the
9038 arguments returns a value of @code{nil}, the value resulting from
9039 evaluating the last argument is returned. (Since such a value is not
9040 @code{nil}, it is considered true in Emacs Lisp.) In other words, an
9041 @code{and} expression returns a true value only if all its arguments
9042 are true. (@xref{Second Buffer Related Review}.)
9044 The expression determines whether the second argument to
9045 @code{menu-bar-update-yank-menu} is true or not.
9047 ;; If we're supposed to be extending an existing string, and that
9048 ;; string really is at the front of the menu, then update it in place.
9051 @code{menu-bar-update-yank-menu} is one of the functions that make it
9052 possible to use the `Select and Paste' menu in the Edit item of a menu
9053 bar; using a mouse, you can look at the various pieces of text you
9054 have saved and select one piece to paste.
9056 The last expression in the @code{kill-new} function adds the newly
9057 copied string to whatever facility exists for copying and pasting
9058 among different programs running in a windowing system. In the X
9059 Windowing system, for example, the @code{x-select-text} function takes
9060 the string and stores it in memory operated by X. You can paste the
9061 string in another program, such as an Xterm.
9064 The expression looks like this:
9068 (if interprogram-cut-function
9069 (funcall interprogram-cut-function string (not replace))))
9073 If an @code{interprogram-cut-function} exists, then Emacs executes
9074 @code{funcall}, which in turn calls its first argument as a function
9075 and passes the remaining arguments to it. (Incidentally, as far as I
9076 can see, this @code{if} expression could be replaced by an @code{and}
9077 expression similar to the one in the first part of the function.)
9079 We are not going to discuss windowing systems and other programs
9080 further, but merely note that this is a mechanism that enables GNU
9081 Emacs to work easily and well with other programs.
9083 This code for placing text in the kill ring, either concatenated with
9084 an existing element or as a new element, leads us to the code for
9085 bringing back text that has been cut out of the buffer---the yank
9086 commands. However, before discussing the yank commands, it is better
9087 to learn how lists are implemented in a computer. This will make
9088 clear such mysteries as the use of the term `pointer'.
9091 @c is this true in Emacs 22? Does not seems to be
9093 (If the @w{@code{(< end beg))}}
9094 expression is true, @code{kill-append} prepends the string to the just
9095 previously clipped text. For a detailed discussion, see
9096 @ref{kill-append function, , The @code{kill-append} function}.)
9098 If you then yank back the text, i.e., `paste' it, you get both
9099 pieces of text at once. That way, if you delete two words in a row,
9100 and then yank them back, you get both words, in their proper order,
9101 with one yank. (The @w{@code{(< end beg))}} expression makes sure the
9104 On the other hand, if the previous command is not @code{kill-region},
9105 then the @code{kill-new} function is called, which adds the text to
9106 the kill ring as the latest item, and sets the
9107 @code{kill-ring-yank-pointer} variable to point to it.
9111 @c Evidently, changed for Emacs 22. The zap-to-char command does not
9112 @c use the delete-and-extract-region function
9114 2006 Oct 26, the Digression into C is now OK but should come after
9115 copy-region-as-kill and filter-buffer-substring
9119 copy-region-as-kill is short, 12 lines, and uses
9120 filter-buffer-substring, which is longer, 39 lines
9121 and has delete-and-extract-region in it.
9122 delete-and-extract-region is written in C.
9124 see Initializing a Variable with @code{defvar}
9127 @node Digression into C, defvar, copy-region-as-kill, Cutting & Storing Text
9128 @comment node-name, next, previous, up
9129 @section Digression into C
9130 @findex delete-and-extract-region
9131 @cindex C, a digression into
9132 @cindex Digression into C
9134 The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, ,
9135 @code{copy-region-as-kill}}) uses the @code{filter-buffer-substring}
9136 function, which in turn uses the @code{delete-and-extract-region}
9137 function. It removes the contents of a region and you cannot get them
9140 Unlike the other code discussed here, the
9141 @code{delete-and-extract-region} function is not written in Emacs
9142 Lisp; it is written in C and is one of the primitives of the GNU Emacs
9143 system. Since it is very simple, I will digress briefly from Lisp and
9146 @c GNU Emacs 22 in /usr/local/src/emacs/src/editfns.c
9147 @c the DEFUN for buffer-substring-no-properties
9150 Like many of the other Emacs primitives,
9151 @code{delete-and-extract-region} is written as an instance of a C
9152 macro, a macro being a template for code. The complete macro looks
9157 DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties,
9158 Sbuffer_substring_no_properties, 2, 2, 0,
9159 doc: /* Return the characters of part of the buffer,
9160 without the text properties.
9161 The two arguments START and END are character positions;
9162 they can be in either order. */)
9164 Lisp_Object start, end;
9168 validate_region (&start, &end);
9172 return make_buffer_string (b, e, 0);
9177 Without going into the details of the macro writing process, let me
9178 point out that this macro starts with the word @code{DEFUN}. The word
9179 @code{DEFUN} was chosen since the code serves the same purpose as
9180 @code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in
9181 @file{emacs/src/lisp.h}.)
9183 The word @code{DEFUN} is followed by seven parts inside of
9188 The first part is the name given to the function in Lisp,
9189 @code{delete-and-extract-region}.
9192 The second part is the name of the function in C,
9193 @code{Fdelete_and_extract_region}. By convention, it starts with
9194 @samp{F}. Since C does not use hyphens in names, underscores are used
9198 The third part is the name for the C constant structure that records
9199 information on this function for internal use. It is the name of the
9200 function in C but begins with an @samp{S} instead of an @samp{F}.
9203 The fourth and fifth parts specify the minimum and maximum number of
9204 arguments the function can have. This function demands exactly 2
9208 The sixth part is nearly like the argument that follows the
9209 @code{interactive} declaration in a function written in Lisp: a letter
9210 followed, perhaps, by a prompt. The only difference from the Lisp is
9211 when the macro is called with no arguments. Then you write a @code{0}
9212 (which is a `null string'), as in this macro.
9214 If you were to specify arguments, you would place them between
9215 quotation marks. The C macro for @code{goto-char} includes
9216 @code{"NGoto char: "} in this position to indicate that the function
9217 expects a raw prefix, in this case, a numerical location in a buffer,
9218 and provides a prompt.
9221 The seventh part is a documentation string, just like the one for a
9222 function written in Emacs Lisp, except that every newline must be
9223 written explicitly as @samp{\n} followed by a backslash and carriage
9227 Thus, the first two lines of documentation for @code{goto-char} are
9232 "Set point to POSITION, a number or marker.\n\
9233 Beginning of buffer is position (point-min), end is (point-max).
9239 In a C macro, the formal parameters come next, with a statement of
9240 what kind of object they are, followed by what might be called the `body'
9241 of the macro. For @code{delete-and-extract-region} the `body'
9242 consists of the following four lines:
9246 validate_region (&start, &end);
9247 if (XINT (start) == XINT (end))
9248 return build_string ("");
9249 return del_range_1 (XINT (start), XINT (end), 1, 1);
9253 The @code{validate_region} function checks whether the values
9254 passed as the beginning and end of the region are the proper type and
9255 are within range. If the beginning and end positions are the same,
9256 then return and empty string.
9258 The @code{del_range_1} function actually deletes the text. It is a
9259 complex function we will not look into. It updates the buffer and
9260 does other things. However, it is worth looking at the two arguments
9261 passed to @code{del_range}. These are @w{@code{XINT (start)}} and
9262 @w{@code{XINT (end)}}.
9264 As far as the C language is concerned, @code{start} and @code{end} are
9265 two integers that mark the beginning and end of the region to be
9266 deleted@footnote{More precisely, and requiring more expert knowledge
9267 to understand, the two integers are of type `Lisp_Object', which can
9268 also be a C union instead of an integer type.}.
9270 In early versions of Emacs, these two numbers were thirty-two bits
9271 long, but the code is slowly being generalized to handle other
9272 lengths. Three of the available bits are used to specify the type of
9273 information; the remaining bits are used as `content'.
9275 @samp{XINT} is a C macro that extracts the relevant number from the
9276 longer collection of bits; the three other bits are discarded.
9279 The command in @code{delete-and-extract-region} looks like this:
9282 del_range_1 (XINT (start), XINT (end), 1, 1);
9286 It deletes the region between the beginning position, @code{start},
9287 and the ending position, @code{end}.
9289 From the point of view of the person writing Lisp, Emacs is all very
9290 simple; but hidden underneath is a great deal of complexity to make it
9293 @node defvar, cons & search-fwd Review, Digression into C, Cutting & Storing Text
9294 @comment node-name, next, previous, up
9295 @section Initializing a Variable with @code{defvar}
9297 @cindex Initializing a variable
9298 @cindex Variable initialization
9303 copy-region-as-kill is short, 12 lines, and uses
9304 filter-buffer-substring, which is longer, 39 lines
9305 and has delete-and-extract-region in it.
9306 delete-and-extract-region is written in C.
9308 see Initializing a Variable with @code{defvar}
9312 The @code{copy-region-as-kill} function is written in Emacs Lisp. Two
9313 functions within it, @code{kill-append} and @code{kill-new}, copy a
9314 region in a buffer and save it in a variable called the
9315 @code{kill-ring}. This section describes how the @code{kill-ring}
9316 variable is created and initialized using the @code{defvar} special
9319 (Again we note that the term @code{kill-ring} is a misnomer. The text
9320 that is clipped out of the buffer can be brought back; it is not a ring
9321 of corpses, but a ring of resurrectable text.)
9323 In Emacs Lisp, a variable such as the @code{kill-ring} is created and
9324 given an initial value by using the @code{defvar} special form. The
9325 name comes from ``define variable''.
9327 The @code{defvar} special form is similar to @code{setq} in that it sets
9328 the value of a variable. It is unlike @code{setq} in two ways: first,
9329 it only sets the value of the variable if the variable does not already
9330 have a value. If the variable already has a value, @code{defvar} does
9331 not override the existing value. Second, @code{defvar} has a
9332 documentation string.
9334 (Another special form, @code{defcustom}, is designed for variables
9335 that people customize. It has more features than @code{defvar}.
9336 (@xref{defcustom, , Setting Variables with @code{defcustom}}.)
9339 * See variable current value::
9340 * defvar and asterisk::
9343 @node See variable current value, defvar and asterisk, defvar, defvar
9345 @unnumberedsubsec Seeing the Current Value of a Variable
9348 You can see the current value of a variable, any variable, by using
9349 the @code{describe-variable} function, which is usually invoked by
9350 typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring}
9351 (followed by @key{RET}) when prompted, you will see what is in your
9352 current kill ring---this may be quite a lot! Conversely, if you have
9353 been doing nothing this Emacs session except read this document, you
9354 may have nothing in it. Also, you will see the documentation for
9360 List of killed text sequences.
9361 Since the kill ring is supposed to interact nicely with cut-and-paste
9362 facilities offered by window systems, use of this variable should
9365 interact nicely with `interprogram-cut-function' and
9366 `interprogram-paste-function'. The functions `kill-new',
9367 `kill-append', and `current-kill' are supposed to implement this
9368 interaction; you may want to use them instead of manipulating the kill
9374 The kill ring is defined by a @code{defvar} in the following way:
9378 (defvar kill-ring nil
9379 "List of killed text sequences.
9385 In this variable definition, the variable is given an initial value of
9386 @code{nil}, which makes sense, since if you have saved nothing, you want
9387 nothing back if you give a @code{yank} command. The documentation
9388 string is written just like the documentation string of a @code{defun}.
9389 As with the documentation string of the @code{defun}, the first line of
9390 the documentation should be a complete sentence, since some commands,
9391 like @code{apropos}, print only the first line of documentation.
9392 Succeeding lines should not be indented; otherwise they look odd when
9393 you use @kbd{C-h v} (@code{describe-variable}).
9395 @node defvar and asterisk, , See variable current value, defvar
9396 @subsection @code{defvar} and an asterisk
9397 @findex defvar @r{for a user customizable variable}
9398 @findex defvar @r{with an asterisk}
9400 In the past, Emacs used the @code{defvar} special form both for
9401 internal variables that you would not expect a user to change and for
9402 variables that you do expect a user to change. Although you can still
9403 use @code{defvar} for user customizable variables, please use
9404 @code{defcustom} instead, since that special form provides a path into
9405 the Customization commands. (@xref{defcustom, , Specifying Variables
9406 using @code{defcustom}}.)
9408 When you specified a variable using the @code{defvar} special form,
9409 you could distinguish a readily settable variable from others by
9410 typing an asterisk, @samp{*}, in the first column of its documentation
9411 string. For example:
9415 (defvar shell-command-default-error-buffer nil
9416 "*Buffer name for `shell-command' @dots{} error output.
9421 @findex set-variable
9423 You could (and still can) use the @code{set-variable} command to
9424 change the value of @code{shell-command-default-error-buffer}
9425 temporarily. However, options set using @code{set-variable} are set
9426 only for the duration of your editing session. The new values are not
9427 saved between sessions. Each time Emacs starts, it reads the original
9428 value, unless you change the value within your @file{.emacs} file,
9429 either by setting it manually or by using @code{customize}.
9430 @xref{Emacs Initialization, , Your @file{.emacs} File}.
9432 For me, the major use of the @code{set-variable} command is to suggest
9433 variables that I might want to set in my @file{.emacs} file. There
9434 are now more than 700 such variables --- far too many to remember
9435 readily. Fortunately, you can press @key{TAB} after calling the
9436 @code{M-x set-variable} command to see the list of variables.
9437 (@xref{Examining, , Examining and Setting Variables, emacs,
9438 The GNU Emacs Manual}.)
9441 @node cons & search-fwd Review, search Exercises, defvar, Cutting & Storing Text
9442 @comment node-name, next, previous, up
9445 Here is a brief summary of some recently introduced functions.
9450 @code{car} returns the first element of a list; @code{cdr} returns the
9451 second and subsequent elements of a list.
9458 (car '(1 2 3 4 5 6 7))
9460 (cdr '(1 2 3 4 5 6 7))
9461 @result{} (2 3 4 5 6 7)
9466 @code{cons} constructs a list by prepending its first argument to its
9480 Return the result of taking @sc{cdr} `n' times on a list.
9488 The `rest of the rest', as it were.
9495 (nthcdr 3 '(1 2 3 4 5 6 7))
9502 @code{setcar} changes the first element of a list; @code{setcdr}
9503 changes the second and subsequent elements of a list.
9510 (setq triple '(1 2 3))
9517 (setcdr triple '("foo" "bar"))
9520 @result{} (37 "foo" "bar")
9525 Evaluate each argument in sequence and then return the value of the
9538 @item save-restriction
9539 Record whatever narrowing is in effect in the current buffer, if any,
9540 and restore that narrowing after evaluating the arguments.
9542 @item search-forward
9543 Search for a string, and if the string is found, move point.
9547 Takes four arguments:
9551 The string to search for.
9554 Optionally, the limit of the search.
9557 Optionally, what to do if the search fails, return @code{nil} or an
9561 Optionally, how many times to repeat the search; if negative, the
9562 search goes backwards.
9566 @itemx delete-and-extract-region
9567 @itemx copy-region-as-kill
9569 @code{kill-region} cuts the text between point and mark from the
9570 buffer and stores that text in the kill ring, so you can get it back
9573 @code{copy-region-as-kill} copies the text between point and mark into
9574 the kill ring, from which you can get it by yanking. The function
9575 does not cut or remove the text from the buffer.
9578 @code{delete-and-extract-region} removes the text between point and
9579 mark from the buffer and throws it away. You cannot get it back.
9580 (This is not an interactive command.)
9583 @node search Exercises, , cons & search-fwd Review, Cutting & Storing Text
9584 @section Searching Exercises
9588 Write an interactive function that searches for a string. If the
9589 search finds the string, leave point after it and display a message
9590 that says ``Found!''. (Do not use @code{search-forward} for the name
9591 of this function; if you do, you will overwrite the existing version of
9592 @code{search-forward} that comes with Emacs. Use a name such as
9593 @code{test-search} instead.)
9596 Write a function that prints the third element of the kill ring in the
9597 echo area, if any; if the kill ring does not contain a third element,
9598 print an appropriate message.
9601 @node List Implementation, Yanking, Cutting & Storing Text, Top
9602 @comment node-name, next, previous, up
9603 @chapter How Lists are Implemented
9604 @cindex Lists in a computer
9606 In Lisp, atoms are recorded in a straightforward fashion; if the
9607 implementation is not straightforward in practice, it is, nonetheless,
9608 straightforward in theory. The atom @samp{rose}, for example, is
9609 recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s},
9610 @samp{e}. A list, on the other hand, is kept differently. The mechanism
9611 is equally simple, but it takes a moment to get used to the idea. A
9612 list is kept using a series of pairs of pointers. In the series, the
9613 first pointer in each pair points to an atom or to another list, and the
9614 second pointer in each pair points to the next pair, or to the symbol
9615 @code{nil}, which marks the end of the list.
9617 A pointer itself is quite simply the electronic address of what is
9618 pointed to. Hence, a list is kept as a series of electronic addresses.
9621 * Lists diagrammed::
9622 * Symbols as Chest::
9626 @node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation
9628 @unnumberedsec Lists diagrammed
9631 For example, the list @code{(rose violet buttercup)} has three elements,
9632 @samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the
9633 electronic address of @samp{rose} is recorded in a segment of computer
9634 memory along with the address that gives the electronic address of where
9635 the atom @samp{violet} is located; and that address (the one that tells
9636 where @samp{violet} is located) is kept along with an address that tells
9637 where the address for the atom @samp{buttercup} is located.
9640 This sounds more complicated than it is and is easier seen in a diagram:
9642 @c clear print-postscript-figures
9643 @c !!! cons-cell-diagram #1
9647 ___ ___ ___ ___ ___ ___
9648 |___|___|--> |___|___|--> |___|___|--> nil
9651 --> rose --> violet --> buttercup
9655 @ifset print-postscript-figures
9659 %%%% old method of including an image
9660 % \input /usr/local/lib/tex/inputs/psfig.tex
9661 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}}
9666 @ifclear print-postscript-figures
9670 ___ ___ ___ ___ ___ ___
9671 |___|___|--> |___|___|--> |___|___|--> nil
9674 --> rose --> violet --> buttercup
9681 In the diagram, each box represents a word of computer memory that
9682 holds a Lisp object, usually in the form of a memory address. The boxes,
9683 i.e.@: the addresses, are in pairs. Each arrow points to what the address
9684 is the address of, either an atom or another pair of addresses. The
9685 first box is the electronic address of @samp{rose} and the arrow points
9686 to @samp{rose}; the second box is the address of the next pair of boxes,
9687 the first part of which is the address of @samp{violet} and the second
9688 part of which is the address of the next pair. The very last box
9689 points to the symbol @code{nil}, which marks the end of the list.
9692 When a variable is set to a list with a function such as @code{setq},
9693 it stores the address of the first box in the variable. Thus,
9694 evaluation of the expression
9697 (setq bouquet '(rose violet buttercup))
9702 creates a situation like this:
9704 @c cons-cell-diagram #2
9710 | ___ ___ ___ ___ ___ ___
9711 --> |___|___|--> |___|___|--> |___|___|--> nil
9714 --> rose --> violet --> buttercup
9718 @ifset print-postscript-figures
9722 %%%% old method of including an image
9723 % \input /usr/local/lib/tex/inputs/psfig.tex
9724 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}}
9729 @ifclear print-postscript-figures
9735 | ___ ___ ___ ___ ___ ___
9736 --> |___|___|--> |___|___|--> |___|___|--> nil
9739 --> rose --> violet --> buttercup
9746 In this example, the symbol @code{bouquet} holds the address of the first
9750 This same list can be illustrated in a different sort of box notation
9753 @c cons-cell-diagram #2a
9759 | -------------- --------------- ----------------
9760 | | car | cdr | | car | cdr | | car | cdr |
9761 -->| rose | o------->| violet | o------->| butter- | nil |
9762 | | | | | | | cup | |
9763 -------------- --------------- ----------------
9767 @ifset print-postscript-figures
9771 %%%% old method of including an image
9772 % \input /usr/local/lib/tex/inputs/psfig.tex
9773 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}}
9778 @ifclear print-postscript-figures
9784 | -------------- --------------- ----------------
9785 | | car | cdr | | car | cdr | | car | cdr |
9786 -->| rose | o------->| violet | o------->| butter- | nil |
9787 | | | | | | | cup | |
9788 -------------- --------------- ----------------
9794 (Symbols consist of more than pairs of addresses, but the structure of
9795 a symbol is made up of addresses. Indeed, the symbol @code{bouquet}
9796 consists of a group of address-boxes, one of which is the address of
9797 the printed word @samp{bouquet}, a second of which is the address of a
9798 function definition attached to the symbol, if any, a third of which
9799 is the address of the first pair of address-boxes for the list
9800 @code{(rose violet buttercup)}, and so on. Here we are showing that
9801 the symbol's third address-box points to the first pair of
9802 address-boxes for the list.)
9804 If a symbol is set to the @sc{cdr} of a list, the list itself is not
9805 changed; the symbol simply has an address further down the list. (In
9806 the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus,
9807 evaluation of the following expression
9810 (setq flowers (cdr bouquet))
9817 @c cons-cell-diagram #3
9824 | ___ ___ | ___ ___ ___ ___
9825 --> | | | --> | | | | | |
9826 |___|___|----> |___|___|--> |___|___|--> nil
9829 --> rose --> violet --> buttercup
9834 @ifset print-postscript-figures
9838 %%%% old method of including an image
9839 % \input /usr/local/lib/tex/inputs/psfig.tex
9840 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}}
9845 @ifclear print-postscript-figures
9852 | ___ ___ | ___ ___ ___ ___
9853 --> | | | --> | | | | | |
9854 |___|___|----> |___|___|--> |___|___|--> nil
9857 --> rose --> violet --> buttercup
9865 The value of @code{flowers} is @code{(violet buttercup)}, which is
9866 to say, the symbol @code{flowers} holds the address of the pair of
9867 address-boxes, the first of which holds the address of @code{violet},
9868 and the second of which holds the address of @code{buttercup}.
9870 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
9871 pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp
9872 Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair
9873 Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more
9874 information about cons cells and dotted pairs.
9877 The function @code{cons} adds a new pair of addresses to the front of
9878 a series of addresses like that shown above. For example, evaluating
9882 (setq bouquet (cons 'lily bouquet))
9889 @c cons-cell-diagram #4
9896 | ___ ___ ___ ___ | ___ ___ ___ ___
9897 --> | | | | | | --> | | | | | |
9898 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9901 --> lily --> rose --> violet --> buttercup
9906 @ifset print-postscript-figures
9910 %%%% old method of including an image
9911 % \input /usr/local/lib/tex/inputs/psfig.tex
9912 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}}
9917 @ifclear print-postscript-figures
9924 | ___ ___ ___ ___ | ___ ___ ___ ___
9925 --> | | | | | | --> | | | | | |
9926 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9929 --> lily --> rose --> violet --> buttercup
9938 However, this does not change the value of the symbol
9939 @code{flowers}, as you can see by evaluating the following,
9942 (eq (cdr (cdr bouquet)) flowers)
9946 which returns @code{t} for true.
9948 Until it is reset, @code{flowers} still has the value
9949 @code{(violet buttercup)}; that is, it has the address of the cons
9950 cell whose first address is of @code{violet}. Also, this does not
9951 alter any of the pre-existing cons cells; they are all still there.
9953 Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address
9954 of the next cons cell in the series; to get the @sc{car} of a list,
9955 you get the address of the first element of the list; to @code{cons} a
9956 new element on a list, you add a new cons cell to the front of the list.
9957 That is all there is to it! The underlying structure of Lisp is
9960 And what does the last address in a series of cons cells refer to? It
9961 is the address of the empty list, of @code{nil}.
9963 In summary, when a Lisp variable is set to a value, it is provided with
9964 the address of the list to which the variable refers.
9966 @node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation
9967 @section Symbols as a Chest of Drawers
9968 @cindex Symbols as a Chest of Drawers
9969 @cindex Chest of Drawers, metaphor for a symbol
9970 @cindex Drawers, Chest of, metaphor for a symbol
9972 In an earlier section, I suggested that you might imagine a symbol as
9973 being a chest of drawers. The function definition is put in one
9974 drawer, the value in another, and so on. What is put in the drawer
9975 holding the value can be changed without affecting the contents of the
9976 drawer holding the function definition, and vice-verse.
9978 Actually, what is put in each drawer is the address of the value or
9979 function definition. It is as if you found an old chest in the attic,
9980 and in one of its drawers you found a map giving you directions to
9981 where the buried treasure lies.
9983 (In addition to its name, symbol definition, and variable value, a
9984 symbol has a `drawer' for a @dfn{property list} which can be used to
9985 record other information. Property lists are not discussed here; see
9986 @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp
9990 Here is a fanciful representation:
9992 @c chest-of-drawers diagram
9997 Chest of Drawers Contents of Drawers
10001 ---------------------
10002 | directions to | [map to]
10003 | symbol name | bouquet
10005 +---------------------+
10007 | symbol definition | [none]
10009 +---------------------+
10010 | directions to | [map to]
10011 | variable value | (rose violet buttercup)
10013 +---------------------+
10015 | property list | [not described here]
10017 +---------------------+
10023 @ifset print-postscript-figures
10027 %%%% old method of including an image
10028 % \input /usr/local/lib/tex/inputs/psfig.tex
10029 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}}
10034 @ifclear print-postscript-figures
10039 Chest of Drawers Contents of Drawers
10043 ---------------------
10044 | directions to | [map to]
10045 | symbol name | bouquet
10047 +---------------------+
10049 | symbol definition | [none]
10051 +---------------------+
10052 | directions to | [map to]
10053 | variable value | (rose violet buttercup)
10055 +---------------------+
10057 | property list | [not described here]
10059 +---------------------+
10067 @node List Exercise, , Symbols as Chest, List Implementation
10070 Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two
10071 more flowers on to this list and set this new list to
10072 @code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish.
10073 What does the @code{more-flowers} list now contain?
10075 @node Yanking, Loops & Recursion, List Implementation, Top
10076 @comment node-name, next, previous, up
10077 @chapter Yanking Text Back
10079 @findex rotate-yank-pointer
10080 @cindex Text retrieval
10081 @cindex Retrieving text
10082 @cindex Pasting text
10084 Whenever you cut text out of a buffer with a `kill' command in GNU Emacs,
10085 you can bring it back with a `yank' command. The text that is cut out of
10086 the buffer is put in the kill ring and the yank commands insert the
10087 appropriate contents of the kill ring back into a buffer (not necessarily
10088 the original buffer).
10090 A simple @kbd{C-y} (@code{yank}) command inserts the first item from
10091 the kill ring into the current buffer. If the @kbd{C-y} command is
10092 followed immediately by @kbd{M-y}, the first element is replaced by
10093 the second element. Successive @kbd{M-y} commands replace the second
10094 element with the third, fourth, or fifth element, and so on. When the
10095 last element in the kill ring is reached, it is replaced by the first
10096 element and the cycle is repeated. (Thus the kill ring is called a
10097 `ring' rather than just a `list'. However, the actual data structure
10098 that holds the text is a list.
10099 @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the
10100 list is handled as a ring.)
10103 * Kill Ring Overview::
10104 * kill-ring-yank-pointer::
10105 * yank nthcdr Exercises::
10108 @node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking
10109 @comment node-name, next, previous, up
10110 @section Kill Ring Overview
10111 @cindex Kill ring overview
10113 The kill ring is a list of textual strings. This is what it looks like:
10116 ("some text" "a different piece of text" "yet more text")
10119 If this were the contents of my kill ring and I pressed @kbd{C-y}, the
10120 string of characters saying @samp{some text} would be inserted in this
10121 buffer where my cursor is located.
10123 The @code{yank} command is also used for duplicating text by copying it.
10124 The copied text is not cut from the buffer, but a copy of it is put on the
10125 kill ring and is inserted by yanking it back.
10127 Three functions are used for bringing text back from the kill ring:
10128 @code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop},
10129 which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer},
10130 which is used by the two other functions.
10132 These functions refer to the kill ring through a variable called the
10133 @code{kill-ring-yank-pointer}. Indeed, the insertion code for both the
10134 @code{yank} and @code{yank-pop} functions is:
10137 (insert (car kill-ring-yank-pointer))
10141 (Well, no more. In GNU Emacs 22, the function has been replaced by
10142 @code{insert-for-yank} which calls @code{insert-for-yank-1}
10143 repetitively for each @code{yank-handler} segment. In turn,
10144 @code{insert-for-yank-1} strips text properties from the inserted text
10145 according to @code{yank-excluded-properties}. Otherwise, it is just
10146 like @code{insert}. We will stick with plain @code{insert} since it
10147 is easier to understand.)
10149 To begin to understand how @code{yank} and @code{yank-pop} work, it is
10150 first necessary to look at the @code{kill-ring-yank-pointer} variable
10151 and the @code{rotate-yank-pointer} function.
10153 @node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking
10154 @comment node-name, next, previous, up
10155 @section The @code{kill-ring-yank-pointer} Variable
10157 @code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is
10158 a variable. It points to something by being bound to the value of what
10159 it points to, like any other Lisp variable.
10162 Thus, if the value of the kill ring is:
10165 ("some text" "a different piece of text" "yet more text")
10170 and the @code{kill-ring-yank-pointer} points to the second clause, the
10171 value of @code{kill-ring-yank-pointer} is:
10174 ("a different piece of text" "yet more text")
10177 As explained in the previous chapter (@pxref{List Implementation}), the
10178 computer does not keep two different copies of the text being pointed to
10179 by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The
10180 words ``a different piece of text'' and ``yet more text'' are not
10181 duplicated. Instead, the two Lisp variables point to the same pieces of
10182 text. Here is a diagram:
10184 @c cons-cell-diagram #5
10188 kill-ring kill-ring-yank-pointer
10190 | ___ ___ | ___ ___ ___ ___
10191 ---> | | | --> | | | | | |
10192 |___|___|----> |___|___|--> |___|___|--> nil
10195 | | --> "yet more text"
10197 | --> "a different piece of text
10204 @ifset print-postscript-figures
10208 %%%% old method of including an image
10209 % \input /usr/local/lib/tex/inputs/psfig.tex
10210 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}}
10215 @ifclear print-postscript-figures
10219 kill-ring kill-ring-yank-pointer
10221 | ___ ___ | ___ ___ ___ ___
10222 ---> | | | --> | | | | | |
10223 |___|___|----> |___|___|--> |___|___|--> nil
10226 | | --> "yet more text"
10228 | --> "a different piece of text
10237 Both the variable @code{kill-ring} and the variable
10238 @code{kill-ring-yank-pointer} are pointers. But the kill ring itself is
10239 usually described as if it were actually what it is composed of. The
10240 @code{kill-ring} is spoken of as if it were the list rather than that it
10241 points to the list. Conversely, the @code{kill-ring-yank-pointer} is
10242 spoken of as pointing to a list.
10244 These two ways of talking about the same thing sound confusing at first but
10245 make sense on reflection. The kill ring is generally thought of as the
10246 complete structure of data that holds the information of what has recently
10247 been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer}
10248 on the other hand, serves to indicate---that is, to `point to'---that part
10249 of the kill ring of which the first element (the @sc{car}) will be
10253 In GNU Emacs 22, the @code{kill-new} function calls
10255 @code{(setq kill-ring-yank-pointer kill-ring)}
10257 (defun rotate-yank-pointer (arg)
10258 "Rotate the yanking point in the kill ring.
10259 With argument, rotate that many kills forward (or backward, if negative)."
10261 (current-kill arg))
10263 (defun current-kill (n &optional do-not-move)
10264 "Rotate the yanking point by N places, and then return that kill.
10265 If N is zero, `interprogram-paste-function' is set, and calling it
10266 returns a string, then that string is added to the front of the
10267 kill ring and returned as the latest kill.
10268 If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
10269 yanking point; just return the Nth kill forward."
10270 (let ((interprogram-paste (and (= n 0)
10271 interprogram-paste-function
10272 (funcall interprogram-paste-function))))
10273 (if interprogram-paste
10275 ;; Disable the interprogram cut function when we add the new
10276 ;; text to the kill ring, so Emacs doesn't try to own the
10277 ;; selection, with identical text.
10278 (let ((interprogram-cut-function nil))
10279 (kill-new interprogram-paste))
10280 interprogram-paste)
10281 (or kill-ring (error "Kill ring is empty"))
10282 (let ((ARGth-kill-element
10283 (nthcdr (mod (- n (length kill-ring-yank-pointer))
10284 (length kill-ring))
10287 (setq kill-ring-yank-pointer ARGth-kill-element))
10288 (car ARGth-kill-element)))))
10293 @node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking
10294 @section Exercises with @code{yank} and @code{nthcdr}
10298 Using @kbd{C-h v} (@code{describe-variable}), look at the value of
10299 your kill ring. Add several items to your kill ring; look at its
10300 value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way
10301 around the kill ring. How many items were in your kill ring? Find
10302 the value of @code{kill-ring-max}. Was your kill ring full, or could
10303 you have kept more blocks of text within it?
10306 Using @code{nthcdr} and @code{car}, construct a series of expressions
10307 to return the first, second, third, and fourth elements of a list.
10310 @node Loops & Recursion, Regexp Search, Yanking, Top
10311 @comment node-name, next, previous, up
10312 @chapter Loops and Recursion
10313 @cindex Loops and recursion
10314 @cindex Recursion and loops
10315 @cindex Repetition (loops)
10317 Emacs Lisp has two primary ways to cause an expression, or a series of
10318 expressions, to be evaluated repeatedly: one uses a @code{while}
10319 loop, and the other uses @dfn{recursion}.
10321 Repetition can be very valuable. For example, to move forward four
10322 sentences, you need only write a program that will move forward one
10323 sentence and then repeat the process four times. Since a computer does
10324 not get bored or tired, such repetitive action does not have the
10325 deleterious effects that excessive or the wrong kinds of repetition can
10328 People mostly write Emacs Lisp functions using @code{while} loops and
10329 their kin; but you can use recursion, which provides a very powerful
10330 way to think about and then to solve problems@footnote{You can write
10331 recursive functions to be frugal or wasteful of mental or computer
10332 resources; as it happens, methods that people find easy---that are
10333 frugal of `mental resources'---sometimes use considerable computer
10334 resources. Emacs was designed to run on machines that we now consider
10335 limited and its default settings are conservative. You may want to
10336 increase the values of @code{max-specpdl-size} and
10337 @code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to
10338 15 and 30 times their default value.}.
10344 * Looping exercise::
10347 @node while, dolist dotimes, Loops & Recursion, Loops & Recursion
10348 @comment node-name, next, previous, up
10349 @section @code{while}
10353 The @code{while} special form tests whether the value returned by
10354 evaluating its first argument is true or false. This is similar to what
10355 the Lisp interpreter does with an @code{if}; what the interpreter does
10356 next, however, is different.
10358 In a @code{while} expression, if the value returned by evaluating the
10359 first argument is false, the Lisp interpreter skips the rest of the
10360 expression (the @dfn{body} of the expression) and does not evaluate it.
10361 However, if the value is true, the Lisp interpreter evaluates the body
10362 of the expression and then again tests whether the first argument to
10363 @code{while} is true or false. If the value returned by evaluating the
10364 first argument is again true, the Lisp interpreter again evaluates the
10365 body of the expression.
10368 The template for a @code{while} expression looks like this:
10372 (while @var{true-or-false-test}
10378 * Looping with while::
10380 * print-elements-of-list::
10381 * Incrementing Loop::
10382 * Decrementing Loop::
10385 @node Looping with while, Loop Example, while, while
10387 @unnumberedsubsec Looping with @code{while}
10390 So long as the true-or-false-test of the @code{while} expression
10391 returns a true value when it is evaluated, the body is repeatedly
10392 evaluated. This process is called a loop since the Lisp interpreter
10393 repeats the same thing again and again, like an airplane doing a loop.
10394 When the result of evaluating the true-or-false-test is false, the
10395 Lisp interpreter does not evaluate the rest of the @code{while}
10396 expression and `exits the loop'.
10398 Clearly, if the value returned by evaluating the first argument to
10399 @code{while} is always true, the body following will be evaluated
10400 again and again @dots{} and again @dots{} forever. Conversely, if the
10401 value returned is never true, the expressions in the body will never
10402 be evaluated. The craft of writing a @code{while} loop consists of
10403 choosing a mechanism such that the true-or-false-test returns true
10404 just the number of times that you want the subsequent expressions to
10405 be evaluated, and then have the test return false.
10407 The value returned by evaluating a @code{while} is the value of the
10408 true-or-false-test. An interesting consequence of this is that a
10409 @code{while} loop that evaluates without error will return @code{nil}
10410 or false regardless of whether it has looped 1 or 100 times or none at
10411 all. A @code{while} expression that evaluates successfully never
10412 returns a true value! What this means is that @code{while} is always
10413 evaluated for its side effects, which is to say, the consequences of
10414 evaluating the expressions within the body of the @code{while} loop.
10415 This makes sense. It is not the mere act of looping that is desired,
10416 but the consequences of what happens when the expressions in the loop
10417 are repeatedly evaluated.
10419 @node Loop Example, print-elements-of-list, Looping with while, while
10420 @comment node-name, next, previous, up
10421 @subsection A @code{while} Loop and a List
10423 A common way to control a @code{while} loop is to test whether a list
10424 has any elements. If it does, the loop is repeated; but if it does not,
10425 the repetition is ended. Since this is an important technique, we will
10426 create a short example to illustrate it.
10428 A simple way to test whether a list has elements is to evaluate the
10429 list: if it has no elements, it is an empty list and will return the
10430 empty list, @code{()}, which is a synonym for @code{nil} or false. On
10431 the other hand, a list with elements will return those elements when it
10432 is evaluated. Since Emacs Lisp considers as true any value that is not
10433 @code{nil}, a list that returns elements will test true in a
10437 For example, you can set the variable @code{empty-list} to @code{nil} by
10438 evaluating the following @code{setq} expression:
10441 (setq empty-list ())
10445 After evaluating the @code{setq} expression, you can evaluate the
10446 variable @code{empty-list} in the usual way, by placing the cursor after
10447 the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your
10454 On the other hand, if you set a variable to be a list with elements, the
10455 list will appear when you evaluate the variable, as you can see by
10456 evaluating the following two expressions:
10460 (setq animals '(gazelle giraffe lion tiger))
10466 Thus, to create a @code{while} loop that tests whether there are any
10467 items in the list @code{animals}, the first part of the loop will be
10478 When the @code{while} tests its first argument, the variable
10479 @code{animals} is evaluated. It returns a list. So long as the list
10480 has elements, the @code{while} considers the results of the test to be
10481 true; but when the list is empty, it considers the results of the test
10484 To prevent the @code{while} loop from running forever, some mechanism
10485 needs to be provided to empty the list eventually. An oft-used
10486 technique is to have one of the subsequent forms in the @code{while}
10487 expression set the value of the list to be the @sc{cdr} of the list.
10488 Each time the @code{cdr} function is evaluated, the list will be made
10489 shorter, until eventually only the empty list will be left. At this
10490 point, the test of the @code{while} loop will return false, and the
10491 arguments to the @code{while} will no longer be evaluated.
10493 For example, the list of animals bound to the variable @code{animals}
10494 can be set to be the @sc{cdr} of the original list with the
10495 following expression:
10498 (setq animals (cdr animals))
10502 If you have evaluated the previous expressions and then evaluate this
10503 expression, you will see @code{(giraffe lion tiger)} appear in the echo
10504 area. If you evaluate the expression again, @code{(lion tiger)} will
10505 appear in the echo area. If you evaluate it again and yet again,
10506 @code{(tiger)} appears and then the empty list, shown by @code{nil}.
10508 A template for a @code{while} loop that uses the @code{cdr} function
10509 repeatedly to cause the true-or-false-test eventually to test false
10514 (while @var{test-whether-list-is-empty}
10516 @var{set-list-to-cdr-of-list})
10520 This test and use of @code{cdr} can be put together in a function that
10521 goes through a list and prints each element of the list on a line of its
10524 @node print-elements-of-list, Incrementing Loop, Loop Example, while
10525 @subsection An Example: @code{print-elements-of-list}
10526 @findex print-elements-of-list
10528 The @code{print-elements-of-list} function illustrates a @code{while}
10531 @cindex @file{*scratch*} buffer
10532 The function requires several lines for its output. If you are
10533 reading this in a recent instance of GNU Emacs,
10534 @c GNU Emacs 21, GNU Emacs 22, or a later version,
10535 you can evaluate the following expression inside of Info, as usual.
10537 If you are using an earlier version of Emacs, you need to copy the
10538 necessary expressions to your @file{*scratch*} buffer and evaluate
10539 them there. This is because the echo area had only one line in the
10542 You can copy the expressions by marking the beginning of the region
10543 with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to
10544 the end of the region and then copying the region using @kbd{M-w}
10545 (@code{kill-ring-save}, which calls @code{copy-region-as-kill} and
10546 then provides visual feedback). In the @file{*scratch*}
10547 buffer, you can yank the expressions back by typing @kbd{C-y}
10550 After you have copied the expressions to the @file{*scratch*} buffer,
10551 evaluate each expression in turn. Be sure to evaluate the last
10552 expression, @code{(print-elements-of-list animals)}, by typing
10553 @kbd{C-u C-x C-e}, that is, by giving an argument to
10554 @code{eval-last-sexp}. This will cause the result of the evaluation
10555 to be printed in the @file{*scratch*} buffer instead of being printed
10556 in the echo area. (Otherwise you will see something like this in your
10557 echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which
10558 each @samp{^J} stands for a `newline'.)
10561 In a recent instance of GNU Emacs, you can evaluate these expressions
10562 directly in the Info buffer, and the echo area will grow to show the
10567 (setq animals '(gazelle giraffe lion tiger))
10569 (defun print-elements-of-list (list)
10570 "Print each element of LIST on a line of its own."
10573 (setq list (cdr list))))
10575 (print-elements-of-list animals)
10581 When you evaluate the three expressions in sequence, you will see
10597 Each element of the list is printed on a line of its own (that is what
10598 the function @code{print} does) and then the value returned by the
10599 function is printed. Since the last expression in the function is the
10600 @code{while} loop, and since @code{while} loops always return
10601 @code{nil}, a @code{nil} is printed after the last element of the list.
10603 @node Incrementing Loop, Decrementing Loop, print-elements-of-list, while
10604 @comment node-name, next, previous, up
10605 @subsection A Loop with an Incrementing Counter
10607 A loop is not useful unless it stops when it ought. Besides
10608 controlling a loop with a list, a common way of stopping a loop is to
10609 write the first argument as a test that returns false when the correct
10610 number of repetitions are complete. This means that the loop must
10611 have a counter---an expression that counts how many times the loop
10614 The test can be an expression such as @code{(< count desired-number)}
10615 which returns @code{t} for true if the value of @code{count} is less
10616 than the @code{desired-number} of repetitions and @code{nil} for false if
10617 the value of @code{count} is equal to or is greater than the
10618 @code{desired-number}. The expression that increments the count can be
10619 a simple @code{setq} such as @code{(setq count (1+ count))}, where
10620 @code{1+} is a built-in function in Emacs Lisp that adds 1 to its
10621 argument. (The expression @w{@code{(1+ count)}} has the same result as
10622 @w{@code{(+ count 1)}}, but is easier for a human to read.)
10625 The template for a @code{while} loop controlled by an incrementing
10626 counter looks like this:
10630 @var{set-count-to-initial-value}
10631 (while (< count desired-number) ; @r{true-or-false-test}
10633 (setq count (1+ count))) ; @r{incrementer}
10638 Note that you need to set the initial value of @code{count}; usually it
10642 * Incrementing Example::
10643 * Inc Example parts::
10644 * Inc Example altogether::
10647 @node Incrementing Example, Inc Example parts, Incrementing Loop, Incrementing Loop
10648 @unnumberedsubsubsec Example with incrementing counter
10650 Suppose you are playing on the beach and decide to make a triangle of
10651 pebbles, putting one pebble in the first row, two in the second row,
10652 three in the third row and so on, like this:
10670 @bullet{} @bullet{}
10671 @bullet{} @bullet{} @bullet{}
10672 @bullet{} @bullet{} @bullet{} @bullet{}
10679 (About 2500 years ago, Pythagoras and others developed the beginnings of
10680 number theory by considering questions such as this.)
10682 Suppose you want to know how many pebbles you will need to make a
10683 triangle with 7 rows?
10685 Clearly, what you need to do is add up the numbers from 1 to 7. There
10686 are two ways to do this; start with the smallest number, one, and add up
10687 the list in sequence, 1, 2, 3, 4 and so on; or start with the largest
10688 number and add the list going down: 7, 6, 5, 4 and so on. Because both
10689 mechanisms illustrate common ways of writing @code{while} loops, we will
10690 create two examples, one counting up and the other counting down. In
10691 this first example, we will start with 1 and add 2, 3, 4 and so on.
10693 If you are just adding up a short list of numbers, the easiest way to do
10694 it is to add up all the numbers at once. However, if you do not know
10695 ahead of time how many numbers your list will have, or if you want to be
10696 prepared for a very long list, then you need to design your addition so
10697 that what you do is repeat a simple process many times instead of doing
10698 a more complex process once.
10700 For example, instead of adding up all the pebbles all at once, what you
10701 can do is add the number of pebbles in the first row, 1, to the number
10702 in the second row, 2, and then add the total of those two rows to the
10703 third row, 3. Then you can add the number in the fourth row, 4, to the
10704 total of the first three rows; and so on.
10706 The critical characteristic of the process is that each repetitive
10707 action is simple. In this case, at each step we add only two numbers,
10708 the number of pebbles in the row and the total already found. This
10709 process of adding two numbers is repeated again and again until the last
10710 row has been added to the total of all the preceding rows. In a more
10711 complex loop the repetitive action might not be so simple, but it will
10712 be simpler than doing everything all at once.
10714 @node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop
10715 @unnumberedsubsubsec The parts of the function definition
10717 The preceding analysis gives us the bones of our function definition:
10718 first, we will need a variable that we can call @code{total} that will
10719 be the total number of pebbles. This will be the value returned by
10722 Second, we know that the function will require an argument: this
10723 argument will be the total number of rows in the triangle. It can be
10724 called @code{number-of-rows}.
10726 Finally, we need a variable to use as a counter. We could call this
10727 variable @code{counter}, but a better name is @code{row-number}. That
10728 is because what the counter does in this function is count rows, and a
10729 program should be written to be as understandable as possible.
10731 When the Lisp interpreter first starts evaluating the expressions in the
10732 function, the value of @code{total} should be set to zero, since we have
10733 not added anything to it. Then the function should add the number of
10734 pebbles in the first row to the total, and then add the number of
10735 pebbles in the second to the total, and then add the number of
10736 pebbles in the third row to the total, and so on, until there are no
10737 more rows left to add.
10739 Both @code{total} and @code{row-number} are used only inside the
10740 function, so they can be declared as local variables with @code{let}
10741 and given initial values. Clearly, the initial value for @code{total}
10742 should be 0. The initial value of @code{row-number} should be 1,
10743 since we start with the first row. This means that the @code{let}
10744 statement will look like this:
10754 After the internal variables are declared and bound to their initial
10755 values, we can begin the @code{while} loop. The expression that serves
10756 as the test should return a value of @code{t} for true so long as the
10757 @code{row-number} is less than or equal to the @code{number-of-rows}.
10758 (If the expression tests true only so long as the row number is less
10759 than the number of rows in the triangle, the last row will never be
10760 added to the total; hence the row number has to be either less than or
10761 equal to the number of rows.)
10764 @findex <= @r{(less than or equal)}
10765 Lisp provides the @code{<=} function that returns true if the value of
10766 its first argument is less than or equal to the value of its second
10767 argument and false otherwise. So the expression that the @code{while}
10768 will evaluate as its test should look like this:
10771 (<= row-number number-of-rows)
10774 The total number of pebbles can be found by repeatedly adding the number
10775 of pebbles in a row to the total already found. Since the number of
10776 pebbles in the row is equal to the row number, the total can be found by
10777 adding the row number to the total. (Clearly, in a more complex
10778 situation, the number of pebbles in the row might be related to the row
10779 number in a more complicated way; if this were the case, the row number
10780 would be replaced by the appropriate expression.)
10783 (setq total (+ total row-number))
10787 What this does is set the new value of @code{total} to be equal to the
10788 sum of adding the number of pebbles in the row to the previous total.
10790 After setting the value of @code{total}, the conditions need to be
10791 established for the next repetition of the loop, if there is one. This
10792 is done by incrementing the value of the @code{row-number} variable,
10793 which serves as a counter. After the @code{row-number} variable has
10794 been incremented, the true-or-false-test at the beginning of the
10795 @code{while} loop tests whether its value is still less than or equal to
10796 the value of the @code{number-of-rows} and if it is, adds the new value
10797 of the @code{row-number} variable to the @code{total} of the previous
10798 repetition of the loop.
10801 The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the
10802 @code{row-number} variable can be incremented with this expression:
10805 (setq row-number (1+ row-number))
10808 @node Inc Example altogether, , Inc Example parts, Incrementing Loop
10809 @unnumberedsubsubsec Putting the function definition together
10811 We have created the parts for the function definition; now we need to
10815 First, the contents of the @code{while} expression:
10819 (while (<= row-number number-of-rows) ; @r{true-or-false-test}
10820 (setq total (+ total row-number))
10821 (setq row-number (1+ row-number))) ; @r{incrementer}
10825 Along with the @code{let} expression varlist, this very nearly
10826 completes the body of the function definition. However, it requires
10827 one final element, the need for which is somewhat subtle.
10829 The final touch is to place the variable @code{total} on a line by
10830 itself after the @code{while} expression. Otherwise, the value returned
10831 by the whole function is the value of the last expression that is
10832 evaluated in the body of the @code{let}, and this is the value
10833 returned by the @code{while}, which is always @code{nil}.
10835 This may not be evident at first sight. It almost looks as if the
10836 incrementing expression is the last expression of the whole function.
10837 But that expression is part of the body of the @code{while}; it is the
10838 last element of the list that starts with the symbol @code{while}.
10839 Moreover, the whole of the @code{while} loop is a list within the body
10843 In outline, the function will look like this:
10847 (defun @var{name-of-function} (@var{argument-list})
10848 "@var{documentation}@dots{}"
10849 (let (@var{varlist})
10850 (while (@var{true-or-false-test})
10851 @var{body-of-while}@dots{} )
10852 @dots{} )) ; @r{Need final expression here.}
10856 The result of evaluating the @code{let} is what is going to be returned
10857 by the @code{defun} since the @code{let} is not embedded within any
10858 containing list, except for the @code{defun} as a whole. However, if
10859 the @code{while} is the last element of the @code{let} expression, the
10860 function will always return @code{nil}. This is not what we want!
10861 Instead, what we want is the value of the variable @code{total}. This
10862 is returned by simply placing the symbol as the last element of the list
10863 starting with @code{let}. It gets evaluated after the preceding
10864 elements of the list are evaluated, which means it gets evaluated after
10865 it has been assigned the correct value for the total.
10867 It may be easier to see this by printing the list starting with
10868 @code{let} all on one line. This format makes it evident that the
10869 @var{varlist} and @code{while} expressions are the second and third
10870 elements of the list starting with @code{let}, and the @code{total} is
10875 (let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total)
10880 Putting everything together, the @code{triangle} function definition
10885 (defun triangle (number-of-rows) ; @r{Version with}
10886 ; @r{ incrementing counter.}
10887 "Add up the number of pebbles in a triangle.
10888 The first row has one pebble, the second row two pebbles,
10889 the third row three pebbles, and so on.
10890 The argument is NUMBER-OF-ROWS."
10895 (while (<= row-number number-of-rows)
10896 (setq total (+ total row-number))
10897 (setq row-number (1+ row-number)))
10903 After you have installed @code{triangle} by evaluating the function, you
10904 can try it out. Here are two examples:
10915 The sum of the first four numbers is 10 and the sum of the first seven
10918 @node Decrementing Loop, , Incrementing Loop, while
10919 @comment node-name, next, previous, up
10920 @subsection Loop with a Decrementing Counter
10922 Another common way to write a @code{while} loop is to write the test
10923 so that it determines whether a counter is greater than zero. So long
10924 as the counter is greater than zero, the loop is repeated. But when
10925 the counter is equal to or less than zero, the loop is stopped. For
10926 this to work, the counter has to start out greater than zero and then
10927 be made smaller and smaller by a form that is evaluated
10930 The test will be an expression such as @code{(> counter 0)} which
10931 returns @code{t} for true if the value of @code{counter} is greater
10932 than zero, and @code{nil} for false if the value of @code{counter} is
10933 equal to or less than zero. The expression that makes the number
10934 smaller and smaller can be a simple @code{setq} such as @code{(setq
10935 counter (1- counter))}, where @code{1-} is a built-in function in
10936 Emacs Lisp that subtracts 1 from its argument.
10939 The template for a decrementing @code{while} loop looks like this:
10943 (while (> counter 0) ; @r{true-or-false-test}
10945 (setq counter (1- counter))) ; @r{decrementer}
10950 * Decrementing Example::
10951 * Dec Example parts::
10952 * Dec Example altogether::
10955 @node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop
10956 @unnumberedsubsubsec Example with decrementing counter
10958 To illustrate a loop with a decrementing counter, we will rewrite the
10959 @code{triangle} function so the counter decreases to zero.
10961 This is the reverse of the earlier version of the function. In this
10962 case, to find out how many pebbles are needed to make a triangle with
10963 3 rows, add the number of pebbles in the third row, 3, to the number
10964 in the preceding row, 2, and then add the total of those two rows to
10965 the row that precedes them, which is 1.
10967 Likewise, to find the number of pebbles in a triangle with 7 rows, add
10968 the number of pebbles in the seventh row, 7, to the number in the
10969 preceding row, which is 6, and then add the total of those two rows to
10970 the row that precedes them, which is 5, and so on. As in the previous
10971 example, each addition only involves adding two numbers, the total of
10972 the rows already added up and the number of pebbles in the row that is
10973 being added to the total. This process of adding two numbers is
10974 repeated again and again until there are no more pebbles to add.
10976 We know how many pebbles to start with: the number of pebbles in the
10977 last row is equal to the number of rows. If the triangle has seven
10978 rows, the number of pebbles in the last row is 7. Likewise, we know how
10979 many pebbles are in the preceding row: it is one less than the number in
10982 @node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop
10983 @unnumberedsubsubsec The parts of the function definition
10985 We start with three variables: the total number of rows in the
10986 triangle; the number of pebbles in a row; and the total number of
10987 pebbles, which is what we want to calculate. These variables can be
10988 named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and
10989 @code{total}, respectively.
10991 Both @code{total} and @code{number-of-pebbles-in-row} are used only
10992 inside the function and are declared with @code{let}. The initial
10993 value of @code{total} should, of course, be zero. However, the
10994 initial value of @code{number-of-pebbles-in-row} should be equal to
10995 the number of rows in the triangle, since the addition will start with
10999 This means that the beginning of the @code{let} expression will look
11005 (number-of-pebbles-in-row number-of-rows))
11010 The total number of pebbles can be found by repeatedly adding the number
11011 of pebbles in a row to the total already found, that is, by repeatedly
11012 evaluating the following expression:
11015 (setq total (+ total number-of-pebbles-in-row))
11019 After the @code{number-of-pebbles-in-row} is added to the @code{total},
11020 the @code{number-of-pebbles-in-row} should be decremented by one, since
11021 the next time the loop repeats, the preceding row will be
11022 added to the total.
11024 The number of pebbles in a preceding row is one less than the number of
11025 pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be
11026 used to compute the number of pebbles in the preceding row. This can be
11027 done with the following expression:
11031 (setq number-of-pebbles-in-row
11032 (1- number-of-pebbles-in-row))
11036 Finally, we know that the @code{while} loop should stop making repeated
11037 additions when there are no pebbles in a row. So the test for
11038 the @code{while} loop is simply:
11041 (while (> number-of-pebbles-in-row 0)
11044 @node Dec Example altogether, , Dec Example parts, Decrementing Loop
11045 @unnumberedsubsubsec Putting the function definition together
11047 We can put these expressions together to create a function definition
11048 that works. However, on examination, we find that one of the local
11049 variables is unneeded!
11052 The function definition looks like this:
11056 ;;; @r{First subtractive version.}
11057 (defun triangle (number-of-rows)
11058 "Add up the number of pebbles in a triangle."
11060 (number-of-pebbles-in-row number-of-rows))
11061 (while (> number-of-pebbles-in-row 0)
11062 (setq total (+ total number-of-pebbles-in-row))
11063 (setq number-of-pebbles-in-row
11064 (1- number-of-pebbles-in-row)))
11069 As written, this function works.
11071 However, we do not need @code{number-of-pebbles-in-row}.
11073 @cindex Argument as local variable
11074 When the @code{triangle} function is evaluated, the symbol
11075 @code{number-of-rows} will be bound to a number, giving it an initial
11076 value. That number can be changed in the body of the function as if
11077 it were a local variable, without any fear that such a change will
11078 effect the value of the variable outside of the function. This is a
11079 very useful characteristic of Lisp; it means that the variable
11080 @code{number-of-rows} can be used anywhere in the function where
11081 @code{number-of-pebbles-in-row} is used.
11084 Here is a second version of the function written a bit more cleanly:
11088 (defun triangle (number) ; @r{Second version.}
11089 "Return sum of numbers 1 through NUMBER inclusive."
11091 (while (> number 0)
11092 (setq total (+ total number))
11093 (setq number (1- number)))
11098 In brief, a properly written @code{while} loop will consist of three parts:
11102 A test that will return false after the loop has repeated itself the
11103 correct number of times.
11106 An expression the evaluation of which will return the value desired
11107 after being repeatedly evaluated.
11110 An expression to change the value passed to the true-or-false-test so
11111 that the test returns false after the loop has repeated itself the right
11115 @node dolist dotimes, Recursion, while, Loops & Recursion
11116 @comment node-name, next, previous, up
11117 @section Save your time: @code{dolist} and @code{dotimes}
11119 In addition to @code{while}, both @code{dolist} and @code{dotimes}
11120 provide for looping. Sometimes these are quicker to write than the
11121 equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, ,
11122 Macros, elisp, The GNU Emacs Lisp Reference Manual}. )
11124 @code{dolist} works like a @code{while} loop that `@sc{cdr}s down a
11125 list': @code{dolist} automatically shortens the list each time it
11126 loops---takes the @sc{cdr} of the list---and binds the @sc{car} of
11127 each shorter version of the list to the first of its arguments.
11129 @code{dotimes} loops a specific number of times: you specify the number.
11136 @node dolist, dotimes, dolist dotimes, dolist dotimes
11137 @unnumberedsubsubsec The @code{dolist} Macro
11140 Suppose, for example, you want to reverse a list, so that
11141 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''.
11144 In practice, you would use the @code{reverse} function, like this:
11148 (setq animals '(gazelle giraffe lion tiger))
11156 Here is how you could reverse the list using a @code{while} loop:
11160 (setq animals '(gazelle giraffe lion tiger))
11162 (defun reverse-list-with-while (list)
11163 "Using while, reverse the order of LIST."
11164 (let (value) ; make sure list starts empty
11166 (setq value (cons (car list) value))
11167 (setq list (cdr list)))
11170 (reverse-list-with-while animals)
11176 And here is how you could use the @code{dolist} macro:
11180 (setq animals '(gazelle giraffe lion tiger))
11182 (defun reverse-list-with-dolist (list)
11183 "Using dolist, reverse the order of LIST."
11184 (let (value) ; make sure list starts empty
11185 (dolist (element list value)
11186 (setq value (cons element value)))))
11188 (reverse-list-with-dolist animals)
11194 In Info, you can place your cursor after the closing parenthesis of
11195 each expression and type @kbd{C-x C-e}; in each case, you should see
11198 (tiger lion giraffe gazelle)
11204 For this example, the existing @code{reverse} function is obviously best.
11205 The @code{while} loop is just like our first example (@pxref{Loop
11206 Example, , A @code{while} Loop and a List}). The @code{while} first
11207 checks whether the list has elements; if so, it constructs a new list
11208 by adding the first element of the list to the existing list (which in
11209 the first iteration of the loop is @code{nil}). Since the second
11210 element is prepended in front of the first element, and the third
11211 element is prepended in front of the second element, the list is reversed.
11213 In the expression using a @code{while} loop,
11214 the @w{@code{(setq list (cdr list))}}
11215 expression shortens the list, so the @code{while} loop eventually
11216 stops. In addition, it provides the @code{cons} expression with a new
11217 first element by creating a new and shorter list at each repetition of
11220 The @code{dolist} expression does very much the same as the
11221 @code{while} expression, except that the @code{dolist} macro does some
11222 of the work you have to do when writing a @code{while} expression.
11224 Like a @code{while} loop, a @code{dolist} loops. What is different is
11225 that it automatically shortens the list each time it loops --- it
11226 `@sc{cdr}s down the list' on its own --- and it automatically binds
11227 the @sc{car} of each shorter version of the list to the first of its
11230 In the example, the @sc{car} of each shorter version of the list is
11231 referred to using the symbol @samp{element}, the list itself is called
11232 @samp{list}, and the value returned is called @samp{value}. The
11233 remainder of the @code{dolist} expression is the body.
11235 The @code{dolist} expression binds the @sc{car} of each shorter
11236 version of the list to @code{element} and then evaluates the body of
11237 the expression; and repeats the loop. The result is returned in
11240 @node dotimes, , dolist, dolist dotimes
11241 @unnumberedsubsubsec The @code{dotimes} Macro
11244 The @code{dotimes} macro is similar to @code{dolist}, except that it
11245 loops a specific number of times.
11247 The first argument to @code{dotimes} is assigned the numbers 0, 1, 2
11248 and so forth each time around the loop, and the value of the third
11249 argument is returned. You need to provide the value of the second
11250 argument, which is how many times the macro loops.
11253 For example, the following binds the numbers from 0 up to, but not
11254 including, the number 3 to the first argument, @var{number}, and then
11255 constructs a list of the three numbers. (The first number is 0, the
11256 second number is 1, and the third number is 2; this makes a total of
11257 three numbers in all, starting with zero as the first number.)
11261 (let (value) ; otherwise a value is a void variable
11262 (dotimes (number 3 value)
11263 (setq value (cons number value))))
11270 @code{dotimes} returns @code{value}, so the way to use
11271 @code{dotimes} is to operate on some expression @var{number} number of
11272 times and then return the result, either as a list or an atom.
11275 Here is an example of a @code{defun} that uses @code{dotimes} to add
11276 up the number of pebbles in a triangle.
11280 (defun triangle-using-dotimes (number-of-rows)
11281 "Using dotimes, add up the number of pebbles in a triangle."
11282 (let ((total 0)) ; otherwise a total is a void variable
11283 (dotimes (number number-of-rows total)
11284 (setq total (+ total (1+ number))))))
11286 (triangle-using-dotimes 4)
11290 @node Recursion, Looping exercise, dolist dotimes, Loops & Recursion
11291 @comment node-name, next, previous, up
11295 A recursive function contains code that tells the Lisp interpreter to
11296 call a program that runs exactly like itself, but with slightly
11297 different arguments. The code runs exactly the same because it has
11298 the same name. However, even though the program has the same name, it
11299 is not the same entity. It is different. In the jargon, it is a
11300 different `instance'.
11302 Eventually, if the program is written correctly, the `slightly
11303 different arguments' will become sufficiently different from the first
11304 arguments that the final instance will stop.
11307 * Building Robots::
11308 * Recursive Definition Parts::
11309 * Recursion with list::
11310 * Recursive triangle function::
11311 * Recursion with cond::
11312 * Recursive Patterns::
11314 * No deferment solution::
11317 @node Building Robots, Recursive Definition Parts, Recursion, Recursion
11318 @comment node-name, next, previous, up
11319 @subsection Building Robots: Extending the Metaphor
11320 @cindex Building robots
11321 @cindex Robots, building
11323 It is sometimes helpful to think of a running program as a robot that
11324 does a job. In doing its job, a recursive function calls on a second
11325 robot to help it. The second robot is identical to the first in every
11326 way, except that the second robot helps the first and has been
11327 passed different arguments than the first.
11329 In a recursive function, the second robot may call a third; and the
11330 third may call a fourth, and so on. Each of these is a different
11331 entity; but all are clones.
11333 Since each robot has slightly different instructions---the arguments
11334 will differ from one robot to the next---the last robot should know
11337 Let's expand on the metaphor in which a computer program is a robot.
11339 A function definition provides the blueprints for a robot. When you
11340 install a function definition, that is, when you evaluate a
11341 @code{defun} special form, you install the necessary equipment to
11342 build robots. It is as if you were in a factory, setting up an
11343 assembly line. Robots with the same name are built according to the
11344 same blueprints. So they have, as it were, the same `model number',
11345 but a different `serial number'.
11347 We often say that a recursive function `calls itself'. What we mean
11348 is that the instructions in a recursive function cause the Lisp
11349 interpreter to run a different function that has the same name and
11350 does the same job as the first, but with different arguments.
11352 It is important that the arguments differ from one instance to the
11353 next; otherwise, the process will never stop.
11355 @node Recursive Definition Parts, Recursion with list, Building Robots, Recursion
11356 @comment node-name, next, previous, up
11357 @subsection The Parts of a Recursive Definition
11358 @cindex Parts of a Recursive Definition
11359 @cindex Recursive Definition Parts
11361 A recursive function typically contains a conditional expression which
11366 A true-or-false-test that determines whether the function is called
11367 again, here called the @dfn{do-again-test}.
11370 The name of the function. When this name is called, a new instance of
11371 the function---a new robot, as it were---is created and told what to do.
11374 An expression that returns a different value each time the function is
11375 called, here called the @dfn{next-step-expression}. Consequently, the
11376 argument (or arguments) passed to the new instance of the function
11377 will be different from that passed to the previous instance. This
11378 causes the conditional expression, the @dfn{do-again-test}, to test
11379 false after the correct number of repetitions.
11382 Recursive functions can be much simpler than any other kind of
11383 function. Indeed, when people first start to use them, they often look
11384 so mysteriously simple as to be incomprehensible. Like riding a
11385 bicycle, reading a recursive function definition takes a certain knack
11386 which is hard at first but then seems simple.
11389 There are several different common recursive patterns. A very simple
11390 pattern looks like this:
11394 (defun @var{name-of-recursive-function} (@var{argument-list})
11395 "@var{documentation}@dots{}"
11396 (if @var{do-again-test}
11398 (@var{name-of-recursive-function}
11399 @var{next-step-expression})))
11403 Each time a recursive function is evaluated, a new instance of it is
11404 created and told what to do. The arguments tell the instance what to do.
11406 An argument is bound to the value of the next-step-expression. Each
11407 instance runs with a different value of the next-step-expression.
11409 The value in the next-step-expression is used in the do-again-test.
11411 The value returned by the next-step-expression is passed to the new
11412 instance of the function, which evaluates it (or some
11413 transmogrification of it) to determine whether to continue or stop.
11414 The next-step-expression is designed so that the do-again-test returns
11415 false when the function should no longer be repeated.
11417 The do-again-test is sometimes called the @dfn{stop condition},
11418 since it stops the repetitions when it tests false.
11420 @node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion
11421 @comment node-name, next, previous, up
11422 @subsection Recursion with a List
11424 The example of a @code{while} loop that printed the elements of a list
11425 of numbers can be written recursively. Here is the code, including
11426 an expression to set the value of the variable @code{animals} to a list.
11428 If you are using GNU Emacs 20 or before, this example must be copied
11429 to the @file{*scratch*} buffer and each expression must be evaluated
11430 there. Use @kbd{C-u C-x C-e} to evaluate the
11431 @code{(print-elements-recursively animals)} expression so that the
11432 results are printed in the buffer; otherwise the Lisp interpreter will
11433 try to squeeze the results into the one line of the echo area.
11435 Also, place your cursor immediately after the last closing parenthesis
11436 of the @code{print-elements-recursively} function, before the comment.
11437 Otherwise, the Lisp interpreter will try to evaluate the comment.
11439 If you are using a more recent version, you can evaluate this
11440 expression directly in Info.
11442 @findex print-elements-recursively
11445 (setq animals '(gazelle giraffe lion tiger))
11447 (defun print-elements-recursively (list)
11448 "Print each element of LIST on a line of its own.
11450 (if list ; @r{do-again-test}
11452 (print (car list)) ; @r{body}
11453 (print-elements-recursively ; @r{recursive call}
11454 (cdr list))))) ; @r{next-step-expression}
11456 (print-elements-recursively animals)
11460 The @code{print-elements-recursively} function first tests whether
11461 there is any content in the list; if there is, the function prints the
11462 first element of the list, the @sc{car} of the list. Then the
11463 function `invokes itself', but gives itself as its argument, not the
11464 whole list, but the second and subsequent elements of the list, the
11465 @sc{cdr} of the list.
11467 Put another way, if the list is not empty, the function invokes
11468 another instance of code that is similar to the initial code, but is a
11469 different thread of execution, with different arguments than the first
11472 Put in yet another way, if the list is not empty, the first robot
11473 assemblies a second robot and tells it what to do; the second robot is
11474 a different individual from the first, but is the same model.
11476 When the second evaluation occurs, the @code{if} expression is
11477 evaluated and if true, prints the first element of the list it
11478 receives as its argument (which is the second element of the original
11479 list). Then the function `calls itself' with the @sc{cdr} of the list
11480 it is invoked with, which (the second time around) is the @sc{cdr} of
11481 the @sc{cdr} of the original list.
11483 Note that although we say that the function `calls itself', what we
11484 mean is that the Lisp interpreter assembles and instructs a new
11485 instance of the program. The new instance is a clone of the first,
11486 but is a separate individual.
11488 Each time the function `invokes itself', it invokes itself on a
11489 shorter version of the original list. It creates a new instance that
11490 works on a shorter list.
11492 Eventually, the function invokes itself on an empty list. It creates
11493 a new instance whose argument is @code{nil}. The conditional expression
11494 tests the value of @code{list}. Since the value of @code{list} is
11495 @code{nil}, the @code{if} expression tests false so the then-part is
11496 not evaluated. The function as a whole then returns @code{nil}.
11499 When you evaluate @code{(print-elements-recursively animals)} in the
11500 @file{*scratch*} buffer, you see this result:
11515 @node Recursive triangle function, Recursion with cond, Recursion with list, Recursion
11516 @comment node-name, next, previous, up
11517 @subsection Recursion in Place of a Counter
11518 @findex triangle-recursively
11521 The @code{triangle} function described in a previous section can also
11522 be written recursively. It looks like this:
11526 (defun triangle-recursively (number)
11527 "Return the sum of the numbers 1 through NUMBER inclusive.
11529 (if (= number 1) ; @r{do-again-test}
11531 (+ number ; @r{else-part}
11532 (triangle-recursively ; @r{recursive call}
11533 (1- number))))) ; @r{next-step-expression}
11535 (triangle-recursively 7)
11540 You can install this function by evaluating it and then try it by
11541 evaluating @code{(triangle-recursively 7)}. (Remember to put your
11542 cursor immediately after the last parenthesis of the function
11543 definition, before the comment.) The function evaluates to 28.
11545 To understand how this function works, let's consider what happens in the
11546 various cases when the function is passed 1, 2, 3, or 4 as the value of
11550 * Recursive Example arg of 1 or 2::
11551 * Recursive Example arg of 3 or 4::
11554 @node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function
11556 @unnumberedsubsubsec An argument of 1 or 2
11559 First, what happens if the value of the argument is 1?
11561 The function has an @code{if} expression after the documentation
11562 string. It tests whether the value of @code{number} is equal to 1; if
11563 so, Emacs evaluates the then-part of the @code{if} expression, which
11564 returns the number 1 as the value of the function. (A triangle with
11565 one row has one pebble in it.)
11567 Suppose, however, that the value of the argument is 2. In this case,
11568 Emacs evaluates the else-part of the @code{if} expression.
11571 The else-part consists of an addition, the recursive call to
11572 @code{triangle-recursively} and a decrementing action; and it looks like
11576 (+ number (triangle-recursively (1- number)))
11579 When Emacs evaluates this expression, the innermost expression is
11580 evaluated first; then the other parts in sequence. Here are the steps
11584 @item Step 1 @w{ } Evaluate the innermost expression.
11586 The innermost expression is @code{(1- number)} so Emacs decrements the
11587 value of @code{number} from 2 to 1.
11589 @item Step 2 @w{ } Evaluate the @code{triangle-recursively} function.
11591 The Lisp interpreter creates an individual instance of
11592 @code{triangle-recursively}. It does not matter that this function is
11593 contained within itself. Emacs passes the result Step 1 as the
11594 argument used by this instance of the @code{triangle-recursively}
11597 In this case, Emacs evaluates @code{triangle-recursively} with an
11598 argument of 1. This means that this evaluation of
11599 @code{triangle-recursively} returns 1.
11601 @item Step 3 @w{ } Evaluate the value of @code{number}.
11603 The variable @code{number} is the second element of the list that
11604 starts with @code{+}; its value is 2.
11606 @item Step 4 @w{ } Evaluate the @code{+} expression.
11608 The @code{+} expression receives two arguments, the first
11609 from the evaluation of @code{number} (Step 3) and the second from the
11610 evaluation of @code{triangle-recursively} (Step 2).
11612 The result of the addition is the sum of 2 plus 1, and the number 3 is
11613 returned, which is correct. A triangle with two rows has three
11617 @node Recursive Example arg of 3 or 4, , Recursive Example arg of 1 or 2, Recursive triangle function
11618 @unnumberedsubsubsec An argument of 3 or 4
11620 Suppose that @code{triangle-recursively} is called with an argument of
11624 @item Step 1 @w{ } Evaluate the do-again-test.
11626 The @code{if} expression is evaluated first. This is the do-again
11627 test and returns false, so the else-part of the @code{if} expression
11628 is evaluated. (Note that in this example, the do-again-test causes
11629 the function to call itself when it tests false, not when it tests
11632 @item Step 2 @w{ } Evaluate the innermost expression of the else-part.
11634 The innermost expression of the else-part is evaluated, which decrements
11635 3 to 2. This is the next-step-expression.
11637 @item Step 3 @w{ } Evaluate the @code{triangle-recursively} function.
11639 The number 2 is passed to the @code{triangle-recursively} function.
11641 We know what happens when Emacs evaluates @code{triangle-recursively} with
11642 an argument of 2. After going through the sequence of actions described
11643 earlier, it returns a value of 3. So that is what will happen here.
11645 @item Step 4 @w{ } Evaluate the addition.
11647 3 will be passed as an argument to the addition and will be added to the
11648 number with which the function was called, which is 3.
11652 The value returned by the function as a whole will be 6.
11654 Now that we know what will happen when @code{triangle-recursively} is
11655 called with an argument of 3, it is evident what will happen if it is
11656 called with an argument of 4:
11660 In the recursive call, the evaluation of
11663 (triangle-recursively (1- 4))
11668 will return the value of evaluating
11671 (triangle-recursively 3)
11675 which is 6 and this value will be added to 4 by the addition in the
11680 The value returned by the function as a whole will be 10.
11682 Each time @code{triangle-recursively} is evaluated, it evaluates a
11683 version of itself---a different instance of itself---with a smaller
11684 argument, until the argument is small enough so that it does not
11687 Note that this particular design for a recursive function
11688 requires that operations be deferred.
11690 Before @code{(triangle-recursively 7)} can calculate its answer, it
11691 must call @code{(triangle-recursively 6)}; and before
11692 @code{(triangle-recursively 6)} can calculate its answer, it must call
11693 @code{(triangle-recursively 5)}; and so on. That is to say, the
11694 calculation that @code{(triangle-recursively 7)} makes must be
11695 deferred until @code{(triangle-recursively 6)} makes its calculation;
11696 and @code{(triangle-recursively 6)} must defer until
11697 @code{(triangle-recursively 5)} completes; and so on.
11699 If each of these instances of @code{triangle-recursively} are thought
11700 of as different robots, the first robot must wait for the second to
11701 complete its job, which must wait until the third completes, and so
11704 There is a way around this kind of waiting, which we will discuss in
11705 @ref{No Deferment, , Recursion without Deferments}.
11707 @node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion
11708 @comment node-name, next, previous, up
11709 @subsection Recursion Example Using @code{cond}
11712 The version of @code{triangle-recursively} described earlier is written
11713 with the @code{if} special form. It can also be written using another
11714 special form called @code{cond}. The name of the special form
11715 @code{cond} is an abbreviation of the word @samp{conditional}.
11717 Although the @code{cond} special form is not used as often in the
11718 Emacs Lisp sources as @code{if}, it is used often enough to justify
11722 The template for a @code{cond} expression looks like this:
11732 where the @var{body} is a series of lists.
11735 Written out more fully, the template looks like this:
11740 (@var{first-true-or-false-test} @var{first-consequent})
11741 (@var{second-true-or-false-test} @var{second-consequent})
11742 (@var{third-true-or-false-test} @var{third-consequent})
11747 When the Lisp interpreter evaluates the @code{cond} expression, it
11748 evaluates the first element (the @sc{car} or true-or-false-test) of
11749 the first expression in a series of expressions within the body of the
11752 If the true-or-false-test returns @code{nil} the rest of that
11753 expression, the consequent, is skipped and the true-or-false-test of the
11754 next expression is evaluated. When an expression is found whose
11755 true-or-false-test returns a value that is not @code{nil}, the
11756 consequent of that expression is evaluated. The consequent can be one
11757 or more expressions. If the consequent consists of more than one
11758 expression, the expressions are evaluated in sequence and the value of
11759 the last one is returned. If the expression does not have a consequent,
11760 the value of the true-or-false-test is returned.
11762 If none of the true-or-false-tests test true, the @code{cond} expression
11763 returns @code{nil}.
11766 Written using @code{cond}, the @code{triangle} function looks like this:
11770 (defun triangle-using-cond (number)
11771 (cond ((<= number 0) 0)
11774 (+ number (triangle-using-cond (1- number))))))
11779 In this example, the @code{cond} returns 0 if the number is less than or
11780 equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+
11781 number (triangle-using-cond (1- number)))} if the number is greater than
11784 @node Recursive Patterns, No Deferment, Recursion with cond, Recursion
11785 @comment node-name, next, previous, up
11786 @subsection Recursive Patterns
11787 @cindex Recursive Patterns
11789 Here are three common recursive patterns. Each involves a list.
11790 Recursion does not need to involve lists, but Lisp is designed for lists
11791 and this provides a sense of its primal capabilities.
11799 @node Every, Accumulate, Recursive Patterns, Recursive Patterns
11800 @comment node-name, next, previous, up
11801 @unnumberedsubsubsec Recursive Pattern: @emph{every}
11802 @cindex Every, type of recursive pattern
11803 @cindex Recursive pattern: every
11805 In the @code{every} recursive pattern, an action is performed on every
11809 The basic pattern is:
11813 If a list be empty, return @code{nil}.
11815 Else, act on the beginning of the list (the @sc{car} of the list)
11818 through a recursive call by the function on the rest (the
11819 @sc{cdr}) of the list,
11821 and, optionally, combine the acted-on element, using @code{cons},
11822 with the results of acting on the rest.
11831 (defun square-each (numbers-list)
11832 "Square each of a NUMBERS LIST, recursively."
11833 (if (not numbers-list) ; do-again-test
11836 (* (car numbers-list) (car numbers-list))
11837 (square-each (cdr numbers-list))))) ; next-step-expression
11841 (square-each '(1 2 3))
11848 If @code{numbers-list} is empty, do nothing. But if it has content,
11849 construct a list combining the square of the first number in the list
11850 with the result of the recursive call.
11852 (The example follows the pattern exactly: @code{nil} is returned if
11853 the numbers' list is empty. In practice, you would write the
11854 conditional so it carries out the action when the numbers' list is not
11857 The @code{print-elements-recursively} function (@pxref{Recursion with
11858 list, , Recursion with a List}) is another example of an @code{every}
11859 pattern, except in this case, rather than bring the results together
11860 using @code{cons}, we print each element of output.
11863 The @code{print-elements-recursively} function looks like this:
11867 (setq animals '(gazelle giraffe lion tiger))
11871 (defun print-elements-recursively (list)
11872 "Print each element of LIST on a line of its own.
11874 (if list ; @r{do-again-test}
11876 (print (car list)) ; @r{body}
11877 (print-elements-recursively ; @r{recursive call}
11878 (cdr list))))) ; @r{next-step-expression}
11880 (print-elements-recursively animals)
11885 The pattern for @code{print-elements-recursively} is:
11889 If the list be empty, do nothing.
11891 But if the list has at least one element,
11894 act on the beginning of the list (the @sc{car} of the list),
11896 and make a recursive call on the rest (the @sc{cdr}) of the list.
11900 @node Accumulate, Keep, Every, Recursive Patterns
11901 @comment node-name, next, previous, up
11902 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
11903 @cindex Accumulate, type of recursive pattern
11904 @cindex Recursive pattern: accumulate
11906 Another recursive pattern is called the @code{accumulate} pattern. In
11907 the @code{accumulate} recursive pattern, an action is performed on
11908 every element of a list and the result of that action is accumulated
11909 with the results of performing the action on the other elements.
11911 This is very like the `every' pattern using @code{cons}, except that
11912 @code{cons} is not used, but some other combiner.
11919 If a list be empty, return zero or some other constant.
11921 Else, act on the beginning of the list (the @sc{car} of the list),
11924 and combine that acted-on element, using @code{+} or
11925 some other combining function, with
11927 a recursive call by the function on the rest (the @sc{cdr}) of the list.
11932 Here is an example:
11936 (defun add-elements (numbers-list)
11937 "Add the elements of NUMBERS-LIST together."
11938 (if (not numbers-list)
11940 (+ (car numbers-list) (add-elements (cdr numbers-list)))))
11944 (add-elements '(1 2 3 4))
11949 @xref{Files List, , Making a List of Files}, for an example of the
11950 accumulate pattern.
11952 @node Keep, , Accumulate, Recursive Patterns
11953 @comment node-name, next, previous, up
11954 @unnumberedsubsubsec Recursive Pattern: @emph{keep}
11955 @cindex Keep, type of recursive pattern
11956 @cindex Recursive pattern: keep
11958 A third recursive pattern is called the @code{keep} pattern.
11959 In the @code{keep} recursive pattern, each element of a list is tested;
11960 the element is acted on and the results are kept only if the element
11963 Again, this is very like the `every' pattern, except the element is
11964 skipped unless it meets a criterion.
11967 The pattern has three parts:
11971 If a list be empty, return @code{nil}.
11973 Else, if the beginning of the list (the @sc{car} of the list) passes
11977 act on that element and combine it, using @code{cons} with
11979 a recursive call by the function on the rest (the @sc{cdr}) of the list.
11982 Otherwise, if the beginning of the list (the @sc{car} of the list) fails
11986 skip on that element,
11988 and, recursively call the function on the rest (the @sc{cdr}) of the list.
11993 Here is an example that uses @code{cond}:
11997 (defun keep-three-letter-words (word-list)
11998 "Keep three letter words in WORD-LIST."
12000 ;; First do-again-test: stop-condition
12001 ((not word-list) nil)
12003 ;; Second do-again-test: when to act
12004 ((eq 3 (length (symbol-name (car word-list))))
12005 ;; combine acted-on element with recursive call on shorter list
12006 (cons (car word-list) (keep-three-letter-words (cdr word-list))))
12008 ;; Third do-again-test: when to skip element;
12009 ;; recursively call shorter list with next-step expression
12010 (t (keep-three-letter-words (cdr word-list)))))
12014 (keep-three-letter-words '(one two three four five six))
12015 @result{} (one two six)
12019 It goes without saying that you need not use @code{nil} as the test for
12020 when to stop; and you can, of course, combine these patterns.
12022 @node No Deferment, No deferment solution, Recursive Patterns, Recursion
12023 @subsection Recursion without Deferments
12024 @cindex Deferment in recursion
12025 @cindex Recursion without Deferments
12027 Let's consider again what happens with the @code{triangle-recursively}
12028 function. We will find that the intermediate calculations are
12029 deferred until all can be done.
12032 Here is the function definition:
12036 (defun triangle-recursively (number)
12037 "Return the sum of the numbers 1 through NUMBER inclusive.
12039 (if (= number 1) ; @r{do-again-test}
12041 (+ number ; @r{else-part}
12042 (triangle-recursively ; @r{recursive call}
12043 (1- number))))) ; @r{next-step-expression}
12047 What happens when we call this function with a argument of 7?
12049 The first instance of the @code{triangle-recursively} function adds
12050 the number 7 to the value returned by a second instance of
12051 @code{triangle-recursively}, an instance that has been passed an
12052 argument of 6. That is to say, the first calculation is:
12055 (+ 7 (triangle-recursively 6))
12059 The first instance of @code{triangle-recursively}---you may want to
12060 think of it as a little robot---cannot complete its job. It must hand
12061 off the calculation for @code{(triangle-recursively 6)} to a second
12062 instance of the program, to a second robot. This second individual is
12063 completely different from the first one; it is, in the jargon, a
12064 `different instantiation'. Or, put another way, it is a different
12065 robot. It is the same model as the first; it calculates triangle
12066 numbers recursively; but it has a different serial number.
12068 And what does @code{(triangle-recursively 6)} return? It returns the
12069 number 6 added to the value returned by evaluating
12070 @code{triangle-recursively} with an argument of 5. Using the robot
12071 metaphor, it asks yet another robot to help it.
12077 (+ 7 6 (triangle-recursively 5))
12081 And what happens next?
12084 (+ 7 6 5 (triangle-recursively 4))
12087 Each time @code{triangle-recursively} is called, except for the last
12088 time, it creates another instance of the program---another robot---and
12089 asks it to make a calculation.
12092 Eventually, the full addition is set up and performed:
12098 This design for the function defers the calculation of the first step
12099 until the second can be done, and defers that until the third can be
12100 done, and so on. Each deferment means the computer must remember what
12101 is being waited on. This is not a problem when there are only a few
12102 steps, as in this example. But it can be a problem when there are
12105 @node No deferment solution, , No Deferment, Recursion
12106 @subsection No Deferment Solution
12107 @cindex No deferment solution
12108 @cindex Defermentless solution
12109 @cindex Solution without deferment
12111 The solution to the problem of deferred operations is to write in a
12112 manner that does not defer operations@footnote{The phrase @dfn{tail
12113 recursive} is used to describe such a process, one that uses
12114 `constant space'.}. This requires
12115 writing to a different pattern, often one that involves writing two
12116 function definitions, an `initialization' function and a `helper'
12119 The `initialization' function sets up the job; the `helper' function
12123 Here are the two function definitions for adding up numbers. They are
12124 so simple, I find them hard to understand.
12128 (defun triangle-initialization (number)
12129 "Return the sum of the numbers 1 through NUMBER inclusive.
12130 This is the `initialization' component of a two function
12131 duo that uses recursion."
12132 (triangle-recursive-helper 0 0 number))
12138 (defun triangle-recursive-helper (sum counter number)
12139 "Return SUM, using COUNTER, through NUMBER inclusive.
12140 This is the `helper' component of a two function duo
12141 that uses recursion."
12142 (if (> counter number)
12144 (triangle-recursive-helper (+ sum counter) ; @r{sum}
12145 (1+ counter) ; @r{counter}
12146 number))) ; @r{number}
12151 Install both function definitions by evaluating them, then call
12152 @code{triangle-initialization} with 2 rows:
12156 (triangle-initialization 2)
12161 The `initialization' function calls the first instance of the `helper'
12162 function with three arguments: zero, zero, and a number which is the
12163 number of rows in the triangle.
12165 The first two arguments passed to the `helper' function are
12166 initialization values. These values are changed when
12167 @code{triangle-recursive-helper} invokes new instances.@footnote{The
12168 jargon is mildly confusing: @code{triangle-recursive-helper} uses a
12169 process that is iterative in a procedure that is recursive. The
12170 process is called iterative because the computer need only record the
12171 three values, @code{sum}, @code{counter}, and @code{number}; the
12172 procedure is recursive because the function `calls itself'. On the
12173 other hand, both the process and the procedure used by
12174 @code{triangle-recursively} are called recursive. The word
12175 `recursive' has different meanings in the two contexts.}
12177 Let's see what happens when we have a triangle that has one row. (This
12178 triangle will have one pebble in it!)
12181 @code{triangle-initialization} will call its helper with
12182 the arguments @w{@code{0 0 1}}. That function will run the conditional
12183 test whether @code{(> counter number)}:
12191 and find that the result is false, so it will invoke
12192 the else-part of the @code{if} clause:
12196 (triangle-recursive-helper
12197 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
12198 (1+ counter) ; @r{increment counter} @result{} @r{counter}
12199 number) ; @r{number stays the same}
12205 which will first compute:
12209 (triangle-recursive-helper (+ 0 0) ; @r{sum}
12210 (1+ 0) ; @r{counter}
12214 (triangle-recursive-helper 0 1 1)
12218 Again, @code{(> counter number)} will be false, so again, the Lisp
12219 interpreter will evaluate @code{triangle-recursive-helper}, creating a
12220 new instance with new arguments.
12223 This new instance will be;
12227 (triangle-recursive-helper
12228 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
12229 (1+ counter) ; @r{increment counter} @result{} @r{counter}
12230 number) ; @r{number stays the same}
12234 (triangle-recursive-helper 1 2 1)
12238 In this case, the @code{(> counter number)} test will be true! So the
12239 instance will return the value of the sum, which will be 1, as
12242 Now, let's pass @code{triangle-initialization} an argument
12243 of 2, to find out how many pebbles there are in a triangle with two rows.
12245 That function calls @code{(triangle-recursive-helper 0 0 2)}.
12248 In stages, the instances called will be:
12252 @r{sum counter number}
12253 (triangle-recursive-helper 0 1 2)
12255 (triangle-recursive-helper 1 2 2)
12257 (triangle-recursive-helper 3 3 2)
12261 When the last instance is called, the @code{(> counter number)} test
12262 will be true, so the instance will return the value of @code{sum},
12265 This kind of pattern helps when you are writing functions that can use
12266 many resources in a computer.
12269 @node Looping exercise, , Recursion, Loops & Recursion
12270 @section Looping Exercise
12274 Write a function similar to @code{triangle} in which each row has a
12275 value which is the square of the row number. Use a @code{while} loop.
12278 Write a function similar to @code{triangle} that multiplies instead of
12282 Rewrite these two functions recursively. Rewrite these functions
12285 @c comma in printed title causes problem in Info cross reference
12287 Write a function for Texinfo mode that creates an index entry at the
12288 beginning of a paragraph for every @samp{@@dfn} within the paragraph.
12289 (In a Texinfo file, @samp{@@dfn} marks a definition. This book is
12290 written in Texinfo.)
12292 Many of the functions you will need are described in two of the
12293 previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing
12294 Text}, and @ref{Yanking, , Yanking Text Back}. If you use
12295 @code{forward-paragraph} to put the index entry at the beginning of
12296 the paragraph, you will have to use @w{@kbd{C-h f}}
12297 (@code{describe-function}) to find out how to make the command go
12300 For more information, see
12302 @ref{Indicating, , Indicating Definitions, texinfo}.
12305 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to
12306 a Texinfo manual in the current directory. Or, if you are on the
12308 @uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
12311 ``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU
12312 Documentation Format}.
12316 @node Regexp Search, Counting Words, Loops & Recursion, Top
12317 @comment node-name, next, previous, up
12318 @chapter Regular Expression Searches
12319 @cindex Searches, illustrating
12320 @cindex Regular expression searches
12321 @cindex Patterns, searching for
12322 @cindex Motion by sentence and paragraph
12323 @cindex Sentences, movement by
12324 @cindex Paragraphs, movement by
12326 Regular expression searches are used extensively in GNU Emacs. The
12327 two functions, @code{forward-sentence} and @code{forward-paragraph},
12328 illustrate these searches well. They use regular expressions to find
12329 where to move point. The phrase `regular expression' is often written
12332 Regular expression searches are described in @ref{Regexp Search, ,
12333 Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in
12334 @ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference
12335 Manual}. In writing this chapter, I am presuming that you have at
12336 least a mild acquaintance with them. The major point to remember is
12337 that regular expressions permit you to search for patterns as well as
12338 for literal strings of characters. For example, the code in
12339 @code{forward-sentence} searches for the pattern of possible
12340 characters that could mark the end of a sentence, and moves point to
12343 Before looking at the code for the @code{forward-sentence} function, it
12344 is worth considering what the pattern that marks the end of a sentence
12345 must be. The pattern is discussed in the next section; following that
12346 is a description of the regular expression search function,
12347 @code{re-search-forward}. The @code{forward-sentence} function
12348 is described in the section following. Finally, the
12349 @code{forward-paragraph} function is described in the last section of
12350 this chapter. @code{forward-paragraph} is a complex function that
12351 introduces several new features.
12355 * re-search-forward::
12356 * forward-sentence::
12357 * forward-paragraph::
12360 * re-search Exercises::
12363 @node sentence-end, re-search-forward, Regexp Search, Regexp Search
12364 @comment node-name, next, previous, up
12365 @section The Regular Expression for @code{sentence-end}
12366 @findex sentence-end
12368 The symbol @code{sentence-end} is bound to the pattern that marks the
12369 end of a sentence. What should this regular expression be?
12371 Clearly, a sentence may be ended by a period, a question mark, or an
12372 exclamation mark. Indeed, only clauses that end with one of those three
12373 characters should be considered the end of a sentence. This means that
12374 the pattern should include the character set:
12380 However, we do not want @code{forward-sentence} merely to jump to a
12381 period, a question mark, or an exclamation mark, because such a character
12382 might be used in the middle of a sentence. A period, for example, is
12383 used after abbreviations. So other information is needed.
12385 According to convention, you type two spaces after every sentence, but
12386 only one space after a period, a question mark, or an exclamation mark in
12387 the body of a sentence. So a period, a question mark, or an exclamation
12388 mark followed by two spaces is a good indicator of an end of sentence.
12389 However, in a file, the two spaces may instead be a tab or the end of a
12390 line. This means that the regular expression should include these three
12391 items as alternatives.
12394 This group of alternatives will look like this:
12405 Here, @samp{$} indicates the end of the line, and I have pointed out
12406 where the tab and two spaces are inserted in the expression. Both are
12407 inserted by putting the actual characters into the expression.
12409 Two backslashes, @samp{\\}, are required before the parentheses and
12410 vertical bars: the first backslash quotes the following backslash in
12411 Emacs; and the second indicates that the following character, the
12412 parenthesis or the vertical bar, is special.
12415 Also, a sentence may be followed by one or more carriage returns, like
12426 Like tabs and spaces, a carriage return is inserted into a regular
12427 expression by inserting it literally. The asterisk indicates that the
12428 @key{RET} is repeated zero or more times.
12430 But a sentence end does not consist only of a period, a question mark or
12431 an exclamation mark followed by appropriate space: a closing quotation
12432 mark or a closing brace of some kind may precede the space. Indeed more
12433 than one such mark or brace may precede the space. These require a
12434 expression that looks like this:
12440 In this expression, the first @samp{]} is the first character in the
12441 expression; the second character is @samp{"}, which is preceded by a
12442 @samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last
12443 three characters are @samp{'}, @samp{)}, and @samp{@}}.
12445 All this suggests what the regular expression pattern for matching the
12446 end of a sentence should be; and, indeed, if we evaluate
12447 @code{sentence-end} we find that it returns the following value:
12452 @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[
12458 (Well, not in GNU Emacs 22; that is because of an effort to make the
12459 process simpler. When its value is @code{nil}, then use the value
12460 defined by the function @code{sentence-end}, and that returns a value
12461 constructed from the variables @code{sentence-end-base},
12462 @code{sentence-end-double-space}, @code{sentence-end-without-period},
12463 and @code{sentence-end-without-space}. The critical variable is
12464 @code{sentence-end-base}; its global value is similar to the one
12465 described above but it also contains two additional quotation marks.
12466 These have differing degrees of curliness. The
12467 @code{sentence-end-without-period} variable, when true, tells Emacs
12468 that a sentence may end without a period, such as text in Thai.)
12472 (Note that here the @key{TAB}, two spaces, and @key{RET} are shown
12473 literally in the pattern.)
12475 This regular expression can be deciphered as follows:
12479 The first part of the pattern is the three characters, a period, a question
12480 mark and an exclamation mark, within square brackets. The pattern must
12481 begin with one or other of these characters.
12484 The second part of the pattern is the group of closing braces and
12485 quotation marks, which can appear zero or more times. These may follow
12486 the period, question mark or exclamation mark. In a regular expression,
12487 the backslash, @samp{\}, followed by the double quotation mark,
12488 @samp{"}, indicates the class of string-quote characters. Usually, the
12489 double quotation mark is the only character in this class. The
12490 asterisk, @samp{*}, indicates that the items in the previous group (the
12491 group surrounded by square brackets, @samp{[]}) may be repeated zero or
12494 @item \\($\\| \\| \\)
12495 The third part of the pattern is one or other of: either the end of a
12496 line, or two blank spaces, or a tab. The double back-slashes are used
12497 to prevent Emacs from reading the parentheses and vertical bars as part
12498 of the search pattern; the parentheses are used to mark the group and
12499 the vertical bars are used to indicated that the patterns to either side
12500 of them are alternatives. The dollar sign is used to indicate the end
12501 of a line and both the two spaces and the tab are each inserted as is to
12502 indicate what they are.
12505 Finally, the last part of the pattern indicates that the end of the line
12506 or the whitespace following the period, question mark or exclamation
12507 mark may, but need not, be followed by one or more carriage returns. In
12508 the pattern, the carriage return is inserted as an actual carriage
12509 return between square brackets but here it is shown as @key{RET}.
12513 @node re-search-forward, forward-sentence, sentence-end, Regexp Search
12514 @comment node-name, next, previous, up
12515 @section The @code{re-search-forward} Function
12516 @findex re-search-forward
12518 The @code{re-search-forward} function is very like the
12519 @code{search-forward} function. (@xref{search-forward, , The
12520 @code{search-forward} Function}.)
12522 @code{re-search-forward} searches for a regular expression. If the
12523 search is successful, it leaves point immediately after the last
12524 character in the target. If the search is backwards, it leaves point
12525 just before the first character in the target. You may tell
12526 @code{re-search-forward} to return @code{t} for true. (Moving point
12527 is therefore a `side effect'.)
12529 Like @code{search-forward}, the @code{re-search-forward} function takes
12534 The first argument is the regular expression that the function searches
12535 for. The regular expression will be a string between quotations marks.
12538 The optional second argument limits how far the function will search; it is a
12539 bound, which is specified as a position in the buffer.
12542 The optional third argument specifies how the function responds to
12543 failure: @code{nil} as the third argument causes the function to
12544 signal an error (and print a message) when the search fails; any other
12545 value causes it to return @code{nil} if the search fails and @code{t}
12546 if the search succeeds.
12549 The optional fourth argument is the repeat count. A negative repeat
12550 count causes @code{re-search-forward} to search backwards.
12554 The template for @code{re-search-forward} looks like this:
12558 (re-search-forward "@var{regular-expression}"
12559 @var{limit-of-search}
12560 @var{what-to-do-if-search-fails}
12561 @var{repeat-count})
12565 The second, third, and fourth arguments are optional. However, if you
12566 want to pass a value to either or both of the last two arguments, you
12567 must also pass a value to all the preceding arguments. Otherwise, the
12568 Lisp interpreter will mistake which argument you are passing the value
12572 In the @code{forward-sentence} function, the regular expression will be
12573 the value of the variable @code{sentence-end}. In simple form, that is:
12577 "[.?!][]\"')@}]*\\($\\| \\| \\)[
12583 The limit of the search will be the end of the paragraph (since a
12584 sentence cannot go beyond a paragraph). If the search fails, the
12585 function will return @code{nil}; and the repeat count will be provided
12586 by the argument to the @code{forward-sentence} function.
12588 @node forward-sentence, forward-paragraph, re-search-forward, Regexp Search
12589 @comment node-name, next, previous, up
12590 @section @code{forward-sentence}
12591 @findex forward-sentence
12593 The command to move the cursor forward a sentence is a straightforward
12594 illustration of how to use regular expression searches in Emacs Lisp.
12595 Indeed, the function looks longer and more complicated than it is; this
12596 is because the function is designed to go backwards as well as forwards;
12597 and, optionally, over more than one sentence. The function is usually
12598 bound to the key command @kbd{M-e}.
12601 * Complete forward-sentence::
12602 * fwd-sentence while loops::
12603 * fwd-sentence re-search::
12606 @node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence
12608 @unnumberedsubsec Complete @code{forward-sentence} function definition
12612 Here is the code for @code{forward-sentence}:
12617 (defun forward-sentence (&optional arg)
12618 "Move forward to next `sentence-end'. With argument, repeat.
12619 With negative argument, move backward repeatedly to `sentence-beginning'.
12621 The variable `sentence-end' is a regular expression that matches ends of
12622 sentences. Also, every paragraph boundary terminates sentences as well."
12626 (or arg (setq arg 1))
12627 (let ((opoint (point))
12628 (sentence-end (sentence-end)))
12630 (let ((pos (point))
12631 (par-beg (save-excursion (start-of-paragraph-text) (point))))
12632 (if (and (re-search-backward sentence-end par-beg t)
12633 (or (< (match-end 0) pos)
12634 (re-search-backward sentence-end par-beg t)))
12635 (goto-char (match-end 0))
12636 (goto-char par-beg)))
12637 (setq arg (1+ arg)))
12641 (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
12642 (if (re-search-forward sentence-end par-end t)
12643 (skip-chars-backward " \t\n")
12644 (goto-char par-end)))
12645 (setq arg (1- arg)))
12646 (constrain-to-field nil opoint t)))
12654 (defun forward-sentence (&optional arg)
12655 "Move forward to next sentence-end. With argument, repeat.
12656 With negative argument, move backward repeatedly to sentence-beginning.
12657 Sentence ends are identified by the value of sentence-end
12658 treated as a regular expression. Also, every paragraph boundary
12659 terminates sentences as well."
12663 (or arg (setq arg 1))
12666 (save-excursion (start-of-paragraph-text) (point))))
12667 (if (re-search-backward
12668 (concat sentence-end "[^ \t\n]") par-beg t)
12669 (goto-char (1- (match-end 0)))
12670 (goto-char par-beg)))
12671 (setq arg (1+ arg)))
12674 (save-excursion (end-of-paragraph-text) (point))))
12675 (if (re-search-forward sentence-end par-end t)
12676 (skip-chars-backward " \t\n")
12677 (goto-char par-end)))
12678 (setq arg (1- arg))))
12683 The function looks long at first sight and it is best to look at its
12684 skeleton first, and then its muscle. The way to see the skeleton is to
12685 look at the expressions that start in the left-most columns:
12689 (defun forward-sentence (&optional arg)
12690 "@var{documentation}@dots{}"
12692 (or arg (setq arg 1))
12693 (let ((opoint (point)) (sentence-end (sentence-end)))
12695 (let ((pos (point))
12696 (par-beg (save-excursion (start-of-paragraph-text) (point))))
12697 @var{rest-of-body-of-while-loop-when-going-backwards}
12699 (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
12700 @var{rest-of-body-of-while-loop-when-going-forwards}
12701 @var{handle-forms-and-equivalent}
12705 This looks much simpler! The function definition consists of
12706 documentation, an @code{interactive} expression, an @code{or}
12707 expression, a @code{let} expression, and @code{while} loops.
12709 Let's look at each of these parts in turn.
12711 We note that the documentation is thorough and understandable.
12713 The function has an @code{interactive "p"} declaration. This means
12714 that the processed prefix argument, if any, is passed to the
12715 function as its argument. (This will be a number.) If the function
12716 is not passed an argument (it is optional) then the argument
12717 @code{arg} will be bound to 1.
12719 When @code{forward-sentence} is called non-interactively without an
12720 argument, @code{arg} is bound to @code{nil}. The @code{or} expression
12721 handles this. What it does is either leave the value of @code{arg} as
12722 it is, but only if @code{arg} is bound to a value; or it sets the
12723 value of @code{arg} to 1, in the case when @code{arg} is bound to
12726 Next is a @code{let}. That specifies the values of two local
12727 variables, @code{point} and @code{sentence-end}. The local value of
12728 point, from before the search, is used in the
12729 @code{constrain-to-field} function which handles forms and
12730 equivalents. The @code{sentence-end} variable is set by the
12731 @code{sentence-end} function.
12733 @node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence
12734 @unnumberedsubsec The @code{while} loops
12736 Two @code{while} loops follow. The first @code{while} has a
12737 true-or-false-test that tests true if the prefix argument for
12738 @code{forward-sentence} is a negative number. This is for going
12739 backwards. The body of this loop is similar to the body of the second
12740 @code{while} clause, but it is not exactly the same. We will skip
12741 this @code{while} loop and concentrate on the second @code{while}
12745 The second @code{while} loop is for moving point forward. Its skeleton
12750 (while (> arg 0) ; @r{true-or-false-test}
12752 (if (@var{true-or-false-test})
12755 (setq arg (1- arg)))) ; @code{while} @r{loop decrementer}
12759 The @code{while} loop is of the decrementing kind.
12760 (@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It
12761 has a true-or-false-test that tests true so long as the counter (in
12762 this case, the variable @code{arg}) is greater than zero; and it has a
12763 decrementer that subtracts 1 from the value of the counter every time
12766 If no prefix argument is given to @code{forward-sentence}, which is
12767 the most common way the command is used, this @code{while} loop will
12768 run once, since the value of @code{arg} will be 1.
12770 The body of the @code{while} loop consists of a @code{let} expression,
12771 which creates and binds a local variable, and has, as its body, an
12772 @code{if} expression.
12775 The body of the @code{while} loop looks like this:
12780 (save-excursion (end-of-paragraph-text) (point))))
12781 (if (re-search-forward sentence-end par-end t)
12782 (skip-chars-backward " \t\n")
12783 (goto-char par-end)))
12787 The @code{let} expression creates and binds the local variable
12788 @code{par-end}. As we shall see, this local variable is designed to
12789 provide a bound or limit to the regular expression search. If the
12790 search fails to find a proper sentence ending in the paragraph, it will
12791 stop on reaching the end of the paragraph.
12793 But first, let us examine how @code{par-end} is bound to the value of
12794 the end of the paragraph. What happens is that the @code{let} sets the
12795 value of @code{par-end} to the value returned when the Lisp interpreter
12796 evaluates the expression
12800 (save-excursion (end-of-paragraph-text) (point))
12805 In this expression, @code{(end-of-paragraph-text)} moves point to the
12806 end of the paragraph, @code{(point)} returns the value of point, and then
12807 @code{save-excursion} restores point to its original position. Thus,
12808 the @code{let} binds @code{par-end} to the value returned by the
12809 @code{save-excursion} expression, which is the position of the end of
12810 the paragraph. (The @code{(end-of-paragraph-text)} function uses
12811 @code{forward-paragraph}, which we will discuss shortly.)
12814 Emacs next evaluates the body of the @code{let}, which is an @code{if}
12815 expression that looks like this:
12819 (if (re-search-forward sentence-end par-end t) ; @r{if-part}
12820 (skip-chars-backward " \t\n") ; @r{then-part}
12821 (goto-char par-end))) ; @r{else-part}
12825 The @code{if} tests whether its first argument is true and if so,
12826 evaluates its then-part; otherwise, the Emacs Lisp interpreter
12827 evaluates the else-part. The true-or-false-test of the @code{if}
12828 expression is the regular expression search.
12830 It may seem odd to have what looks like the `real work' of
12831 the @code{forward-sentence} function buried here, but this is a common
12832 way this kind of operation is carried out in Lisp.
12834 @node fwd-sentence re-search, , fwd-sentence while loops, forward-sentence
12835 @unnumberedsubsec The regular expression search
12837 The @code{re-search-forward} function searches for the end of the
12838 sentence, that is, for the pattern defined by the @code{sentence-end}
12839 regular expression. If the pattern is found---if the end of the sentence is
12840 found---then the @code{re-search-forward} function does two things:
12844 The @code{re-search-forward} function carries out a side effect, which
12845 is to move point to the end of the occurrence found.
12848 The @code{re-search-forward} function returns a value of true. This is
12849 the value received by the @code{if}, and means that the search was
12854 The side effect, the movement of point, is completed before the
12855 @code{if} function is handed the value returned by the successful
12856 conclusion of the search.
12858 When the @code{if} function receives the value of true from a successful
12859 call to @code{re-search-forward}, the @code{if} evaluates the then-part,
12860 which is the expression @code{(skip-chars-backward " \t\n")}. This
12861 expression moves backwards over any blank spaces, tabs or carriage
12862 returns until a printed character is found and then leaves point after
12863 the character. Since point has already been moved to the end of the
12864 pattern that marks the end of the sentence, this action leaves point
12865 right after the closing printed character of the sentence, which is
12868 On the other hand, if the @code{re-search-forward} function fails to
12869 find a pattern marking the end of the sentence, the function returns
12870 false. The false then causes the @code{if} to evaluate its third
12871 argument, which is @code{(goto-char par-end)}: it moves point to the
12872 end of the paragraph.
12874 (And if the text is in a form or equivalent, and point may not move
12875 fully, then the @code{constrain-to-field} function comes into play.)
12877 Regular expression searches are exceptionally useful and the pattern
12878 illustrated by @code{re-search-forward}, in which the search is the
12879 test of an @code{if} expression, is handy. You will see or write code
12880 incorporating this pattern often.
12882 @node forward-paragraph, etags, forward-sentence, Regexp Search
12883 @comment node-name, next, previous, up
12884 @section @code{forward-paragraph}: a Goldmine of Functions
12885 @findex forward-paragraph
12889 (defun forward-paragraph (&optional arg)
12890 "Move forward to end of paragraph.
12891 With argument ARG, do it ARG times;
12892 a negative argument ARG = -N means move backward N paragraphs.
12894 A line which `paragraph-start' matches either separates paragraphs
12895 \(if `paragraph-separate' matches it also) or is the first line of a paragraph.
12896 A paragraph end is the beginning of a line which is not part of the paragraph
12897 to which the end of the previous line belongs, or the end of the buffer.
12898 Returns the count of paragraphs left to move."
12900 (or arg (setq arg 1))
12901 (let* ((opoint (point))
12902 (fill-prefix-regexp
12903 (and fill-prefix (not (equal fill-prefix ""))
12904 (not paragraph-ignore-fill-prefix)
12905 (regexp-quote fill-prefix)))
12906 ;; Remove ^ from paragraph-start and paragraph-sep if they are there.
12907 ;; These regexps shouldn't be anchored, because we look for them
12908 ;; starting at the left-margin. This allows paragraph commands to
12909 ;; work normally with indented text.
12910 ;; This hack will not find problem cases like "whatever\\|^something".
12911 (parstart (if (and (not (equal "" paragraph-start))
12912 (equal ?^ (aref paragraph-start 0)))
12913 (substring paragraph-start 1)
12915 (parsep (if (and (not (equal "" paragraph-separate))
12916 (equal ?^ (aref paragraph-separate 0)))
12917 (substring paragraph-separate 1)
12918 paragraph-separate))
12920 (if fill-prefix-regexp
12921 (concat parsep "\\|"
12922 fill-prefix-regexp "[ \t]*$")
12924 ;; This is used for searching.
12925 (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)"))
12927 (while (and (< arg 0) (not (bobp)))
12928 (if (and (not (looking-at parsep))
12929 (re-search-backward "^\n" (max (1- (point)) (point-min)) t)
12930 (looking-at parsep))
12931 (setq arg (1+ arg))
12932 (setq start (point))
12933 ;; Move back over paragraph-separating lines.
12934 (forward-char -1) (beginning-of-line)
12935 (while (and (not (bobp))
12936 (progn (move-to-left-margin)
12937 (looking-at parsep)))
12941 (setq arg (1+ arg))
12942 ;; Go to end of the previous (non-separating) line.
12944 ;; Search back for line that starts or separates paragraphs.
12945 (if (if fill-prefix-regexp
12946 ;; There is a fill prefix; it overrides parstart.
12947 (let (multiple-lines)
12948 (while (and (progn (beginning-of-line) (not (bobp)))
12949 (progn (move-to-left-margin)
12950 (not (looking-at parsep)))
12951 (looking-at fill-prefix-regexp))
12952 (unless (= (point) start)
12953 (setq multiple-lines t))
12955 (move-to-left-margin)
12956 ;; This deleted code caused a long hanging-indent line
12957 ;; not to be filled together with the following lines.
12958 ;; ;; Don't move back over a line before the paragraph
12959 ;; ;; which doesn't start with fill-prefix
12960 ;; ;; unless that is the only line we've moved over.
12961 ;; (and (not (looking-at fill-prefix-regexp))
12963 ;; (forward-line 1))
12965 (while (and (re-search-backward sp-parstart nil 1)
12966 (setq found-start t)
12967 ;; Found a candidate, but need to check if it is a
12969 (progn (setq start (point))
12970 (move-to-left-margin)
12971 (not (looking-at parsep)))
12972 (not (and (looking-at parstart)
12973 (or (not use-hard-newlines)
12976 (1- start) 'hard)))))
12977 (setq found-start nil)
12982 ;; Move forward over paragraph separators.
12983 ;; We know this cannot reach the place we started
12984 ;; because we know we moved back over a non-separator.
12985 (while (and (not (eobp))
12986 (progn (move-to-left-margin)
12987 (looking-at parsep)))
12989 ;; If line before paragraph is just margin, back up to there.
12991 (if (> (current-column) (current-left-margin))
12993 (skip-chars-backward " \t")
12995 (forward-line 1))))
12996 ;; No starter or separator line => use buffer beg.
12997 (goto-char (point-min))))))
12999 (while (and (> arg 0) (not (eobp)))
13000 ;; Move forward over separator lines...
13001 (while (and (not (eobp))
13002 (progn (move-to-left-margin) (not (eobp)))
13003 (looking-at parsep))
13005 (unless (eobp) (setq arg (1- arg)))
13006 ;; ... and one more line.
13008 (if fill-prefix-regexp
13009 ;; There is a fill prefix; it overrides parstart.
13010 (while (and (not (eobp))
13011 (progn (move-to-left-margin) (not (eobp)))
13012 (not (looking-at parsep))
13013 (looking-at fill-prefix-regexp))
13015 (while (and (re-search-forward sp-parstart nil 1)
13016 (progn (setq start (match-beginning 0))
13019 (progn (move-to-left-margin)
13020 (not (looking-at parsep)))
13021 (or (not (looking-at parstart))
13022 (and use-hard-newlines
13023 (not (get-text-property (1- start) 'hard)))))
13025 (if (< (point) (point-max))
13026 (goto-char start))))
13027 (constrain-to-field nil opoint t)
13028 ;; Return the number of steps that could not be done.
13032 The @code{forward-paragraph} function moves point forward to the end
13033 of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a
13034 number of functions that are important in themselves, including
13035 @code{let*}, @code{match-beginning}, and @code{looking-at}.
13037 The function definition for @code{forward-paragraph} is considerably
13038 longer than the function definition for @code{forward-sentence}
13039 because it works with a paragraph, each line of which may begin with a
13042 A fill prefix consists of a string of characters that are repeated at
13043 the beginning of each line. For example, in Lisp code, it is a
13044 convention to start each line of a paragraph-long comment with
13045 @samp{;;; }. In Text mode, four blank spaces make up another common
13046 fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , ,
13047 emacs, The GNU Emacs Manual}, for more information about fill
13050 The existence of a fill prefix means that in addition to being able to
13051 find the end of a paragraph whose lines begin on the left-most
13052 column, the @code{forward-paragraph} function must be able to find the
13053 end of a paragraph when all or many of the lines in the buffer begin
13054 with the fill prefix.
13056 Moreover, it is sometimes practical to ignore a fill prefix that
13057 exists, especially when blank lines separate paragraphs.
13058 This is an added complication.
13061 * forward-paragraph in brief::
13066 @node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph
13068 @unnumberedsubsec Shortened @code{forward-paragraph} function definition
13071 Rather than print all of the @code{forward-paragraph} function, we
13072 will only print parts of it. Read without preparation, the function
13076 In outline, the function looks like this:
13080 (defun forward-paragraph (&optional arg)
13081 "@var{documentation}@dots{}"
13083 (or arg (setq arg 1))
13086 (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code}
13088 (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code}
13093 The first parts of the function are routine: the function's argument
13094 list consists of one optional argument. Documentation follows.
13096 The lower case @samp{p} in the @code{interactive} declaration means
13097 that the processed prefix argument, if any, is passed to the function.
13098 This will be a number, and is the repeat count of how many paragraphs
13099 point will move. The @code{or} expression in the next line handles
13100 the common case when no argument is passed to the function, which occurs
13101 if the function is called from other code rather than interactively.
13102 This case was described earlier. (@xref{forward-sentence, The
13103 @code{forward-sentence} function}.) Now we reach the end of the
13104 familiar part of this function.
13106 @node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph
13107 @unnumberedsubsec The @code{let*} expression
13109 The next line of the @code{forward-paragraph} function begins a
13110 @code{let*} expression. This is a different than @code{let}. The
13111 symbol is @code{let*} not @code{let}.
13113 The @code{let*} special form is like @code{let} except that Emacs sets
13114 each variable in sequence, one after another, and variables in the
13115 latter part of the varlist can make use of the values to which Emacs
13116 set variables in the earlier part of the varlist.
13119 ( refappend save-excursion, , code save-excursion in code append-to-buffer .)
13122 (@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.)
13124 In the @code{let*} expression in this function, Emacs binds a total of
13125 seven variables: @code{opoint}, @code{fill-prefix-regexp},
13126 @code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and
13127 @code{found-start}.
13129 The variable @code{parsep} appears twice, first, to remove instances
13130 of @samp{^}, and second, to handle fill prefixes.
13132 The variable @code{opoint} is just the value of @code{point}. As you
13133 can guess, it is used in a @code{constrain-to-field} expression, just
13134 as in @code{forward-sentence}.
13136 The variable @code{fill-prefix-regexp} is set to the value returned by
13137 evaluating the following list:
13142 (not (equal fill-prefix ""))
13143 (not paragraph-ignore-fill-prefix)
13144 (regexp-quote fill-prefix))
13149 This is an expression whose first element is the @code{and} special form.
13151 As we learned earlier (@pxref{kill-new function, , The @code{kill-new}
13152 function}), the @code{and} special form evaluates each of its
13153 arguments until one of the arguments returns a value of @code{nil}, in
13154 which case the @code{and} expression returns @code{nil}; however, if
13155 none of the arguments returns a value of @code{nil}, the value
13156 resulting from evaluating the last argument is returned. (Since such
13157 a value is not @code{nil}, it is considered true in Lisp.) In other
13158 words, an @code{and} expression returns a true value only if all its
13159 arguments are true.
13162 In this case, the variable @code{fill-prefix-regexp} is bound to a
13163 non-@code{nil} value only if the following four expressions produce a
13164 true (i.e., a non-@code{nil}) value when they are evaluated; otherwise,
13165 @code{fill-prefix-regexp} is bound to @code{nil}.
13169 When this variable is evaluated, the value of the fill prefix, if any,
13170 is returned. If there is no fill prefix, this variable returns
13173 @item (not (equal fill-prefix "")
13174 This expression checks whether an existing fill prefix is an empty
13175 string, that is, a string with no characters in it. An empty string is
13176 not a useful fill prefix.
13178 @item (not paragraph-ignore-fill-prefix)
13179 This expression returns @code{nil} if the variable
13180 @code{paragraph-ignore-fill-prefix} has been turned on by being set to a
13181 true value such as @code{t}.
13183 @item (regexp-quote fill-prefix)
13184 This is the last argument to the @code{and} special form. If all the
13185 arguments to the @code{and} are true, the value resulting from
13186 evaluating this expression will be returned by the @code{and} expression
13187 and bound to the variable @code{fill-prefix-regexp},
13190 @findex regexp-quote
13192 The result of evaluating this @code{and} expression successfully is that
13193 @code{fill-prefix-regexp} will be bound to the value of
13194 @code{fill-prefix} as modified by the @code{regexp-quote} function.
13195 What @code{regexp-quote} does is read a string and return a regular
13196 expression that will exactly match the string and match nothing else.
13197 This means that @code{fill-prefix-regexp} will be set to a value that
13198 will exactly match the fill prefix if the fill prefix exists.
13199 Otherwise, the variable will be set to @code{nil}.
13201 The next two local variables in the @code{let*} expression are
13202 designed to remove instances of @samp{^} from @code{parstart} and
13203 @code{parsep}, the local variables indicate the paragraph start and
13204 the paragraph separator. The next expression sets @code{parsep}
13205 again. That is to handle fill prefixes.
13207 This is the setting that requires the definition call @code{let*}
13208 rather than @code{let}. The true-or-false-test for the @code{if}
13209 depends on whether the variable @code{fill-prefix-regexp} evaluates to
13210 @code{nil} or some other value.
13212 If @code{fill-prefix-regexp} does not have a value, Emacs evaluates
13213 the else-part of the @code{if} expression and binds @code{parsep} to
13214 its local value. (@code{parsep} is a regular expression that matches
13215 what separates paragraphs.)
13217 But if @code{fill-prefix-regexp} does have a value, Emacs evaluates
13218 the then-part of the @code{if} expression and binds @code{parsep} to a
13219 regular expression that includes the @code{fill-prefix-regexp} as part
13222 Specifically, @code{parsep} is set to the original value of the
13223 paragraph separate regular expression concatenated with an alternative
13224 expression that consists of the @code{fill-prefix-regexp} followed by
13225 optional whitespace to the end of the line. The whitespace is defined
13226 by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the
13227 regexp as an alternative to @code{parsep}.
13229 According to a comment in the code, the next local variable,
13230 @code{sp-parstart}, is used for searching, and then the final two,
13231 @code{start} and @code{found-start}, are set to @code{nil}.
13233 Now we get into the body of the @code{let*}. The first part of the body
13234 of the @code{let*} deals with the case when the function is given a
13235 negative argument and is therefore moving backwards. We will skip this
13238 @node fwd-para while, , fwd-para let, forward-paragraph
13239 @unnumberedsubsec The forward motion @code{while} loop
13241 The second part of the body of the @code{let*} deals with forward
13242 motion. It is a @code{while} loop that repeats itself so long as the
13243 value of @code{arg} is greater than zero. In the most common use of
13244 the function, the value of the argument is 1, so the body of the
13245 @code{while} loop is evaluated exactly once, and the cursor moves
13246 forward one paragraph.
13249 (while (and (> arg 0) (not (eobp)))
13251 ;; Move forward over separator lines...
13252 (while (and (not (eobp))
13253 (progn (move-to-left-margin) (not (eobp)))
13254 (looking-at parsep))
13256 (unless (eobp) (setq arg (1- arg)))
13257 ;; ... and one more line.
13260 (if fill-prefix-regexp
13261 ;; There is a fill prefix; it overrides parstart.
13262 (while (and (not (eobp))
13263 (progn (move-to-left-margin) (not (eobp)))
13264 (not (looking-at parsep))
13265 (looking-at fill-prefix-regexp))
13268 (while (and (re-search-forward sp-parstart nil 1)
13269 (progn (setq start (match-beginning 0))
13272 (progn (move-to-left-margin)
13273 (not (looking-at parsep)))
13274 (or (not (looking-at parstart))
13275 (and use-hard-newlines
13276 (not (get-text-property (1- start) 'hard)))))
13279 (if (< (point) (point-max))
13280 (goto-char start))))
13283 This part handles three situations: when point is between paragraphs,
13284 when there is a fill prefix and when there is no fill prefix.
13287 The @code{while} loop looks like this:
13291 ;; @r{going forwards and not at the end of the buffer}
13292 (while (and (> arg 0) (not (eobp)))
13294 ;; @r{between paragraphs}
13295 ;; Move forward over separator lines...
13296 (while (and (not (eobp))
13297 (progn (move-to-left-margin) (not (eobp)))
13298 (looking-at parsep))
13300 ;; @r{This decrements the loop}
13301 (unless (eobp) (setq arg (1- arg)))
13302 ;; ... and one more line.
13307 (if fill-prefix-regexp
13308 ;; There is a fill prefix; it overrides parstart;
13309 ;; we go forward line by line
13310 (while (and (not (eobp))
13311 (progn (move-to-left-margin) (not (eobp)))
13312 (not (looking-at parsep))
13313 (looking-at fill-prefix-regexp))
13318 ;; There is no fill prefix;
13319 ;; we go forward character by character
13320 (while (and (re-search-forward sp-parstart nil 1)
13321 (progn (setq start (match-beginning 0))
13324 (progn (move-to-left-margin)
13325 (not (looking-at parsep)))
13326 (or (not (looking-at parstart))
13327 (and use-hard-newlines
13328 (not (get-text-property (1- start) 'hard)))))
13333 ;; and if there is no fill prefix and if we are not at the end,
13334 ;; go to whatever was found in the regular expression search
13336 (if (< (point) (point-max))
13337 (goto-char start))))
13342 We can see that this is a decrementing counter @code{while} loop,
13343 using the expression @code{(setq arg (1- arg))} as the decrementer.
13344 That expression is not far from the @code{while}, but is hidden in
13345 another Lisp macro, an @code{unless} macro. Unless we are at the end
13346 of the buffer --- that is what the @code{eobp} function determines; it
13347 is an abbreviation of @samp{End Of Buffer P} --- we decrease the value
13348 of @code{arg} by one.
13350 (If we are at the end of the buffer, we cannot go forward any more and
13351 the next loop of the @code{while} expression will test false since the
13352 test is an @code{and} with @code{(not (eobp))}. The @code{not}
13353 function means exactly as you expect; it is another name for
13354 @code{null}, a function that returns true when its argument is false.)
13356 Interestingly, the loop count is not decremented until we leave the
13357 space between paragraphs, unless we come to the end of buffer or stop
13358 seeing the local value of the paragraph separator.
13360 That second @code{while} also has a @code{(move-to-left-margin)}
13361 expression. The function is self-explanatory. It is inside a
13362 @code{progn} expression and not the last element of its body, so it is
13363 only invoked for its side effect, which is to move point to the left
13364 margin of the current line.
13367 The @code{looking-at} function is also self-explanatory; it returns
13368 true if the text after point matches the regular expression given as
13371 The rest of the body of the loop looks difficult at first, but makes
13372 sense as you come to understand it.
13375 First consider what happens if there is a fill prefix:
13379 (if fill-prefix-regexp
13380 ;; There is a fill prefix; it overrides parstart;
13381 ;; we go forward line by line
13382 (while (and (not (eobp))
13383 (progn (move-to-left-margin) (not (eobp)))
13384 (not (looking-at parsep))
13385 (looking-at fill-prefix-regexp))
13391 This expression moves point forward line by line so long
13392 as four conditions are true:
13396 Point is not at the end of the buffer.
13399 We can move to the left margin of the text and are
13400 not at the end of the buffer.
13403 The text following point does not separate paragraphs.
13406 The pattern following point is the fill prefix regular expression.
13409 The last condition may be puzzling, until you remember that point was
13410 moved to the beginning of the line early in the @code{forward-paragraph}
13411 function. This means that if the text has a fill prefix, the
13412 @code{looking-at} function will see it.
13415 Consider what happens when there is no fill prefix.
13419 (while (and (re-search-forward sp-parstart nil 1)
13420 (progn (setq start (match-beginning 0))
13423 (progn (move-to-left-margin)
13424 (not (looking-at parsep)))
13425 (or (not (looking-at parstart))
13426 (and use-hard-newlines
13427 (not (get-text-property (1- start) 'hard)))))
13433 This @code{while} loop has us searching forward for
13434 @code{sp-parstart}, which is the combination of possible whitespace
13435 with a the local value of the start of a paragraph or of a paragraph
13436 separator. (The latter two are within an expression starting
13437 @code{\(?:} so that they are not referenced by the
13438 @code{match-beginning} function.)
13441 The two expressions,
13445 (setq start (match-beginning 0))
13451 mean go to the start of the text matched by the regular expression
13454 The @code{(match-beginning 0)} expression is new. It returns a number
13455 specifying the location of the start of the text that was matched by
13458 The @code{match-beginning} function is used here because of a
13459 characteristic of a forward search: a successful forward search,
13460 regardless of whether it is a plain search or a regular expression
13461 search, moves point to the end of the text that is found. In this
13462 case, a successful search moves point to the end of the pattern for
13463 @code{sp-parstart}.
13465 However, we want to put point at the end of the current paragraph, not
13466 somewhere else. Indeed, since the search possibly includes the
13467 paragraph separator, point may end up at the beginning of the next one
13468 unless we use an expression that includes @code{match-beginning}.
13470 @findex match-beginning
13471 When given an argument of 0, @code{match-beginning} returns the
13472 position that is the start of the text matched by the most recent
13473 search. In this case, the most recent search looks for
13474 @code{sp-parstart}. The @code{(match-beginning 0)} expression returns
13475 the beginning position of that pattern, rather than the end position
13478 (Incidentally, when passed a positive number as an argument, the
13479 @code{match-beginning} function returns the location of point at that
13480 parenthesized expression in the last search unless that parenthesized
13481 expression begins with @code{\(?:}. I don't know why @code{\(?:}
13482 appears here since the argument is 0.)
13485 The last expression when there is no fill prefix is
13489 (if (< (point) (point-max))
13490 (goto-char start))))
13495 This says that if there is no fill prefix and if we are not at the
13496 end, point should move to the beginning of whatever was found by the
13497 regular expression search for @code{sp-parstart}.
13499 The full definition for the @code{forward-paragraph} function not only
13500 includes code for going forwards, but also code for going backwards.
13502 If you are reading this inside of GNU Emacs and you want to see the
13503 whole function, you can type @kbd{C-h f} (@code{describe-function})
13504 and the name of the function. This gives you the function
13505 documentation and the name of the library containing the function's
13506 source. Place point over the name of the library and press the RET
13507 key; you will be taken directly to the source. (Be sure to install
13508 your sources! Without them, you are like a person who tries to drive
13509 a car with his eyes shut!)
13511 @node etags, Regexp Review, forward-paragraph, Regexp Search
13512 @section Create Your Own @file{TAGS} File
13514 @cindex @file{TAGS} file, create own
13516 Besides @kbd{C-h f} (@code{describe-function}), another way to see the
13517 source of a function is to type @kbd{M-.} (@code{find-tag}) and the
13518 name of the function when prompted for it. This is a good habit to
13519 get into. This will take you directly to the source. If the
13520 @code{find-tag} function first asks you for the name of a @file{TAGS}
13521 table, give it the name of a @file{TAGS} file such as
13522 @file{/usr/local/src/emacs/src/TAGS}. (The exact path to your
13523 @file{TAGS} file depends on how your copy of Emacs was installed. I
13524 just told you the location that provides both my C and my Emacs Lisp
13527 You can also create your own @file{TAGS} file for directories that
13530 The @kbd{M-.} (@code{find-tag}) command takes you directly to the
13531 source for a function, variable, node, or other source. The function
13532 depends on tags tables to tell it where to go.
13534 You often need to build and install tags tables yourself. They are
13535 not built automatically. A tags table is called a @file{TAGS} file;
13536 the name is in upper case letters.
13538 You can create a @file{TAGS} file by calling the @code{etags} program
13539 that comes as a part of the Emacs distribution. Usually, @code{etags}
13540 is compiled and installed when Emacs is built. (@code{etags} is not
13541 an Emacs Lisp function or a part of Emacs; it is a C program.)
13544 To create a @file{TAGS} file, first switch to the directory in which
13545 you want to create the file. In Emacs you can do this with the
13546 @kbd{M-x cd} command, or by visiting a file in the directory, or by
13547 listing the directory with @kbd{C-x d} (@code{dired}). Then run the
13548 compile command, with @w{@code{etags *.el}} as the command to execute
13551 M-x compile RET etags *.el RET
13555 to create a @file{TAGS} file.
13557 For example, if you have a large number of files in your
13558 @file{~/emacs} directory, as I do---I have 137 @file{.el} files in it,
13559 of which I load 12---you can create a @file{TAGS} file for the Emacs
13560 Lisp files in that directory.
13563 The @code{etags} program takes all the
13564 usual shell `wildcards'. For example, if you have two directories for
13565 which you want a single @file{TAGS file}, type
13566 @w{@code{etags *.el ../elisp/*.el}},
13567 where @file{../elisp/} is the second directory:
13570 M-x compile RET etags *.el ../elisp/*.el RET
13577 M-x compile RET etags --help RET
13581 to see a list of the options accepted by @code{etags} as well as a
13582 list of supported languages.
13584 The @code{etags} program handles more than 20 languages, including
13585 Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, Java, LaTeX,
13586 Pascal, Perl, Python, Texinfo, makefiles, and most assemblers. The
13587 program has no switches for specifying the language; it recognizes the
13588 language in an input file according to its file name and contents.
13590 @file{etags} is very helpful when you are writing code yourself and
13591 want to refer back to functions you have already written. Just run
13592 @code{etags} again at intervals as you write new functions, so they
13593 become part of the @file{TAGS} file.
13595 If you think an appropriate @file{TAGS} file already exists for what
13596 you want, but do not know where it is, you can use the @code{locate}
13597 program to attempt to find it.
13599 Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list
13600 for you the full path names of all your @file{TAGS} files. On my
13601 system, this command lists 34 @file{TAGS} files. On the other hand, a
13602 `plain vanilla' system I recently installed did not contain any
13605 If the tags table you want has been created, you can use the @code{M-x
13606 visit-tags-table} command to specify it. Otherwise, you will need to
13607 create the tag table yourself and then use @code{M-x
13610 @subsubheading Building Tags in the Emacs sources
13611 @cindex Building Tags in the Emacs sources
13612 @cindex Tags in the Emacs sources
13615 The GNU Emacs sources come with a @file{Makefile} that contains a
13616 sophisticated @code{etags} command that creates, collects, and merges
13617 tags tables from all over the Emacs sources and puts the information
13618 into one @file{TAGS} file in the @file{src/} directory below the top
13619 level of your Emacs source directory.
13622 To build this @file{TAGS} file, go to the top level of your Emacs
13623 source directory and run the compile command @code{make tags}:
13626 M-x compile RET make tags RET
13630 (The @code{make tags} command works well with the GNU Emacs sources,
13631 as well as with some other source packages.)
13633 For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs
13636 @node Regexp Review, re-search Exercises, etags, Regexp Search
13637 @comment node-name, next, previous, up
13640 Here is a brief summary of some recently introduced functions.
13644 Repeatedly evaluate the body of the expression so long as the first
13645 element of the body tests true. Then return @code{nil}. (The
13646 expression is evaluated only for its side effects.)
13655 (insert (format "foo is %d.\n" foo))
13656 (setq foo (1- foo))))
13658 @result{} foo is 2.
13665 (The @code{insert} function inserts its arguments at point; the
13666 @code{format} function returns a string formatted from its arguments
13667 the way @code{message} formats its arguments; @code{\n} produces a new
13670 @item re-search-forward
13671 Search for a pattern, and if the pattern is found, move point to rest
13675 Takes four arguments, like @code{search-forward}:
13679 A regular expression that specifies the pattern to search for.
13680 (Remember to put quotation marks around this argument!)
13683 Optionally, the limit of the search.
13686 Optionally, what to do if the search fails, return @code{nil} or an
13690 Optionally, how many times to repeat the search; if negative, the
13691 search goes backwards.
13695 Bind some variables locally to particular values,
13696 and then evaluate the remaining arguments, returning the value of the
13697 last one. While binding the local variables, use the local values of
13698 variables bound earlier, if any.
13707 (message "`bar' is %d." bar))
13708 @result{} `bar' is 21.
13712 @item match-beginning
13713 Return the position of the start of the text found by the last regular
13717 Return @code{t} for true if the text after point matches the argument,
13718 which should be a regular expression.
13721 Return @code{t} for true if point is at the end of the accessible part
13722 of a buffer. The end of the accessible part is the end of the buffer
13723 if the buffer is not narrowed; it is the end of the narrowed part if
13724 the buffer is narrowed.
13728 @node re-search Exercises, , Regexp Review, Regexp Search
13729 @section Exercises with @code{re-search-forward}
13733 Write a function to search for a regular expression that matches two
13734 or more blank lines in sequence.
13737 Write a function to search for duplicated words, such as `the the'.
13738 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
13739 Manual}, for information on how to write a regexp (a regular
13740 expression) to match a string that is composed of two identical
13741 halves. You can devise several regexps; some are better than others.
13742 The function I use is described in an appendix, along with several
13743 regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}.
13746 @node Counting Words, Words in a defun, Regexp Search, Top
13747 @chapter Counting: Repetition and Regexps
13748 @cindex Repetition for word counting
13749 @cindex Regular expressions for word counting
13751 Repetition and regular expression searches are powerful tools that you
13752 often use when you write code in Emacs Lisp. This chapter illustrates
13753 the use of regular expression searches through the construction of
13754 word count commands using @code{while} loops and recursion.
13757 * Why Count Words::
13758 * count-words-region::
13759 * recursive-count-words::
13760 * Counting Exercise::
13763 @node Why Count Words, count-words-region, Counting Words, Counting Words
13765 @unnumberedsec Counting words
13768 The standard Emacs distribution contains a function for counting the
13769 number of lines within a region. However, there is no corresponding
13770 function for counting words.
13772 Certain types of writing ask you to count words. Thus, if you write
13773 an essay, you may be limited to 800 words; if you write a novel, you
13774 may discipline yourself to write 1000 words a day. It seems odd to me
13775 that Emacs lacks a word count command. Perhaps people use Emacs
13776 mostly for code or types of documentation that do not require word
13777 counts; or perhaps they restrict themselves to the operating system
13778 word count command, @code{wc}. Alternatively, people may follow
13779 the publishers' convention and compute a word count by dividing the
13780 number of characters in a document by five. In any event, here are
13781 commands to count words.
13783 @node count-words-region, recursive-count-words, Why Count Words, Counting Words
13784 @comment node-name, next, previous, up
13785 @section The @code{count-words-region} Function
13786 @findex count-words-region
13788 A word count command could count words in a line, paragraph, region,
13789 or buffer. What should the command cover? You could design the
13790 command to count the number of words in a complete buffer. However,
13791 the Emacs tradition encourages flexibility---you may want to count
13792 words in just a section, rather than all of a buffer. So it makes
13793 more sense to design the command to count the number of words in a
13794 region. Once you have a @code{count-words-region} command, you can,
13795 if you wish, count words in a whole buffer by marking it with
13796 @w{@kbd{C-x h}} (@code{mark-whole-buffer}).
13798 Clearly, counting words is a repetitive act: starting from the
13799 beginning of the region, you count the first word, then the second
13800 word, then the third word, and so on, until you reach the end of the
13801 region. This means that word counting is ideally suited to recursion
13802 or to a @code{while} loop.
13805 * Design count-words-region::
13809 @node Design count-words-region, Whitespace Bug, count-words-region, count-words-region
13811 @unnumberedsubsec Designing @code{count-words-region}
13814 First, we will implement the word count command with a @code{while}
13815 loop, then with recursion. The command will, of course, be
13819 The template for an interactive function definition is, as always:
13823 (defun @var{name-of-function} (@var{argument-list})
13824 "@var{documentation}@dots{}"
13825 (@var{interactive-expression}@dots{})
13830 What we need to do is fill in the slots.
13832 The name of the function should be self-explanatory and similar to the
13833 existing @code{count-lines-region} name. This makes the name easier
13834 to remember. @code{count-words-region} is a good choice.
13836 The function counts words within a region. This means that the
13837 argument list must contain symbols that are bound to the two
13838 positions, the beginning and end of the region. These two positions
13839 can be called @samp{beginning} and @samp{end} respectively. The first
13840 line of the documentation should be a single sentence, since that is
13841 all that is printed as documentation by a command such as
13842 @code{apropos}. The interactive expression will be of the form
13843 @samp{(interactive "r")}, since that will cause Emacs to pass the
13844 beginning and end of the region to the function's argument list. All
13847 The body of the function needs to be written to do three tasks:
13848 first, to set up conditions under which the @code{while} loop can
13849 count words, second, to run the @code{while} loop, and third, to send
13850 a message to the user.
13852 When a user calls @code{count-words-region}, point may be at the
13853 beginning or the end of the region. However, the counting process
13854 must start at the beginning of the region. This means we will want
13855 to put point there if it is not already there. Executing
13856 @code{(goto-char beginning)} ensures this. Of course, we will want to
13857 return point to its expected position when the function finishes its
13858 work. For this reason, the body must be enclosed in a
13859 @code{save-excursion} expression.
13861 The central part of the body of the function consists of a
13862 @code{while} loop in which one expression jumps point forward word by
13863 word, and another expression counts those jumps. The true-or-false-test
13864 of the @code{while} loop should test true so long as point should jump
13865 forward, and false when point is at the end of the region.
13867 We could use @code{(forward-word 1)} as the expression for moving point
13868 forward word by word, but it is easier to see what Emacs identifies as a
13869 `word' if we use a regular expression search.
13871 A regular expression search that finds the pattern for which it is
13872 searching leaves point after the last character matched. This means
13873 that a succession of successful word searches will move point forward
13876 As a practical matter, we want the regular expression search to jump
13877 over whitespace and punctuation between words as well as over the
13878 words themselves. A regexp that refuses to jump over interword
13879 whitespace would never jump more than one word! This means that
13880 the regexp should include the whitespace and punctuation that follows
13881 a word, if any, as well as the word itself. (A word may end a buffer
13882 and not have any following whitespace or punctuation, so that part of
13883 the regexp must be optional.)
13885 Thus, what we want for the regexp is a pattern defining one or more
13886 word constituent characters followed, optionally, by one or more
13887 characters that are not word constituents. The regular expression for
13895 The buffer's syntax table determines which characters are and are not
13896 word constituents. (@xref{Syntax, , What Constitutes a Word or
13897 Symbol?}, for more about syntax. Also, see @ref{Syntax, Syntax, The
13898 Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, ,
13899 Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
13902 The search expression looks like this:
13905 (re-search-forward "\\w+\\W*")
13909 (Note that paired backslashes precede the @samp{w} and @samp{W}. A
13910 single backslash has special meaning to the Emacs Lisp interpreter.
13911 It indicates that the following character is interpreted differently
13912 than usual. For example, the two characters, @samp{\n}, stand for
13913 @samp{newline}, rather than for a backslash followed by @samp{n}. Two
13914 backslashes in a row stand for an ordinary, `unspecial' backslash,
13915 which in this case is followed by a letter, the combination of which
13916 is important to @code{re-search-forward}.)
13918 We need a counter to count how many words there are; this variable
13919 must first be set to 0 and then incremented each time Emacs goes
13920 around the @code{while} loop. The incrementing expression is simply:
13923 (setq count (1+ count))
13926 Finally, we want to tell the user how many words there are in the
13927 region. The @code{message} function is intended for presenting this
13928 kind of information to the user. The message has to be phrased so
13929 that it reads properly regardless of how many words there are in the
13930 region: we don't want to say that ``there are 1 words in the region''.
13931 The conflict between singular and plural is ungrammatical. We can
13932 solve this problem by using a conditional expression that evaluates
13933 different messages depending on the number of words in the region.
13934 There are three possibilities: no words in the region, one word in the
13935 region, and more than one word. This means that the @code{cond}
13936 special form is appropriate.
13939 All this leads to the following function definition:
13943 ;;; @r{First version; has bugs!}
13944 (defun count-words-region (beginning end)
13945 "Print number of words in the region.
13946 Words are defined as at least one word-constituent
13947 character followed by at least one character that
13948 is not a word-constituent. The buffer's syntax
13949 table determines which characters these are."
13951 (message "Counting words in region ... ")
13955 ;;; @r{1. Set up appropriate conditions.}
13957 (goto-char beginning)
13962 ;;; @r{2. Run the} while @r{loop.}
13963 (while (< (point) end)
13964 (re-search-forward "\\w+\\W*")
13965 (setq count (1+ count)))
13969 ;;; @r{3. Send a message to the user.}
13970 (cond ((zerop count)
13972 "The region does NOT have any words."))
13975 "The region has 1 word."))
13978 "The region has %d words." count))))))
13983 As written, the function works, but not in all circumstances.
13985 @node Whitespace Bug, , Design count-words-region, count-words-region
13986 @comment node-name, next, previous, up
13987 @subsection The Whitespace Bug in @code{count-words-region}
13989 The @code{count-words-region} command described in the preceding
13990 section has two bugs, or rather, one bug with two manifestations.
13991 First, if you mark a region containing only whitespace in the middle
13992 of some text, the @code{count-words-region} command tells you that the
13993 region contains one word! Second, if you mark a region containing
13994 only whitespace at the end of the buffer or the accessible portion of
13995 a narrowed buffer, the command displays an error message that looks
13999 Search failed: "\\w+\\W*"
14002 If you are reading this in Info in GNU Emacs, you can test for these
14005 First, evaluate the function in the usual manner to install it.
14007 Here is a copy of the definition. Place your cursor after the closing
14008 parenthesis and type @kbd{C-x C-e} to install it.
14012 ;; @r{First version; has bugs!}
14013 (defun count-words-region (beginning end)
14014 "Print number of words in the region.
14015 Words are defined as at least one word-constituent character followed
14016 by at least one character that is not a word-constituent. The buffer's
14017 syntax table determines which characters these are."
14021 (message "Counting words in region ... ")
14025 ;;; @r{1. Set up appropriate conditions.}
14027 (goto-char beginning)
14032 ;;; @r{2. Run the} while @r{loop.}
14033 (while (< (point) end)
14034 (re-search-forward "\\w+\\W*")
14035 (setq count (1+ count)))
14039 ;;; @r{3. Send a message to the user.}
14040 (cond ((zerop count)
14041 (message "The region does NOT have any words."))
14042 ((= 1 count) (message "The region has 1 word."))
14043 (t (message "The region has %d words." count))))))
14049 If you wish, you can also install this keybinding by evaluating it:
14052 (global-set-key "\C-c=" 'count-words-region)
14055 To conduct the first test, set mark and point to the beginning and end
14056 of the following line and then type @kbd{C-c =} (or @kbd{M-x
14057 count-words-region} if you have not bound @kbd{C-c =}):
14064 Emacs will tell you, correctly, that the region has three words.
14066 Repeat the test, but place mark at the beginning of the line and place
14067 point just @emph{before} the word @samp{one}. Again type the command
14068 @kbd{C-c =} (or @kbd{M-x count-words-region}). Emacs should tell you
14069 that the region has no words, since it is composed only of the
14070 whitespace at the beginning of the line. But instead Emacs tells you
14071 that the region has one word!
14073 For the third test, copy the sample line to the end of the
14074 @file{*scratch*} buffer and then type several spaces at the end of the
14075 line. Place mark right after the word @samp{three} and point at the
14076 end of line. (The end of the line will be the end of the buffer.)
14077 Type @kbd{C-c =} (or @kbd{M-x count-words-region}) as you did before.
14078 Again, Emacs should tell you that the region has no words, since it is
14079 composed only of the whitespace at the end of the line. Instead,
14080 Emacs displays an error message saying @samp{Search failed}.
14082 The two bugs stem from the same problem.
14084 Consider the first manifestation of the bug, in which the command
14085 tells you that the whitespace at the beginning of the line contains
14086 one word. What happens is this: The @code{M-x count-words-region}
14087 command moves point to the beginning of the region. The @code{while}
14088 tests whether the value of point is smaller than the value of
14089 @code{end}, which it is. Consequently, the regular expression search
14090 looks for and finds the first word. It leaves point after the word.
14091 @code{count} is set to one. The @code{while} loop repeats; but this
14092 time the value of point is larger than the value of @code{end}, the
14093 loop is exited; and the function displays a message saying the number
14094 of words in the region is one. In brief, the regular expression
14095 search looks for and finds the word even though it is outside
14098 In the second manifestation of the bug, the region is whitespace at
14099 the end of the buffer. Emacs says @samp{Search failed}. What happens
14100 is that the true-or-false-test in the @code{while} loop tests true, so
14101 the search expression is executed. But since there are no more words
14102 in the buffer, the search fails.
14104 In both manifestations of the bug, the search extends or attempts to
14105 extend outside of the region.
14107 The solution is to limit the search to the region---this is a fairly
14108 simple action, but as you may have come to expect, it is not quite as
14109 simple as you might think.
14111 As we have seen, the @code{re-search-forward} function takes a search
14112 pattern as its first argument. But in addition to this first,
14113 mandatory argument, it accepts three optional arguments. The optional
14114 second argument bounds the search. The optional third argument, if
14115 @code{t}, causes the function to return @code{nil} rather than signal
14116 an error if the search fails. The optional fourth argument is a
14117 repeat count. (In Emacs, you can see a function's documentation by
14118 typing @kbd{C-h f}, the name of the function, and then @key{RET}.)
14120 In the @code{count-words-region} definition, the value of the end of
14121 the region is held by the variable @code{end} which is passed as an
14122 argument to the function. Thus, we can add @code{end} as an argument
14123 to the regular expression search expression:
14126 (re-search-forward "\\w+\\W*" end)
14129 However, if you make only this change to the @code{count-words-region}
14130 definition and then test the new version of the definition on a
14131 stretch of whitespace, you will receive an error message saying
14132 @samp{Search failed}.
14134 What happens is this: the search is limited to the region, and fails
14135 as you expect because there are no word-constituent characters in the
14136 region. Since it fails, we receive an error message. But we do not
14137 want to receive an error message in this case; we want to receive the
14138 message that "The region does NOT have any words."
14140 The solution to this problem is to provide @code{re-search-forward}
14141 with a third argument of @code{t}, which causes the function to return
14142 @code{nil} rather than signal an error if the search fails.
14144 However, if you make this change and try it, you will see the message
14145 ``Counting words in region ... '' and @dots{} you will keep on seeing
14146 that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}).
14148 Here is what happens: the search is limited to the region, as before,
14149 and it fails because there are no word-constituent characters in the
14150 region, as expected. Consequently, the @code{re-search-forward}
14151 expression returns @code{nil}. It does nothing else. In particular,
14152 it does not move point, which it does as a side effect if it finds the
14153 search target. After the @code{re-search-forward} expression returns
14154 @code{nil}, the next expression in the @code{while} loop is evaluated.
14155 This expression increments the count. Then the loop repeats. The
14156 true-or-false-test tests true because the value of point is still less
14157 than the value of end, since the @code{re-search-forward} expression
14158 did not move point. @dots{} and the cycle repeats @dots{}
14160 The @code{count-words-region} definition requires yet another
14161 modification, to cause the true-or-false-test of the @code{while} loop
14162 to test false if the search fails. Put another way, there are two
14163 conditions that must be satisfied in the true-or-false-test before the
14164 word count variable is incremented: point must still be within the
14165 region and the search expression must have found a word to count.
14167 Since both the first condition and the second condition must be true
14168 together, the two expressions, the region test and the search
14169 expression, can be joined with an @code{and} special form and embedded in
14170 the @code{while} loop as the true-or-false-test, like this:
14173 (and (< (point) end) (re-search-forward "\\w+\\W*" end t))
14176 @c colon in printed section title causes problem in Info cross reference
14177 @c also trouble with an overfull hbox
14180 (For information about @code{and}, see
14181 @ref{kill-new function, , The @code{kill-new} function}.)
14185 (@xref{kill-new function, , The @code{kill-new} function}, for
14186 information about @code{and}.)
14189 The @code{re-search-forward} expression returns @code{t} if the search
14190 succeeds and as a side effect moves point. Consequently, as words are
14191 found, point is moved through the region. When the search expression
14192 fails to find another word, or when point reaches the end of the
14193 region, the true-or-false-test tests false, the @code{while} loop
14194 exits, and the @code{count-words-region} function displays one or
14195 other of its messages.
14197 After incorporating these final changes, the @code{count-words-region}
14198 works without bugs (or at least, without bugs that I have found!).
14199 Here is what it looks like:
14203 ;;; @r{Final version:} @code{while}
14204 (defun count-words-region (beginning end)
14205 "Print number of words in the region."
14207 (message "Counting words in region ... ")
14211 ;;; @r{1. Set up appropriate conditions.}
14214 (goto-char beginning)
14218 ;;; @r{2. Run the} while @r{loop.}
14219 (while (and (< (point) end)
14220 (re-search-forward "\\w+\\W*" end t))
14221 (setq count (1+ count)))
14225 ;;; @r{3. Send a message to the user.}
14226 (cond ((zerop count)
14228 "The region does NOT have any words."))
14231 "The region has 1 word."))
14234 "The region has %d words." count))))))
14238 @node recursive-count-words, Counting Exercise, count-words-region, Counting Words
14239 @comment node-name, next, previous, up
14240 @section Count Words Recursively
14241 @cindex Count words recursively
14242 @cindex Recursively counting words
14243 @cindex Words, counted recursively
14245 You can write the function for counting words recursively as well as
14246 with a @code{while} loop. Let's see how this is done.
14248 First, we need to recognize that the @code{count-words-region}
14249 function has three jobs: it sets up the appropriate conditions for
14250 counting to occur; it counts the words in the region; and it sends a
14251 message to the user telling how many words there are.
14253 If we write a single recursive function to do everything, we will
14254 receive a message for every recursive call. If the region contains 13
14255 words, we will receive thirteen messages, one right after the other.
14256 We don't want this! Instead, we must write two functions to do the
14257 job, one of which (the recursive function) will be used inside of the
14258 other. One function will set up the conditions and display the
14259 message; the other will return the word count.
14261 Let us start with the function that causes the message to be displayed.
14262 We can continue to call this @code{count-words-region}.
14264 This is the function that the user will call. It will be interactive.
14265 Indeed, it will be similar to our previous versions of this
14266 function, except that it will call @code{recursive-count-words} to
14267 determine how many words are in the region.
14270 We can readily construct a template for this function, based on our
14275 ;; @r{Recursive version; uses regular expression search}
14276 (defun count-words-region (beginning end)
14277 "@var{documentation}@dots{}"
14278 (@var{interactive-expression}@dots{})
14282 ;;; @r{1. Set up appropriate conditions.}
14283 (@var{explanatory message})
14284 (@var{set-up functions}@dots{}
14288 ;;; @r{2. Count the words.}
14289 @var{recursive call}
14293 ;;; @r{3. Send a message to the user.}
14294 @var{message providing word count}))
14298 The definition looks straightforward, except that somehow the count
14299 returned by the recursive call must be passed to the message
14300 displaying the word count. A little thought suggests that this can be
14301 done by making use of a @code{let} expression: we can bind a variable
14302 in the varlist of a @code{let} expression to the number of words in
14303 the region, as returned by the recursive call; and then the
14304 @code{cond} expression, using binding, can display the value to the
14307 Often, one thinks of the binding within a @code{let} expression as
14308 somehow secondary to the `primary' work of a function. But in this
14309 case, what you might consider the `primary' job of the function,
14310 counting words, is done within the @code{let} expression.
14313 Using @code{let}, the function definition looks like this:
14317 (defun count-words-region (beginning end)
14318 "Print number of words in the region."
14323 ;;; @r{1. Set up appropriate conditions.}
14324 (message "Counting words in region ... ")
14326 (goto-char beginning)
14330 ;;; @r{2. Count the words.}
14331 (let ((count (recursive-count-words end)))
14335 ;;; @r{3. Send a message to the user.}
14336 (cond ((zerop count)
14338 "The region does NOT have any words."))
14341 "The region has 1 word."))
14344 "The region has %d words." count))))))
14348 Next, we need to write the recursive counting function.
14350 A recursive function has at least three parts: the `do-again-test', the
14351 `next-step-expression', and the recursive call.
14353 The do-again-test determines whether the function will or will not be
14354 called again. Since we are counting words in a region and can use a
14355 function that moves point forward for every word, the do-again-test
14356 can check whether point is still within the region. The do-again-test
14357 should find the value of point and determine whether point is before,
14358 at, or after the value of the end of the region. We can use the
14359 @code{point} function to locate point. Clearly, we must pass the
14360 value of the end of the region to the recursive counting function as an
14363 In addition, the do-again-test should also test whether the search finds a
14364 word. If it does not, the function should not call itself again.
14366 The next-step-expression changes a value so that when the recursive
14367 function is supposed to stop calling itself, it stops. More
14368 precisely, the next-step-expression changes a value so that at the
14369 right time, the do-again-test stops the recursive function from
14370 calling itself again. In this case, the next-step-expression can be
14371 the expression that moves point forward, word by word.
14373 The third part of a recursive function is the recursive call.
14375 Somewhere, also, we also need a part that does the `work' of the
14376 function, a part that does the counting. A vital part!
14379 But already, we have an outline of the recursive counting function:
14383 (defun recursive-count-words (region-end)
14384 "@var{documentation}@dots{}"
14385 @var{do-again-test}
14386 @var{next-step-expression}
14387 @var{recursive call})
14391 Now we need to fill in the slots. Let's start with the simplest cases
14392 first: if point is at or beyond the end of the region, there cannot
14393 be any words in the region, so the function should return zero.
14394 Likewise, if the search fails, there are no words to count, so the
14395 function should return zero.
14397 On the other hand, if point is within the region and the search
14398 succeeds, the function should call itself again.
14401 Thus, the do-again-test should look like this:
14405 (and (< (point) region-end)
14406 (re-search-forward "\\w+\\W*" region-end t))
14410 Note that the search expression is part of the do-again-test---the
14411 function returns @code{t} if its search succeeds and @code{nil} if it
14412 fails. (@xref{Whitespace Bug, , The Whitespace Bug in
14413 @code{count-words-region}}, for an explanation of how
14414 @code{re-search-forward} works.)
14416 The do-again-test is the true-or-false test of an @code{if} clause.
14417 Clearly, if the do-again-test succeeds, the then-part of the @code{if}
14418 clause should call the function again; but if it fails, the else-part
14419 should return zero since either point is outside the region or the
14420 search failed because there were no words to find.
14422 But before considering the recursive call, we need to consider the
14423 next-step-expression. What is it? Interestingly, it is the search
14424 part of the do-again-test.
14426 In addition to returning @code{t} or @code{nil} for the
14427 do-again-test, @code{re-search-forward} moves point forward as a side
14428 effect of a successful search. This is the action that changes the
14429 value of point so that the recursive function stops calling itself
14430 when point completes its movement through the region. Consequently,
14431 the @code{re-search-forward} expression is the next-step-expression.
14434 In outline, then, the body of the @code{recursive-count-words}
14435 function looks like this:
14439 (if @var{do-again-test-and-next-step-combined}
14441 @var{recursive-call-returning-count}
14447 How to incorporate the mechanism that counts?
14449 If you are not used to writing recursive functions, a question like
14450 this can be troublesome. But it can and should be approached
14453 We know that the counting mechanism should be associated in some way
14454 with the recursive call. Indeed, since the next-step-expression moves
14455 point forward by one word, and since a recursive call is made for
14456 each word, the counting mechanism must be an expression that adds one
14457 to the value returned by a call to @code{recursive-count-words}.
14460 Consider several cases:
14464 If there are two words in the region, the function should return
14465 a value resulting from adding one to the value returned when it counts
14466 the first word, plus the number returned when it counts the remaining
14467 words in the region, which in this case is one.
14470 If there is one word in the region, the function should return
14471 a value resulting from adding one to the value returned when it counts
14472 that word, plus the number returned when it counts the remaining
14473 words in the region, which in this case is zero.
14476 If there are no words in the region, the function should return zero.
14479 From the sketch we can see that the else-part of the @code{if} returns
14480 zero for the case of no words. This means that the then-part of the
14481 @code{if} must return a value resulting from adding one to the value
14482 returned from a count of the remaining words.
14485 The expression will look like this, where @code{1+} is a function that
14486 adds one to its argument.
14489 (1+ (recursive-count-words region-end))
14493 The whole @code{recursive-count-words} function will then look like
14498 (defun recursive-count-words (region-end)
14499 "@var{documentation}@dots{}"
14501 ;;; @r{1. do-again-test}
14502 (if (and (< (point) region-end)
14503 (re-search-forward "\\w+\\W*" region-end t))
14507 ;;; @r{2. then-part: the recursive call}
14508 (1+ (recursive-count-words region-end))
14510 ;;; @r{3. else-part}
14516 Let's examine how this works:
14518 If there are no words in the region, the else part of the @code{if}
14519 expression is evaluated and consequently the function returns zero.
14521 If there is one word in the region, the value of point is less than
14522 the value of @code{region-end} and the search succeeds. In this case,
14523 the true-or-false-test of the @code{if} expression tests true, and the
14524 then-part of the @code{if} expression is evaluated. The counting
14525 expression is evaluated. This expression returns a value (which will
14526 be the value returned by the whole function) that is the sum of one
14527 added to the value returned by a recursive call.
14529 Meanwhile, the next-step-expression has caused point to jump over the
14530 first (and in this case only) word in the region. This means that
14531 when @code{(recursive-count-words region-end)} is evaluated a second
14532 time, as a result of the recursive call, the value of point will be
14533 equal to or greater than the value of region end. So this time,
14534 @code{recursive-count-words} will return zero. The zero will be added
14535 to one, and the original evaluation of @code{recursive-count-words}
14536 will return one plus zero, which is one, which is the correct amount.
14538 Clearly, if there are two words in the region, the first call to
14539 @code{recursive-count-words} returns one added to the value returned
14540 by calling @code{recursive-count-words} on a region containing the
14541 remaining word---that is, it adds one to one, producing two, which is
14542 the correct amount.
14544 Similarly, if there are three words in the region, the first call to
14545 @code{recursive-count-words} returns one added to the value returned
14546 by calling @code{recursive-count-words} on a region containing the
14547 remaining two words---and so on and so on.
14551 With full documentation the two functions look like this:
14555 The recursive function:
14557 @findex recursive-count-words
14560 (defun recursive-count-words (region-end)
14561 "Number of words between point and REGION-END."
14565 ;;; @r{1. do-again-test}
14566 (if (and (< (point) region-end)
14567 (re-search-forward "\\w+\\W*" region-end t))
14571 ;;; @r{2. then-part: the recursive call}
14572 (1+ (recursive-count-words region-end))
14574 ;;; @r{3. else-part}
14585 ;;; @r{Recursive version}
14586 (defun count-words-region (beginning end)
14587 "Print number of words in the region.
14591 Words are defined as at least one word-constituent
14592 character followed by at least one character that is
14593 not a word-constituent. The buffer's syntax table
14594 determines which characters these are."
14598 (message "Counting words in region ... ")
14600 (goto-char beginning)
14601 (let ((count (recursive-count-words end)))
14604 (cond ((zerop count)
14606 "The region does NOT have any words."))
14610 (message "The region has 1 word."))
14613 "The region has %d words." count))))))
14617 @node Counting Exercise, , recursive-count-words, Counting Words
14618 @section Exercise: Counting Punctuation
14620 Using a @code{while} loop, write a function to count the number of
14621 punctuation marks in a region---period, comma, semicolon, colon,
14622 exclamation mark, and question mark. Do the same using recursion.
14624 @node Words in a defun, Readying a Graph, Counting Words, Top
14625 @chapter Counting Words in a @code{defun}
14626 @cindex Counting words in a @code{defun}
14627 @cindex Word counting in a @code{defun}
14629 Our next project is to count the number of words in a function
14630 definition. Clearly, this can be done using some variant of
14631 @code{count-word-region}. @xref{Counting Words, , Counting Words:
14632 Repetition and Regexps}. If we are just going to count the words in
14633 one definition, it is easy enough to mark the definition with the
14634 @kbd{C-M-h} (@code{mark-defun}) command, and then call
14635 @code{count-word-region}.
14637 However, I am more ambitious: I want to count the words and symbols in
14638 every definition in the Emacs sources and then print a graph that
14639 shows how many functions there are of each length: how many contain 40
14640 to 49 words or symbols, how many contain 50 to 59 words or symbols,
14641 and so on. I have often been curious how long a typical function is,
14642 and this will tell.
14645 * Divide and Conquer::
14646 * Words and Symbols::
14648 * count-words-in-defun::
14651 * lengths-list-file::
14653 * Several files recursively::
14654 * Prepare the data::
14657 @node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun
14659 @unnumberedsec Divide and Conquer
14662 Described in one phrase, the histogram project is daunting; but
14663 divided into numerous small steps, each of which we can take one at a
14664 time, the project becomes less fearsome. Let us consider what the
14669 First, write a function to count the words in one definition. This
14670 includes the problem of handling symbols as well as words.
14673 Second, write a function to list the numbers of words in each function
14674 in a file. This function can use the @code{count-words-in-defun}
14678 Third, write a function to list the numbers of words in each function
14679 in each of several files. This entails automatically finding the
14680 various files, switching to them, and counting the words in the
14681 definitions within them.
14684 Fourth, write a function to convert the list of numbers that we
14685 created in step three to a form that will be suitable for printing as
14689 Fifth, write a function to print the results as a graph.
14692 This is quite a project! But if we take each step slowly, it will not
14695 @node Words and Symbols, Syntax, Divide and Conquer, Words in a defun
14696 @section What to Count?
14697 @cindex Words and symbols in defun
14699 When we first start thinking about how to count the words in a
14700 function definition, the first question is (or ought to be) what are
14701 we going to count? When we speak of `words' with respect to a Lisp
14702 function definition, we are actually speaking, in large part, of
14703 `symbols'. For example, the following @code{multiply-by-seven}
14704 function contains the five symbols @code{defun},
14705 @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In
14706 addition, in the documentation string, it contains the four words
14707 @samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The
14708 symbol @samp{number} is repeated, so the definition contains a total
14709 of ten words and symbols.
14713 (defun multiply-by-seven (number)
14714 "Multiply NUMBER by seven."
14720 However, if we mark the @code{multiply-by-seven} definition with
14721 @kbd{C-M-h} (@code{mark-defun}), and then call
14722 @code{count-words-region} on it, we will find that
14723 @code{count-words-region} claims the definition has eleven words, not
14724 ten! Something is wrong!
14726 The problem is twofold: @code{count-words-region} does not count the
14727 @samp{*} as a word, and it counts the single symbol,
14728 @code{multiply-by-seven}, as containing three words. The hyphens are
14729 treated as if they were interword spaces rather than intraword
14730 connectors: @samp{multiply-by-seven} is counted as if it were written
14731 @samp{multiply by seven}.
14733 The cause of this confusion is the regular expression search within
14734 the @code{count-words-region} definition that moves point forward word
14735 by word. In the canonical version of @code{count-words-region}, the
14743 This regular expression is a pattern defining one or more word
14744 constituent characters possibly followed by one or more characters
14745 that are not word constituents. What is meant by `word constituent
14746 characters' brings us to the issue of syntax, which is worth a section
14749 @node Syntax, count-words-in-defun, Words and Symbols, Words in a defun
14750 @section What Constitutes a Word or Symbol?
14751 @cindex Syntax categories and tables
14753 Emacs treats different characters as belonging to different
14754 @dfn{syntax categories}. For example, the regular expression,
14755 @samp{\\w+}, is a pattern specifying one or more @emph{word
14756 constituent} characters. Word constituent characters are members of
14757 one syntax category. Other syntax categories include the class of
14758 punctuation characters, such as the period and the comma, and the
14759 class of whitespace characters, such as the blank space and the tab
14760 character. (For more information, see @ref{Syntax, Syntax, The Syntax
14761 Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , Syntax
14762 Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
14764 Syntax tables specify which characters belong to which categories.
14765 Usually, a hyphen is not specified as a `word constituent character'.
14766 Instead, it is specified as being in the `class of characters that are
14767 part of symbol names but not words.' This means that the
14768 @code{count-words-region} function treats it in the same way it treats
14769 an interword white space, which is why @code{count-words-region}
14770 counts @samp{multiply-by-seven} as three words.
14772 There are two ways to cause Emacs to count @samp{multiply-by-seven} as
14773 one symbol: modify the syntax table or modify the regular expression.
14775 We could redefine a hyphen as a word constituent character by
14776 modifying the syntax table that Emacs keeps for each mode. This
14777 action would serve our purpose, except that a hyphen is merely the
14778 most common character within symbols that is not typically a word
14779 constituent character; there are others, too.
14781 Alternatively, we can redefine the regular expression used in the
14782 @code{count-words} definition so as to include symbols. This
14783 procedure has the merit of clarity, but the task is a little tricky.
14786 The first part is simple enough: the pattern must match ``at least one
14787 character that is a word or symbol constituent''. Thus:
14790 "\\(\\w\\|\\s_\\)+"
14794 The @samp{\\(} is the first part of the grouping construct that
14795 includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated
14796 by the @samp{\\|}. The @samp{\\w} matches any word-constituent
14797 character and the @samp{\\s_} matches any character that is part of a
14798 symbol name but not a word-constituent character. The @samp{+}
14799 following the group indicates that the word or symbol constituent
14800 characters must be matched at least once.
14802 However, the second part of the regexp is more difficult to design.
14803 What we want is to follow the first part with ``optionally one or more
14804 characters that are not constituents of a word or symbol''. At first,
14805 I thought I could define this with the following:
14808 "\\(\\W\\|\\S_\\)*"
14812 The upper case @samp{W} and @samp{S} match characters that are
14813 @emph{not} word or symbol constituents. Unfortunately, this
14814 expression matches any character that is either not a word constituent
14815 or not a symbol constituent. This matches any character!
14817 I then noticed that every word or symbol in my test region was
14818 followed by white space (blank space, tab, or newline). So I tried
14819 placing a pattern to match one or more blank spaces after the pattern
14820 for one or more word or symbol constituents. This failed, too. Words
14821 and symbols are often separated by whitespace, but in actual code
14822 parentheses may follow symbols and punctuation may follow words. So
14823 finally, I designed a pattern in which the word or symbol constituents
14824 are followed optionally by characters that are not white space and
14825 then followed optionally by white space.
14828 Here is the full regular expression:
14831 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14834 @node count-words-in-defun, Several defuns, Syntax, Words in a defun
14835 @section The @code{count-words-in-defun} Function
14836 @cindex Counting words in a @code{defun}
14838 We have seen that there are several ways to write a
14839 @code{count-word-region} function. To write a
14840 @code{count-words-in-defun}, we need merely adapt one of these
14843 The version that uses a @code{while} loop is easy to understand, so I
14844 am going to adapt that. Because @code{count-words-in-defun} will be
14845 part of a more complex program, it need not be interactive and it need
14846 not display a message but just return the count. These considerations
14847 simplify the definition a little.
14849 On the other hand, @code{count-words-in-defun} will be used within a
14850 buffer that contains function definitions. Consequently, it is
14851 reasonable to ask that the function determine whether it is called
14852 when point is within a function definition, and if it is, to return
14853 the count for that definition. This adds complexity to the
14854 definition, but saves us from needing to pass arguments to the
14858 These considerations lead us to prepare the following template:
14862 (defun count-words-in-defun ()
14863 "@var{documentation}@dots{}"
14864 (@var{set up}@dots{}
14865 (@var{while loop}@dots{})
14866 @var{return count})
14871 As usual, our job is to fill in the slots.
14875 We are presuming that this function will be called within a buffer
14876 containing function definitions. Point will either be within a
14877 function definition or not. For @code{count-words-in-defun} to work,
14878 point must move to the beginning of the definition, a counter must
14879 start at zero, and the counting loop must stop when point reaches the
14880 end of the definition.
14882 The @code{beginning-of-defun} function searches backwards for an
14883 opening delimiter such as a @samp{(} at the beginning of a line, and
14884 moves point to that position, or else to the limit of the search. In
14885 practice, this means that @code{beginning-of-defun} moves point to the
14886 beginning of an enclosing or preceding function definition, or else to
14887 the beginning of the buffer. We can use @code{beginning-of-defun} to
14888 place point where we wish to start.
14890 The @code{while} loop requires a counter to keep track of the words or
14891 symbols being counted. A @code{let} expression can be used to create
14892 a local variable for this purpose, and bind it to an initial value of zero.
14894 The @code{end-of-defun} function works like @code{beginning-of-defun}
14895 except that it moves point to the end of the definition.
14896 @code{end-of-defun} can be used as part of an expression that
14897 determines the position of the end of the definition.
14899 The set up for @code{count-words-in-defun} takes shape rapidly: first
14900 we move point to the beginning of the definition, then we create a
14901 local variable to hold the count, and finally, we record the position
14902 of the end of the definition so the @code{while} loop will know when to stop
14906 The code looks like this:
14910 (beginning-of-defun)
14912 (end (save-excursion (end-of-defun) (point))))
14917 The code is simple. The only slight complication is likely to concern
14918 @code{end}: it is bound to the position of the end of the definition
14919 by a @code{save-excursion} expression that returns the value of point
14920 after @code{end-of-defun} temporarily moves it to the end of the
14923 The second part of the @code{count-words-in-defun}, after the set up,
14924 is the @code{while} loop.
14926 The loop must contain an expression that jumps point forward word by
14927 word and symbol by symbol, and another expression that counts the
14928 jumps. The true-or-false-test for the @code{while} loop should test
14929 true so long as point should jump forward, and false when point is at
14930 the end of the definition. We have already redefined the regular
14931 expression for this (@pxref{Syntax}), so the loop is straightforward:
14935 (while (and (< (point) end)
14937 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t)
14938 (setq count (1+ count)))
14942 The third part of the function definition returns the count of words
14943 and symbols. This part is the last expression within the body of the
14944 @code{let} expression, and can be, very simply, the local variable
14945 @code{count}, which when evaluated returns the count.
14948 Put together, the @code{count-words-in-defun} definition looks like this:
14950 @findex count-words-in-defun
14953 (defun count-words-in-defun ()
14954 "Return the number of words and symbols in a defun."
14955 (beginning-of-defun)
14957 (end (save-excursion (end-of-defun) (point))))
14961 (and (< (point) end)
14963 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14965 (setq count (1+ count)))
14970 How to test this? The function is not interactive, but it is easy to
14971 put a wrapper around the function to make it interactive; we can use
14972 almost the same code as for the recursive version of
14973 @code{count-words-region}:
14977 ;;; @r{Interactive version.}
14978 (defun count-words-defun ()
14979 "Number of words and symbols in a function definition."
14982 "Counting words and symbols in function definition ... ")
14985 (let ((count (count-words-in-defun)))
14989 "The definition does NOT have any words or symbols."))
14994 "The definition has 1 word or symbol."))
14997 "The definition has %d words or symbols." count)))))
15003 Let's re-use @kbd{C-c =} as a convenient keybinding:
15006 (global-set-key "\C-c=" 'count-words-defun)
15009 Now we can try out @code{count-words-defun}: install both
15010 @code{count-words-in-defun} and @code{count-words-defun}, and set the
15011 keybinding, and then place the cursor within the following definition:
15015 (defun multiply-by-seven (number)
15016 "Multiply NUMBER by seven."
15023 Success! The definition has 10 words and symbols.
15025 The next problem is to count the numbers of words and symbols in
15026 several definitions within a single file.
15028 @node Several defuns, Find a File, count-words-in-defun, Words in a defun
15029 @section Count Several @code{defuns} Within a File
15031 A file such as @file{simple.el} may have a hundred or more function
15032 definitions within it. Our long term goal is to collect statistics on
15033 many files, but as a first step, our immediate goal is to collect
15034 statistics on one file.
15036 The information will be a series of numbers, each number being the
15037 length of a function definition. We can store the numbers in a list.
15039 We know that we will want to incorporate the information regarding one
15040 file with information about many other files; this means that the
15041 function for counting definition lengths within one file need only
15042 return the list of lengths. It need not and should not display any
15045 The word count commands contain one expression to jump point forward
15046 word by word and another expression to count the jumps. The function
15047 to return the lengths of definitions can be designed to work the same
15048 way, with one expression to jump point forward definition by
15049 definition and another expression to construct the lengths' list.
15051 This statement of the problem makes it elementary to write the
15052 function definition. Clearly, we will start the count at the
15053 beginning of the file, so the first command will be @code{(goto-char
15054 (point-min))}. Next, we start the @code{while} loop; and the
15055 true-or-false test of the loop can be a regular expression search for
15056 the next function definition---so long as the search succeeds, point
15057 is moved forward and then the body of the loop is evaluated. The body
15058 needs an expression that constructs the lengths' list. @code{cons},
15059 the list construction command, can be used to create the list. That
15060 is almost all there is to it.
15063 Here is what this fragment of code looks like:
15067 (goto-char (point-min))
15068 (while (re-search-forward "^(defun" nil t)
15070 (cons (count-words-in-defun) lengths-list)))
15074 What we have left out is the mechanism for finding the file that
15075 contains the function definitions.
15077 In previous examples, we either used this, the Info file, or we
15078 switched back and forth to some other buffer, such as the
15079 @file{*scratch*} buffer.
15081 Finding a file is a new process that we have not yet discussed.
15083 @node Find a File, lengths-list-file, Several defuns, Words in a defun
15084 @comment node-name, next, previous, up
15085 @section Find a File
15086 @cindex Find a File
15088 To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file})
15089 command. This command is almost, but not quite right for the lengths
15093 Let's look at the source for @code{find-file}:
15097 (defun find-file (filename)
15098 "Edit file FILENAME.
15099 Switch to a buffer visiting file FILENAME,
15100 creating one if none already exists."
15101 (interactive "FFind file: ")
15102 (switch-to-buffer (find-file-noselect filename)))
15107 (The most recent version of the @code{find-file} function definition
15108 permits you to specify optional wildcards visit multiple files; that
15109 makes the definition more complex and we will not discuss it here,
15110 since it is not relevant. You can see its source using either
15111 @kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).)
15115 (defun find-file (filename &optional wildcards)
15116 "Edit file FILENAME.
15117 Switch to a buffer visiting file FILENAME,
15118 creating one if none already exists.
15119 Interactively, the default if you just type RET is the current directory,
15120 but the visited file name is available through the minibuffer history:
15121 type M-n to pull it into the minibuffer.
15123 Interactively, or if WILDCARDS is non-nil in a call from Lisp,
15124 expand wildcards (if any) and visit multiple files. You can
15125 suppress wildcard expansion by setting `find-file-wildcards' to nil.
15127 To visit a file without any kind of conversion and without
15128 automatically choosing a major mode, use \\[find-file-literally]."
15129 (interactive (find-file-read-args "Find file: " nil))
15130 (let ((value (find-file-noselect filename nil nil wildcards)))
15132 (mapcar 'switch-to-buffer (nreverse value))
15133 (switch-to-buffer value))))
15136 The definition I am showing possesses short but complete documentation
15137 and an interactive specification that prompts you for a file name when
15138 you use the command interactively. The body of the definition
15139 contains two functions, @code{find-file-noselect} and
15140 @code{switch-to-buffer}.
15142 According to its documentation as shown by @kbd{C-h f} (the
15143 @code{describe-function} command), the @code{find-file-noselect}
15144 function reads the named file into a buffer and returns the buffer.
15145 (Its most recent version includes an optional wildcards argument,
15146 too, as well as another to read a file literally and an other you
15147 suppress warning messages. These optional arguments are irrelevant.)
15149 However, the @code{find-file-noselect} function does not select the
15150 buffer in which it puts the file. Emacs does not switch its attention
15151 (or yours if you are using @code{find-file-noselect}) to the named
15152 buffer. That is what @code{switch-to-buffer} does: it switches the
15153 buffer to which Emacs attention is directed; and it switches the
15154 buffer displayed in the window to the new buffer. We have discussed
15155 buffer switching elsewhere. (@xref{Switching Buffers}.)
15157 In this histogram project, we do not need to display each file on the
15158 screen as the program determines the length of each definition within
15159 it. Instead of employing @code{switch-to-buffer}, we can work with
15160 @code{set-buffer}, which redirects the attention of the computer
15161 program to a different buffer but does not redisplay it on the screen.
15162 So instead of calling on @code{find-file} to do the job, we must write
15163 our own expression.
15165 The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
15167 @node lengths-list-file, Several files, Find a File, Words in a defun
15168 @section @code{lengths-list-file} in Detail
15170 The core of the @code{lengths-list-file} function is a @code{while}
15171 loop containing a function to move point forward `defun by defun' and
15172 a function to count the number of words and symbols in each defun.
15173 This core must be surrounded by functions that do various other tasks,
15174 including finding the file, and ensuring that point starts out at the
15175 beginning of the file. The function definition looks like this:
15176 @findex lengths-list-file
15180 (defun lengths-list-file (filename)
15181 "Return list of definitions' lengths within FILE.
15182 The returned list is a list of numbers.
15183 Each number is the number of words or
15184 symbols in one function definition."
15187 (message "Working on `%s' ... " filename)
15189 (let ((buffer (find-file-noselect filename))
15191 (set-buffer buffer)
15192 (setq buffer-read-only t)
15194 (goto-char (point-min))
15195 (while (re-search-forward "^(defun" nil t)
15197 (cons (count-words-in-defun) lengths-list)))
15198 (kill-buffer buffer)
15204 The function is passed one argument, the name of the file on which it
15205 will work. It has four lines of documentation, but no interactive
15206 specification. Since people worry that a computer is broken if they
15207 don't see anything going on, the first line of the body is a
15210 The next line contains a @code{save-excursion} that returns Emacs'
15211 attention to the current buffer when the function completes. This is
15212 useful in case you embed this function in another function that
15213 presumes point is restored to the original buffer.
15215 In the varlist of the @code{let} expression, Emacs finds the file and
15216 binds the local variable @code{buffer} to the buffer containing the
15217 file. At the same time, Emacs creates @code{lengths-list} as a local
15220 Next, Emacs switches its attention to the buffer.
15222 In the following line, Emacs makes the buffer read-only. Ideally,
15223 this line is not necessary. None of the functions for counting words
15224 and symbols in a function definition should change the buffer.
15225 Besides, the buffer is not going to be saved, even if it were changed.
15226 This line is entirely the consequence of great, perhaps excessive,
15227 caution. The reason for the caution is that this function and those
15228 it calls work on the sources for Emacs and it is very inconvenient if
15229 they are inadvertently modified. It goes without saying that I did
15230 not realize a need for this line until an experiment went awry and
15231 started to modify my Emacs source files @dots{}
15233 Next comes a call to widen the buffer if it is narrowed. This
15234 function is usually not needed---Emacs creates a fresh buffer if none
15235 already exists; but if a buffer visiting the file already exists Emacs
15236 returns that one. In this case, the buffer may be narrowed and must
15237 be widened. If we wanted to be fully `user-friendly', we would
15238 arrange to save the restriction and the location of point, but we
15241 The @code{(goto-char (point-min))} expression moves point to the
15242 beginning of the buffer.
15244 Then comes a @code{while} loop in which the `work' of the function is
15245 carried out. In the loop, Emacs determines the length of each
15246 definition and constructs a lengths' list containing the information.
15248 Emacs kills the buffer after working through it. This is to save
15249 space inside of Emacs. My version of GNU Emacs 19 contained over 300
15250 source files of interest; GNU Emacs 22 contains over a thousand source
15251 files. Another function will apply @code{lengths-list-file} to each
15254 Finally, the last expression within the @code{let} expression is the
15255 @code{lengths-list} variable; its value is returned as the value of
15256 the whole function.
15258 You can try this function by installing it in the usual fashion. Then
15259 place your cursor after the following expression and type @kbd{C-x
15260 C-e} (@code{eval-last-sexp}).
15262 @c !!! 22.0.100 lisp sources location here
15265 "/usr/local/share/emacs/22.0.100/lisp/emacs-lisp/debug.el")
15269 (You may need to change the pathname of the file; the one here is for
15270 GNU Emacs version 22.0.100. To change the expression, copy it to
15271 the @file{*scratch*} buffer and edit it.
15275 (Also, to see the full length of the list, rather than a truncated
15276 version, you may have to evaluate the following:
15279 (custom-set-variables '(eval-expression-print-length nil))
15283 (@xref{defcustom, , Specifying Variables using @code{defcustom}}.)
15284 Then evaluate the @code{lengths-list-file} expression.)
15287 The lengths' list for @file{debug.el} takes less than a second to
15288 produce and looks like this in GNU Emacs 22:
15291 (83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587)
15295 (Using my old machine, the version 19 lengths' list for @file{debug.el}
15296 took seven seconds to produce and looked like this:
15299 (75 41 80 62 20 45 44 68 45 12 34 235)
15302 (The newer version of @file{debug.el} contains more defuns than the
15303 earlier one; and my new machine is much faster than the old one.)
15305 Note that the length of the last definition in the file is first in
15308 @node Several files, Several files recursively, lengths-list-file, Words in a defun
15309 @section Count Words in @code{defuns} in Different Files
15311 In the previous section, we created a function that returns a list of
15312 the lengths of each definition in a file. Now, we want to define a
15313 function to return a master list of the lengths of the definitions in
15316 Working on each of a list of files is a repetitious act, so we can use
15317 either a @code{while} loop or recursion.
15320 * lengths-list-many-files::
15324 @node lengths-list-many-files, append, Several files, Several files
15326 @unnumberedsubsec Determine the lengths of @code{defuns}
15329 The design using a @code{while} loop is routine. The argument passed
15330 the function is a list of files. As we saw earlier (@pxref{Loop
15331 Example}), you can write a @code{while} loop so that the body of the
15332 loop is evaluated if such a list contains elements, but to exit the
15333 loop if the list is empty. For this design to work, the body of the
15334 loop must contain an expression that shortens the list each time the
15335 body is evaluated, so that eventually the list is empty. The usual
15336 technique is to set the value of the list to the value of the @sc{cdr}
15337 of the list each time the body is evaluated.
15340 The template looks like this:
15344 (while @var{test-whether-list-is-empty}
15346 @var{set-list-to-cdr-of-list})
15350 Also, we remember that a @code{while} loop returns @code{nil} (the
15351 result of evaluating the true-or-false-test), not the result of any
15352 evaluation within its body. (The evaluations within the body of the
15353 loop are done for their side effects.) However, the expression that
15354 sets the lengths' list is part of the body---and that is the value
15355 that we want returned by the function as a whole. To do this, we
15356 enclose the @code{while} loop within a @code{let} expression, and
15357 arrange that the last element of the @code{let} expression contains
15358 the value of the lengths' list. (@xref{Incrementing Example, , Loop
15359 Example with an Incrementing Counter}.)
15361 @findex lengths-list-many-files
15363 These considerations lead us directly to the function itself:
15367 ;;; @r{Use @code{while} loop.}
15368 (defun lengths-list-many-files (list-of-files)
15369 "Return list of lengths of defuns in LIST-OF-FILES."
15372 (let (lengths-list)
15374 ;;; @r{true-or-false-test}
15375 (while list-of-files
15380 ;;; @r{Generate a lengths' list.}
15382 (expand-file-name (car list-of-files)))))
15386 ;;; @r{Make files' list shorter.}
15387 (setq list-of-files (cdr list-of-files)))
15389 ;;; @r{Return final value of lengths' list.}
15394 @code{expand-file-name} is a built-in function that converts a file
15395 name to the absolute, long, path name form of the directory in which
15396 the function is called.
15398 @c !!! 22.0.100 lisp sources location here
15400 Thus, if @code{expand-file-name} is called on @code{debug.el} when
15401 Emacs is visiting the
15402 @file{/usr/local/share/emacs/22.0.100/lisp/emacs-lisp/} directory,
15412 @c !!! 22.0.100 lisp sources location here
15414 /usr/local/share/emacs/22.0.100/lisp/emacs-lisp/debug.el
15417 The only other new element of this function definition is the as yet
15418 unstudied function @code{append}, which merits a short section for
15421 @node append, , lengths-list-many-files, Several files
15422 @subsection The @code{append} Function
15425 The @code{append} function attaches one list to another. Thus,
15428 (append '(1 2 3 4) '(5 6 7 8))
15439 This is exactly how we want to attach two lengths' lists produced by
15440 @code{lengths-list-file} to each other. The results contrast with
15444 (cons '(1 2 3 4) '(5 6 7 8))
15449 which constructs a new list in which the first argument to @code{cons}
15450 becomes the first element of the new list:
15453 ((1 2 3 4) 5 6 7 8)
15456 @node Several files recursively, Prepare the data, Several files, Words in a defun
15457 @section Recursively Count Words in Different Files
15459 Besides a @code{while} loop, you can work on each of a list of files
15460 with recursion. A recursive version of @code{lengths-list-many-files}
15461 is short and simple.
15463 The recursive function has the usual parts: the `do-again-test', the
15464 `next-step-expression', and the recursive call. The `do-again-test'
15465 determines whether the function should call itself again, which it
15466 will do if the @code{list-of-files} contains any remaining elements;
15467 the `next-step-expression' resets the @code{list-of-files} to the
15468 @sc{cdr} of itself, so eventually the list will be empty; and the
15469 recursive call calls itself on the shorter list. The complete
15470 function is shorter than this description!
15471 @findex recursive-lengths-list-many-files
15475 (defun recursive-lengths-list-many-files (list-of-files)
15476 "Return list of lengths of each defun in LIST-OF-FILES."
15477 (if list-of-files ; @r{do-again-test}
15480 (expand-file-name (car list-of-files)))
15481 (recursive-lengths-list-many-files
15482 (cdr list-of-files)))))
15487 In a sentence, the function returns the lengths' list for the first of
15488 the @code{list-of-files} appended to the result of calling itself on
15489 the rest of the @code{list-of-files}.
15491 Here is a test of @code{recursive-lengths-list-many-files}, along with
15492 the results of running @code{lengths-list-file} on each of the files
15495 Install @code{recursive-lengths-list-many-files} and
15496 @code{lengths-list-file}, if necessary, and then evaluate the
15497 following expressions. You may need to change the files' pathnames;
15498 those here work when this Info file and the Emacs sources are located
15499 in their customary places. To change the expressions, copy them to
15500 the @file{*scratch*} buffer, edit them, and then evaluate them.
15502 The results are shown after the @samp{@result{}}. (These results are
15503 for files from Emacs Version 22.0.100; files from other versions of
15504 Emacs may produce different results.)
15506 @c !!! 22.0.100 lisp sources location here
15509 (cd "/usr/local/share/emacs/22.0.100/")
15511 (lengths-list-file "./lisp/macros.el")
15512 @result{} (283 263 480 90)
15516 (lengths-list-file "./lisp/mail/mailalias.el")
15517 @result{} (38 32 29 95 178 180 321 218 324)
15521 (lengths-list-file "./lisp/makesum.el")
15526 (recursive-lengths-list-many-files
15527 '("./lisp/macros.el"
15528 "./lisp/mail/mailalias.el"
15529 "./lisp/makesum.el"))
15530 @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181)
15534 The @code{recursive-lengths-list-many-files} function produces the
15537 The next step is to prepare the data in the list for display in a graph.
15539 @node Prepare the data, , Several files recursively, Words in a defun
15540 @section Prepare the Data for Display in a Graph
15542 The @code{recursive-lengths-list-many-files} function returns a list
15543 of numbers. Each number records the length of a function definition.
15544 What we need to do now is transform this data into a list of numbers
15545 suitable for generating a graph. The new list will tell how many
15546 functions definitions contain less than 10 words and
15547 symbols, how many contain between 10 and 19 words and symbols, how
15548 many contain between 20 and 29 words and symbols, and so on.
15550 In brief, we need to go through the lengths' list produced by the
15551 @code{recursive-lengths-list-many-files} function and count the number
15552 of defuns within each range of lengths, and produce a list of those
15555 Based on what we have done before, we can readily foresee that it
15556 should not be too hard to write a function that `@sc{cdr}s' down the
15557 lengths' list, looks at each element, determines which length range it
15558 is in, and increments a counter for that range.
15560 However, before beginning to write such a function, we should consider
15561 the advantages of sorting the lengths' list first, so the numbers are
15562 ordered from smallest to largest. First, sorting will make it easier
15563 to count the numbers in each range, since two adjacent numbers will
15564 either be in the same length range or in adjacent ranges. Second, by
15565 inspecting a sorted list, we can discover the highest and lowest
15566 number, and thereby determine the largest and smallest length range
15572 * Counting function definitions::
15575 @node Sorting, Files List, Prepare the data, Prepare the data
15576 @subsection Sorting Lists
15579 Emacs contains a function to sort lists, called (as you might guess)
15580 @code{sort}. The @code{sort} function takes two arguments, the list
15581 to be sorted, and a predicate that determines whether the first of
15582 two list elements is ``less'' than the second.
15584 As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong
15585 Type Object as an Argument}), a predicate is a function that
15586 determines whether some property is true or false. The @code{sort}
15587 function will reorder a list according to whatever property the
15588 predicate uses; this means that @code{sort} can be used to sort
15589 non-numeric lists by non-numeric criteria---it can, for example,
15590 alphabetize a list.
15593 The @code{<} function is used when sorting a numeric list. For example,
15596 (sort '(4 8 21 17 33 7 21 7) '<)
15604 (4 7 7 8 17 21 21 33)
15608 (Note that in this example, both the arguments are quoted so that the
15609 symbols are not evaluated before being passed to @code{sort} as
15612 Sorting the list returned by the
15613 @code{recursive-lengths-list-many-files} function is straightforward;
15614 it uses the @code{<} function:
15618 In GNU Emacs 22, eval
15620 (cd "/usr/local/share/emacs/22.0.50/")
15622 (recursive-lengths-list-many-files
15623 '("./lisp/macros.el"
15624 "./lisp/mail/mailalias.el"
15625 "./lisp/makesum.el"))
15633 (recursive-lengths-list-many-files
15634 '("./lisp/macros.el"
15635 "./lisp/mailalias.el"
15636 "./lisp/makesum.el"))
15646 (29 32 38 85 90 95 178 180 181 218 263 283 321 324 480)
15650 (Note that in this example, the first argument to @code{sort} is not
15651 quoted, since the expression must be evaluated so as to produce the
15652 list that is passed to @code{sort}.)
15654 @node Files List, Counting function definitions, Sorting, Prepare the data
15655 @subsection Making a List of Files
15657 The @code{recursive-lengths-list-many-files} function requires a list
15658 of files as its argument. For our test examples, we constructed such
15659 a list by hand; but the Emacs Lisp source directory is too large for
15660 us to do for that. Instead, we will write a function to do the job
15661 for us. In this function, we will use both a @code{while} loop and a
15664 @findex directory-files
15665 We did not have to write a function like this for older versions of
15666 GNU Emacs, since they placed all the @samp{.el} files in one
15667 directory. Instead, we were able to use the @code{directory-files}
15668 function, which lists the names of files that match a specified
15669 pattern within a single directory.
15671 However, recent versions of Emacs place Emacs Lisp files in
15672 sub-directories of the top level @file{lisp} directory. This
15673 re-arrangement eases navigation. For example, all the mail related
15674 files are in a @file{lisp} sub-directory called @file{mail}. But at
15675 the same time, this arrangement forces us to create a file listing
15676 function that descends into the sub-directories.
15678 @findex files-in-below-directory
15679 We can create this function, called @code{files-in-below-directory},
15680 using familiar functions such as @code{car}, @code{nthcdr}, and
15681 @code{substring} in conjunction with an existing function called
15682 @code{directory-files-and-attributes}. This latter function not only
15683 lists all the filenames in a directory, including the names
15684 of sub-directories, but also their attributes.
15686 To restate our goal: to create a function that will enable us
15687 to feed filenames to @code{recursive-lengths-list-many-files}
15688 as a list that looks like this (but with more elements):
15692 ("./lisp/macros.el"
15693 "./lisp/mail/rmail.el"
15694 "./lisp/makesum.el")
15698 The @code{directory-files-and-attributes} function returns a list of
15699 lists. Each of the lists within the main list consists of 13
15700 elements. The first element is a string that contains the name of the
15701 file -- which, in GNU/Linux, may be a `directory file', that is to
15702 say, a file with the special attributes of a directory. The second
15703 element of the list is @code{t} for a directory, a string
15704 for symbolic link (the string is the name linked to), or @code{nil}.
15706 For example, the first @samp{.el} file in the @file{lisp/} directory
15707 is @file{abbrev.el}. Its name is
15708 @file{/usr/local/share/emacs/22.0.100/lisp/abbrev.el} and it is not a
15709 directory or a symbolic link.
15712 This is how @code{directory-files-and-attributes} lists that file and
15738 On the other hand, @file{mail/} is a directory within the @file{lisp/}
15739 directory. The beginning of its listing looks like this:
15750 (To learn about the different attributes, look at the documentation of
15751 @code{file-attributes}. Bear in mind that the @code{file-attributes}
15752 function does not list the filename, so its first element is
15753 @code{directory-files-and-attributes}'s second element.)
15755 We will want our new function, @code{files-in-below-directory}, to
15756 list the @samp{.el} files in the directory it is told to check, and in
15757 any directories below that directory.
15759 This gives us a hint on how to construct
15760 @code{files-in-below-directory}: within a directory, the function
15761 should add @samp{.el} filenames to a list; and if, within a directory,
15762 the function comes upon a sub-directory, it should go into that
15763 sub-directory and repeat its actions.
15765 However, we should note that every directory contains a name that
15766 refers to itself, called @file{.}, (``dot'') and a name that refers to
15767 its parent directory, called @file{..} (``double dot''). (In
15768 @file{/}, the root directory, @file{..} refers to itself, since
15769 @file{/} has no parent.) Clearly, we do not want our
15770 @code{files-in-below-directory} function to enter those directories,
15771 since they always lead us, directly or indirectly, to the current
15774 Consequently, our @code{files-in-below-directory} function must do
15779 Check to see whether it is looking at a filename that ends in
15780 @samp{.el}; and if so, add its name to a list.
15783 Check to see whether it is looking at a filename that is the name of a
15784 directory; and if so,
15788 Check to see whether it is looking at @file{.} or @file{..}; and if
15792 Or else, go into that directory and repeat the process.
15796 Let's write a function definition to do these tasks. We will use a
15797 @code{while} loop to move from one filename to another within a
15798 directory, checking what needs to be done; and we will use a recursive
15799 call to repeat the actions on each sub-directory. The recursive
15800 pattern is `accumulate'
15801 (@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}),
15802 using @code{append} as the combiner.
15805 (directory-files "/usr/local/src/emacs/lisp/" t "\\.el$")
15806 (shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'")
15808 (directory-files "/usr/local/share/emacs/22.0.100/lisp/" t "\\.el$")
15809 (shell-command "find /usr/local/share/emacs/22.0.100/lisp/ -name '*.el'")
15812 @c /usr/local/share/emacs/22.0.100/lisp/
15815 Here is the function:
15819 (defun files-in-below-directory (directory)
15820 "List the .el files in DIRECTORY and in its sub-directories."
15821 ;; Although the function will be used non-interactively,
15822 ;; it will be easier to test if we make it interactive.
15823 ;; The directory will have a name such as
15824 ;; "/usr/local/share/emacs/22.0.100/lisp/"
15825 (interactive "DDirectory name: ")
15828 (let (el-files-list
15829 (current-directory-list
15830 (directory-files-and-attributes directory t)))
15831 ;; while we are in the current directory
15832 (while current-directory-list
15836 ;; check to see whether filename ends in `.el'
15837 ;; and if so, append its name to a list.
15838 ((equal ".el" (substring (car (car current-directory-list)) -3))
15839 (setq el-files-list
15840 (cons (car (car current-directory-list)) el-files-list)))
15843 ;; check whether filename is that of a directory
15844 ((eq t (car (cdr (car current-directory-list))))
15845 ;; decide whether to skip or recurse
15848 (substring (car (car current-directory-list)) -1))
15849 ;; then do nothing since filename is that of
15850 ;; current directory or parent, "." or ".."
15854 ;; else descend into the directory and repeat the process
15855 (setq el-files-list
15857 (files-in-below-directory
15858 (car (car current-directory-list)))
15860 ;; move to the next filename in the list; this also
15861 ;; shortens the list so the while loop eventually comes to an end
15862 (setq current-directory-list (cdr current-directory-list)))
15863 ;; return the filenames
15868 @c (files-in-below-directory "/usr/local/src/emacs/lisp/")
15869 @c (files-in-below-directory "/usr/local/share/emacs/22.0.100/lisp/")
15871 The @code{files-in-below-directory} @code{directory-files} function
15872 takes one argument, the name of a directory.
15875 Thus, on my system,
15877 @c (length (files-in-below-directory "/usr/local/src/emacs/lisp/"))
15879 @c !!! 22.0.100 lisp sources location here
15883 (files-in-below-directory "/usr/local/share/emacs/22.0.100/lisp/"))
15888 tells me that my Lisp sources directory contains 1031 @samp{.el}
15891 @code{files-in-below-directory} returns a list in reverse alphabetical
15892 order. An expression to sort the list in alphabetical order looks
15898 (files-in-below-directory "/usr/local/share/emacs/22.0.100/lisp/")
15905 "Test how long it takes to find lengths of all sorted elisp defuns."
15906 (insert "\n" (current-time-string) "\n")
15909 (recursive-lengths-list-many-files
15910 (files-in-below-directory "/usr/local/src/emacs/lisp/"))
15912 (insert (format "%s" (current-time-string))))
15915 @node Counting function definitions, , Files List, Prepare the data
15916 @subsection Counting function definitions
15918 Our immediate goal is to generate a list that tells us how many
15919 function definitions contain fewer than 10 words and symbols, how many
15920 contain between 10 and 19 words and symbols, how many contain between
15921 20 and 29 words and symbols, and so on.
15923 With a sorted list of numbers, this is easy: count how many elements
15924 of the list are smaller than 10, then, after moving past the numbers
15925 just counted, count how many are smaller than 20, then, after moving
15926 past the numbers just counted, count how many are smaller than 30, and
15927 so on. Each of the numbers, 10, 20, 30, 40, and the like, is one
15928 larger than the top of that range. We can call the list of such
15929 numbers the @code{top-of-ranges} list.
15932 If we wished, we could generate this list automatically, but it is
15933 simpler to write a list manually. Here it is:
15934 @vindex top-of-ranges
15938 (defvar top-of-ranges
15941 110 120 130 140 150
15942 160 170 180 190 200
15943 210 220 230 240 250
15944 260 270 280 290 300)
15945 "List specifying ranges for `defuns-per-range'.")
15949 To change the ranges, we edit this list.
15951 Next, we need to write the function that creates the list of the
15952 number of definitions within each range. Clearly, this function must
15953 take the @code{sorted-lengths} and the @code{top-of-ranges} lists
15956 The @code{defuns-per-range} function must do two things again and
15957 again: it must count the number of definitions within a range
15958 specified by the current top-of-range value; and it must shift to the
15959 next higher value in the @code{top-of-ranges} list after counting the
15960 number of definitions in the current range. Since each of these
15961 actions is repetitive, we can use @code{while} loops for the job.
15962 One loop counts the number of definitions in the range defined by the
15963 current top-of-range value, and the other loop selects each of the
15964 top-of-range values in turn.
15966 Several entries of the @code{sorted-lengths} list are counted for each
15967 range; this means that the loop for the @code{sorted-lengths} list
15968 will be inside the loop for the @code{top-of-ranges} list, like a
15969 small gear inside a big gear.
15971 The inner loop counts the number of definitions within the range. It
15972 is a simple counting loop of the type we have seen before.
15973 (@xref{Incrementing Loop, , A loop with an incrementing counter}.)
15974 The true-or-false test of the loop tests whether the value from the
15975 @code{sorted-lengths} list is smaller than the current value of the
15976 top of the range. If it is, the function increments the counter and
15977 tests the next value from the @code{sorted-lengths} list.
15980 The inner loop looks like this:
15984 (while @var{length-element-smaller-than-top-of-range}
15985 (setq number-within-range (1+ number-within-range))
15986 (setq sorted-lengths (cdr sorted-lengths)))
15990 The outer loop must start with the lowest value of the
15991 @code{top-of-ranges} list, and then be set to each of the succeeding
15992 higher values in turn. This can be done with a loop like this:
15996 (while top-of-ranges
15997 @var{body-of-loop}@dots{}
15998 (setq top-of-ranges (cdr top-of-ranges)))
16003 Put together, the two loops look like this:
16007 (while top-of-ranges
16009 ;; @r{Count the number of elements within the current range.}
16010 (while @var{length-element-smaller-than-top-of-range}
16011 (setq number-within-range (1+ number-within-range))
16012 (setq sorted-lengths (cdr sorted-lengths)))
16014 ;; @r{Move to next range.}
16015 (setq top-of-ranges (cdr top-of-ranges)))
16019 In addition, in each circuit of the outer loop, Emacs should record
16020 the number of definitions within that range (the value of
16021 @code{number-within-range}) in a list. We can use @code{cons} for
16022 this purpose. (@xref{cons, , @code{cons}}.)
16024 The @code{cons} function works fine, except that the list it
16025 constructs will contain the number of definitions for the highest
16026 range at its beginning and the number of definitions for the lowest
16027 range at its end. This is because @code{cons} attaches new elements
16028 of the list to the beginning of the list, and since the two loops are
16029 working their way through the lengths' list from the lower end first,
16030 the @code{defuns-per-range-list} will end up largest number first.
16031 But we will want to print our graph with smallest values first and the
16032 larger later. The solution is to reverse the order of the
16033 @code{defuns-per-range-list}. We can do this using the
16034 @code{nreverse} function, which reverses the order of a list.
16041 (nreverse '(1 2 3 4))
16052 Note that the @code{nreverse} function is ``destructive''---that is,
16053 it changes the list to which it is applied; this contrasts with the
16054 @code{car} and @code{cdr} functions, which are non-destructive. In
16055 this case, we do not want the original @code{defuns-per-range-list},
16056 so it does not matter that it is destroyed. (The @code{reverse}
16057 function provides a reversed copy of a list, leaving the original list
16062 Put all together, the @code{defuns-per-range} looks like this:
16066 (defun defuns-per-range (sorted-lengths top-of-ranges)
16067 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
16068 (let ((top-of-range (car top-of-ranges))
16069 (number-within-range 0)
16070 defuns-per-range-list)
16075 (while top-of-ranges
16081 ;; @r{Need number for numeric test.}
16082 (car sorted-lengths)
16083 (< (car sorted-lengths) top-of-range))
16087 ;; @r{Count number of definitions within current range.}
16088 (setq number-within-range (1+ number-within-range))
16089 (setq sorted-lengths (cdr sorted-lengths)))
16091 ;; @r{Exit inner loop but remain within outer loop.}
16095 (setq defuns-per-range-list
16096 (cons number-within-range defuns-per-range-list))
16097 (setq number-within-range 0) ; @r{Reset count to zero.}
16101 ;; @r{Move to next range.}
16102 (setq top-of-ranges (cdr top-of-ranges))
16103 ;; @r{Specify next top of range value.}
16104 (setq top-of-range (car top-of-ranges)))
16108 ;; @r{Exit outer loop and count the number of defuns larger than}
16109 ;; @r{ the largest top-of-range value.}
16110 (setq defuns-per-range-list
16112 (length sorted-lengths)
16113 defuns-per-range-list))
16117 ;; @r{Return a list of the number of definitions within each range,}
16118 ;; @r{ smallest to largest.}
16119 (nreverse defuns-per-range-list)))
16125 The function is straightforward except for one subtle feature. The
16126 true-or-false test of the inner loop looks like this:
16130 (and (car sorted-lengths)
16131 (< (car sorted-lengths) top-of-range))
16137 instead of like this:
16140 (< (car sorted-lengths) top-of-range)
16143 The purpose of the test is to determine whether the first item in the
16144 @code{sorted-lengths} list is less than the value of the top of the
16147 The simple version of the test works fine unless the
16148 @code{sorted-lengths} list has a @code{nil} value. In that case, the
16149 @code{(car sorted-lengths)} expression function returns
16150 @code{nil}. The @code{<} function cannot compare a number to
16151 @code{nil}, which is an empty list, so Emacs signals an error and
16152 stops the function from attempting to continue to execute.
16154 The @code{sorted-lengths} list always becomes @code{nil} when the
16155 counter reaches the end of the list. This means that any attempt to
16156 use the @code{defuns-per-range} function with the simple version of
16157 the test will fail.
16159 We solve the problem by using the @code{(car sorted-lengths)}
16160 expression in conjunction with the @code{and} expression. The
16161 @code{(car sorted-lengths)} expression returns a non-@code{nil}
16162 value so long as the list has at least one number within it, but
16163 returns @code{nil} if the list is empty. The @code{and} expression
16164 first evaluates the @code{(car sorted-lengths)} expression, and
16165 if it is @code{nil}, returns false @emph{without} evaluating the
16166 @code{<} expression. But if the @code{(car sorted-lengths)}
16167 expression returns a non-@code{nil} value, the @code{and} expression
16168 evaluates the @code{<} expression, and returns that value as the value
16169 of the @code{and} expression.
16171 @c colon in printed section title causes problem in Info cross reference
16172 This way, we avoid an error.
16175 (For information about @code{and}, see
16176 @ref{kill-new function, , The @code{kill-new} function}.)
16180 (@xref{kill-new function, , The @code{kill-new} function}, for
16181 information about @code{and}.)
16184 Here is a short test of the @code{defuns-per-range} function. First,
16185 evaluate the expression that binds (a shortened)
16186 @code{top-of-ranges} list to the list of values, then evaluate the
16187 expression for binding the @code{sorted-lengths} list, and then
16188 evaluate the @code{defuns-per-range} function.
16192 ;; @r{(Shorter list than we will use later.)}
16193 (setq top-of-ranges
16194 '(110 120 130 140 150
16195 160 170 180 190 200))
16197 (setq sorted-lengths
16198 '(85 86 110 116 122 129 154 176 179 200 265 300 300))
16200 (defuns-per-range sorted-lengths top-of-ranges)
16206 The list returned looks like this:
16209 (2 2 2 0 0 1 0 2 0 0 4)
16213 Indeed, there are two elements of the @code{sorted-lengths} list
16214 smaller than 110, two elements between 110 and 119, two elements
16215 between 120 and 129, and so on. There are four elements with a value
16218 @c The next step is to turn this numbers' list into a graph.
16219 @node Readying a Graph, Emacs Initialization, Words in a defun, Top
16220 @chapter Readying a Graph
16221 @cindex Readying a graph
16222 @cindex Graph prototype
16223 @cindex Prototype graph
16224 @cindex Body of graph
16226 Our goal is to construct a graph showing the numbers of function
16227 definitions of various lengths in the Emacs lisp sources.
16229 As a practical matter, if you were creating a graph, you would
16230 probably use a program such as @code{gnuplot} to do the job.
16231 (@code{gnuplot} is nicely integrated into GNU Emacs.) In this case,
16232 however, we create one from scratch, and in the process we will
16233 re-acquaint ourselves with some of what we learned before and learn
16236 In this chapter, we will first write a simple graph printing function.
16237 This first definition will be a @dfn{prototype}, a rapidly written
16238 function that enables us to reconnoiter this unknown graph-making
16239 territory. We will discover dragons, or find that they are myth.
16240 After scouting the terrain, we will feel more confident and enhance
16241 the function to label the axes automatically.
16244 * Columns of a graph::
16245 * graph-body-print::
16246 * recursive-graph-body-print::
16248 * Line Graph Exercise::
16251 @node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph
16253 @unnumberedsec Printing the Columns of a Graph
16256 Since Emacs is designed to be flexible and work with all kinds of
16257 terminals, including character-only terminals, the graph will need to
16258 be made from one of the `typewriter' symbols. An asterisk will do; as
16259 we enhance the graph-printing function, we can make the choice of
16260 symbol a user option.
16262 We can call this function @code{graph-body-print}; it will take a
16263 @code{numbers-list} as its only argument. At this stage, we will not
16264 label the graph, but only print its body.
16266 The @code{graph-body-print} function inserts a vertical column of
16267 asterisks for each element in the @code{numbers-list}. The height of
16268 each line is determined by the value of that element of the
16269 @code{numbers-list}.
16271 Inserting columns is a repetitive act; that means that this function can
16272 be written either with a @code{while} loop or recursively.
16274 Our first challenge is to discover how to print a column of asterisks.
16275 Usually, in Emacs, we print characters onto a screen horizontally,
16276 line by line, by typing. We have two routes we can follow: write our
16277 own column-insertion function or discover whether one exists in Emacs.
16279 To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
16280 command. This command is like the @kbd{C-h a} (@code{command-apropos})
16281 command, except that the latter finds only those functions that are
16282 commands. The @kbd{M-x apropos} command lists all symbols that match
16283 a regular expression, including functions that are not interactive.
16286 What we want to look for is some command that prints or inserts
16287 columns. Very likely, the name of the function will contain either
16288 the word `print' or the word `insert' or the word `column'.
16289 Therefore, we can simply type @kbd{M-x apropos RET
16290 print\|insert\|column RET} and look at the result. On my system, this
16291 command once too takes quite some time, and then produced a list of 79
16292 functions and variables. Now it does not take much time at all and
16293 produces a list of 211 functions and variables. Scanning down the
16294 list, the only function that looks as if it might do the job is
16295 @code{insert-rectangle}.
16298 Indeed, this is the function we want; its documentation says:
16303 Insert text of RECTANGLE with upper left corner at point.
16304 RECTANGLE's first line is inserted at point,
16305 its second line is inserted at a point vertically under point, etc.
16306 RECTANGLE should be a list of strings.
16307 After this command, the mark is at the upper left corner
16308 and point is at the lower right corner.
16312 We can run a quick test, to make sure it does what we expect of it.
16314 Here is the result of placing the cursor after the
16315 @code{insert-rectangle} expression and typing @kbd{C-u C-x C-e}
16316 (@code{eval-last-sexp}). The function inserts the strings
16317 @samp{"first"}, @samp{"second"}, and @samp{"third"} at and below
16318 point. Also the function returns @code{nil}.
16322 (insert-rectangle '("first" "second" "third"))first
16329 Of course, we won't be inserting the text of the
16330 @code{insert-rectangle} expression itself into the buffer in which we
16331 are making the graph, but will call the function from our program. We
16332 shall, however, have to make sure that point is in the buffer at the
16333 place where the @code{insert-rectangle} function will insert its
16336 If you are reading this in Info, you can see how this works by
16337 switching to another buffer, such as the @file{*scratch*} buffer,
16338 placing point somewhere in the buffer, typing @kbd{M-:}, typing the
16339 @code{insert-rectangle} expression into the minibuffer at the prompt,
16340 and then typing @key{RET}. This causes Emacs to evaluate the
16341 expression in the minibuffer, but to use as the value of point the
16342 position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the
16343 keybinding for @code{eval-expression}. Also, @code{nil} does not
16344 appear in the @file{*scratch*} buffer since the expression is
16345 evaluated in the minibuffer.)
16347 We find when we do this that point ends up at the end of the last
16348 inserted line---that is to say, this function moves point as a
16349 side-effect. If we were to repeat the command, with point at this
16350 position, the next insertion would be below and to the right of the
16351 previous insertion. We don't want this! If we are going to make a
16352 bar graph, the columns need to be beside each other.
16354 So we discover that each cycle of the column-inserting @code{while}
16355 loop must reposition point to the place we want it, and that place
16356 will be at the top, not the bottom, of the column. Moreover, we
16357 remember that when we print a graph, we do not expect all the columns
16358 to be the same height. This means that the top of each column may be
16359 at a different height from the previous one. We cannot simply
16360 reposition point to the same line each time, but moved over to the
16361 right---or perhaps we can@dots{}
16363 We are planning to make the columns of the bar graph out of asterisks.
16364 The number of asterisks in the column is the number specified by the
16365 current element of the @code{numbers-list}. We need to construct a
16366 list of asterisks of the right length for each call to
16367 @code{insert-rectangle}. If this list consists solely of the requisite
16368 number of asterisks, then we will have position point the right number
16369 of lines above the base for the graph to print correctly. This could
16372 Alternatively, if we can figure out some way to pass
16373 @code{insert-rectangle} a list of the same length each time, then we
16374 can place point on the same line each time, but move it over one
16375 column to the right for each new column. If we do this, however, some
16376 of the entries in the list passed to @code{insert-rectangle} must be
16377 blanks rather than asterisks. For example, if the maximum height of
16378 the graph is 5, but the height of the column is 3, then
16379 @code{insert-rectangle} requires an argument that looks like this:
16382 (" " " " "*" "*" "*")
16385 This last proposal is not so difficult, so long as we can determine
16386 the column height. There are two ways for us to specify the column
16387 height: we can arbitrarily state what it will be, which would work
16388 fine for graphs of that height; or we can search through the list of
16389 numbers and use the maximum height of the list as the maximum height
16390 of the graph. If the latter operation were difficult, then the former
16391 procedure would be easiest, but there is a function built into Emacs
16392 that determines the maximum of its arguments. We can use that
16393 function. The function is called @code{max} and it returns the
16394 largest of all its arguments, which must be numbers. Thus, for
16402 returns 7. (A corresponding function called @code{min} returns the
16403 smallest of all its arguments.)
16407 However, we cannot simply call @code{max} on the @code{numbers-list};
16408 the @code{max} function expects numbers as its argument, not a list of
16409 numbers. Thus, the following expression,
16412 (max '(3 4 6 5 7 3))
16417 produces the following error message;
16420 Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3)
16424 We need a function that passes a list of arguments to a function.
16425 This function is @code{apply}. This function `applies' its first
16426 argument (a function) to its remaining arguments, the last of which
16433 (apply 'max 3 4 7 3 '(4 8 5))
16439 (Incidentally, I don't know how you would learn of this function
16440 without a book such as this. It is possible to discover other
16441 functions, like @code{search-forward} or @code{insert-rectangle}, by
16442 guessing at a part of their names and then using @code{apropos}. Even
16443 though its base in metaphor is clear---`apply' its first argument to
16444 the rest---I doubt a novice would come up with that particular word
16445 when using @code{apropos} or other aid. Of course, I could be wrong;
16446 after all, the function was first named by someone who had to invent
16449 The second and subsequent arguments to @code{apply} are optional, so
16450 we can use @code{apply} to call a function and pass the elements of a
16451 list to it, like this, which also returns 8:
16454 (apply 'max '(4 8 5))
16457 This latter way is how we will use @code{apply}. The
16458 @code{recursive-lengths-list-many-files} function returns a numbers'
16459 list to which we can apply @code{max} (we could also apply @code{max} to
16460 the sorted numbers' list; it does not matter whether the list is
16464 Hence, the operation for finding the maximum height of the graph is this:
16467 (setq max-graph-height (apply 'max numbers-list))
16470 Now we can return to the question of how to create a list of strings
16471 for a column of the graph. Told the maximum height of the graph
16472 and the number of asterisks that should appear in the column, the
16473 function should return a list of strings for the
16474 @code{insert-rectangle} command to insert.
16476 Each column is made up of asterisks or blanks. Since the function is
16477 passed the value of the height of the column and the number of
16478 asterisks in the column, the number of blanks can be found by
16479 subtracting the number of asterisks from the height of the column.
16480 Given the number of blanks and the number of asterisks, two
16481 @code{while} loops can be used to construct the list:
16485 ;;; @r{First version.}
16486 (defun column-of-graph (max-graph-height actual-height)
16487 "Return list of strings that is one column of a graph."
16488 (let ((insert-list nil)
16489 (number-of-top-blanks
16490 (- max-graph-height actual-height)))
16494 ;; @r{Fill in asterisks.}
16495 (while (> actual-height 0)
16496 (setq insert-list (cons "*" insert-list))
16497 (setq actual-height (1- actual-height)))
16501 ;; @r{Fill in blanks.}
16502 (while (> number-of-top-blanks 0)
16503 (setq insert-list (cons " " insert-list))
16504 (setq number-of-top-blanks
16505 (1- number-of-top-blanks)))
16509 ;; @r{Return whole list.}
16514 If you install this function and then evaluate the following
16515 expression you will see that it returns the list as desired:
16518 (column-of-graph 5 3)
16526 (" " " " "*" "*" "*")
16529 As written, @code{column-of-graph} contains a major flaw: the symbols
16530 used for the blank and for the marked entries in the column are
16531 `hard-coded' as a space and asterisk. This is fine for a prototype,
16532 but you, or another user, may wish to use other symbols. For example,
16533 in testing the graph function, you many want to use a period in place
16534 of the space, to make sure the point is being repositioned properly
16535 each time the @code{insert-rectangle} function is called; or you might
16536 want to substitute a @samp{+} sign or other symbol for the asterisk.
16537 You might even want to make a graph-column that is more than one
16538 display column wide. The program should be more flexible. The way to
16539 do that is to replace the blank and the asterisk with two variables
16540 that we can call @code{graph-blank} and @code{graph-symbol} and define
16541 those variables separately.
16543 Also, the documentation is not well written. These considerations
16544 lead us to the second version of the function:
16548 (defvar graph-symbol "*"
16549 "String used as symbol in graph, usually an asterisk.")
16553 (defvar graph-blank " "
16554 "String used as blank in graph, usually a blank space.
16555 graph-blank must be the same number of columns wide
16561 (For an explanation of @code{defvar}, see
16562 @ref{defvar, , Initializing a Variable with @code{defvar}}.)
16566 ;;; @r{Second version.}
16567 (defun column-of-graph (max-graph-height actual-height)
16568 "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols.
16572 The graph-symbols are contiguous entries at the end
16574 The list will be inserted as one column of a graph.
16575 The strings are either graph-blank or graph-symbol."
16579 (let ((insert-list nil)
16580 (number-of-top-blanks
16581 (- max-graph-height actual-height)))
16585 ;; @r{Fill in @code{graph-symbols}.}
16586 (while (> actual-height 0)
16587 (setq insert-list (cons graph-symbol insert-list))
16588 (setq actual-height (1- actual-height)))
16592 ;; @r{Fill in @code{graph-blanks}.}
16593 (while (> number-of-top-blanks 0)
16594 (setq insert-list (cons graph-blank insert-list))
16595 (setq number-of-top-blanks
16596 (1- number-of-top-blanks)))
16598 ;; @r{Return whole list.}
16603 If we wished, we could rewrite @code{column-of-graph} a third time to
16604 provide optionally for a line graph as well as for a bar graph. This
16605 would not be hard to do. One way to think of a line graph is that it
16606 is no more than a bar graph in which the part of each bar that is
16607 below the top is blank. To construct a column for a line graph, the
16608 function first constructs a list of blanks that is one shorter than
16609 the value, then it uses @code{cons} to attach a graph symbol to the
16610 list; then it uses @code{cons} again to attach the `top blanks' to
16613 It is easy to see how to write such a function, but since we don't
16614 need it, we will not do it. But the job could be done, and if it were
16615 done, it would be done with @code{column-of-graph}. Even more
16616 important, it is worth noting that few changes would have to be made
16617 anywhere else. The enhancement, if we ever wish to make it, is
16620 Now, finally, we come to our first actual graph printing function.
16621 This prints the body of a graph, not the labels for the vertical and
16622 horizontal axes, so we can call this @code{graph-body-print}.
16624 @node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph
16625 @section The @code{graph-body-print} Function
16626 @findex graph-body-print
16628 After our preparation in the preceding section, the
16629 @code{graph-body-print} function is straightforward. The function
16630 will print column after column of asterisks and blanks, using the
16631 elements of a numbers' list to specify the number of asterisks in each
16632 column. This is a repetitive act, which means we can use a
16633 decrementing @code{while} loop or recursive function for the job. In
16634 this section, we will write the definition using a @code{while} loop.
16636 The @code{column-of-graph} function requires the height of the graph
16637 as an argument, so we should determine and record that as a local variable.
16639 This leads us to the following template for the @code{while} loop
16640 version of this function:
16644 (defun graph-body-print (numbers-list)
16645 "@var{documentation}@dots{}"
16646 (let ((height @dots{}
16651 (while numbers-list
16652 @var{insert-columns-and-reposition-point}
16653 (setq numbers-list (cdr numbers-list)))))
16658 We need to fill in the slots of the template.
16660 Clearly, we can use the @code{(apply 'max numbers-list)} expression to
16661 determine the height of the graph.
16663 The @code{while} loop will cycle through the @code{numbers-list} one
16664 element at a time. As it is shortened by the @code{(setq numbers-list
16665 (cdr numbers-list))} expression, the @sc{car} of each instance of the
16666 list is the value of the argument for @code{column-of-graph}.
16668 At each cycle of the @code{while} loop, the @code{insert-rectangle}
16669 function inserts the list returned by @code{column-of-graph}. Since
16670 the @code{insert-rectangle} function moves point to the lower right of
16671 the inserted rectangle, we need to save the location of point at the
16672 time the rectangle is inserted, move back to that position after the
16673 rectangle is inserted, and then move horizontally to the next place
16674 from which @code{insert-rectangle} is called.
16676 If the inserted columns are one character wide, as they will be if
16677 single blanks and asterisks are used, the repositioning command is
16678 simply @code{(forward-char 1)}; however, the width of a column may be
16679 greater than one. This means that the repositioning command should be
16680 written @code{(forward-char symbol-width)}. The @code{symbol-width}
16681 itself is the length of a @code{graph-blank} and can be found using
16682 the expression @code{(length graph-blank)}. The best place to bind
16683 the @code{symbol-width} variable to the value of the width of graph
16684 column is in the varlist of the @code{let} expression.
16687 These considerations lead to the following function definition:
16691 (defun graph-body-print (numbers-list)
16692 "Print a bar graph of the NUMBERS-LIST.
16693 The numbers-list consists of the Y-axis values."
16695 (let ((height (apply 'max numbers-list))
16696 (symbol-width (length graph-blank))
16701 (while numbers-list
16702 (setq from-position (point))
16704 (column-of-graph height (car numbers-list)))
16705 (goto-char from-position)
16706 (forward-char symbol-width)
16709 ;; @r{Draw graph column by column.}
16711 (setq numbers-list (cdr numbers-list)))
16714 ;; @r{Place point for X axis labels.}
16715 (forward-line height)
16722 The one unexpected expression in this function is the
16723 @w{@code{(sit-for 0)}} expression in the @code{while} loop. This
16724 expression makes the graph printing operation more interesting to
16725 watch than it would be otherwise. The expression causes Emacs to
16726 `sit' or do nothing for a zero length of time and then redraw the
16727 screen. Placed here, it causes Emacs to redraw the screen column by
16728 column. Without it, Emacs would not redraw the screen until the
16731 We can test @code{graph-body-print} with a short list of numbers.
16735 Install @code{graph-symbol}, @code{graph-blank},
16736 @code{column-of-graph}, which are in
16738 @ref{Readying a Graph, , Readying a Graph},
16741 @ref{Columns of a graph},
16743 and @code{graph-body-print}.
16747 Copy the following expression:
16750 (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3))
16754 Switch to the @file{*scratch*} buffer and place the cursor where you
16755 want the graph to start.
16758 Type @kbd{M-:} (@code{eval-expression}).
16761 Yank the @code{graph-body-print} expression into the minibuffer
16762 with @kbd{C-y} (@code{yank)}.
16765 Press @key{RET} to evaluate the @code{graph-body-print} expression.
16769 Emacs will print a graph like this:
16783 @node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph
16784 @section The @code{recursive-graph-body-print} Function
16785 @findex recursive-graph-body-print
16787 The @code{graph-body-print} function may also be written recursively.
16788 The recursive solution is divided into two parts: an outside `wrapper'
16789 that uses a @code{let} expression to determine the values of several
16790 variables that need only be found once, such as the maximum height of
16791 the graph, and an inside function that is called recursively to print
16795 The `wrapper' is uncomplicated:
16799 (defun recursive-graph-body-print (numbers-list)
16800 "Print a bar graph of the NUMBERS-LIST.
16801 The numbers-list consists of the Y-axis values."
16802 (let ((height (apply 'max numbers-list))
16803 (symbol-width (length graph-blank))
16805 (recursive-graph-body-print-internal
16812 The recursive function is a little more difficult. It has four parts:
16813 the `do-again-test', the printing code, the recursive call, and the
16814 `next-step-expression'. The `do-again-test' is an @code{if}
16815 expression that determines whether the @code{numbers-list} contains
16816 any remaining elements; if it does, the function prints one column of
16817 the graph using the printing code and calls itself again. The
16818 function calls itself again according to the value produced by the
16819 `next-step-expression' which causes the call to act on a shorter
16820 version of the @code{numbers-list}.
16824 (defun recursive-graph-body-print-internal
16825 (numbers-list height symbol-width)
16826 "Print a bar graph.
16827 Used within recursive-graph-body-print function."
16833 (setq from-position (point))
16835 (column-of-graph height (car numbers-list)))
16838 (goto-char from-position)
16839 (forward-char symbol-width)
16840 (sit-for 0) ; @r{Draw graph column by column.}
16841 (recursive-graph-body-print-internal
16842 (cdr numbers-list) height symbol-width))))
16847 After installation, this expression can be tested; here is a sample:
16850 (recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1))
16854 Here is what @code{recursive-graph-body-print} produces:
16868 Either of these two functions, @code{graph-body-print} or
16869 @code{recursive-graph-body-print}, create the body of a graph.
16871 @node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph
16872 @section Need for Printed Axes
16874 A graph needs printed axes, so you can orient yourself. For a do-once
16875 project, it may be reasonable to draw the axes by hand using Emacs'
16876 Picture mode; but a graph drawing function may be used more than once.
16878 For this reason, I have written enhancements to the basic
16879 @code{print-graph-body} function that automatically print labels for
16880 the horizontal and vertical axes. Since the label printing functions
16881 do not contain much new material, I have placed their description in
16882 an appendix. @xref{Full Graph, , A Graph with Labelled Axes}.
16884 @node Line Graph Exercise, , Printed Axes, Readying a Graph
16887 Write a line graph version of the graph printing functions.
16889 @node Emacs Initialization, Debugging, Readying a Graph, Top
16890 @chapter Your @file{.emacs} File
16891 @cindex @file{.emacs} file
16892 @cindex Customizing your @file{.emacs} file
16893 @cindex Initialization file
16895 ``You don't have to like Emacs to like it'' -- this seemingly
16896 paradoxical statement is the secret of GNU Emacs. The plain, `out of
16897 the box' Emacs is a generic tool. Most people who use it, customize
16898 it to suit themselves.
16900 GNU Emacs is mostly written in Emacs Lisp; this means that by writing
16901 expressions in Emacs Lisp you can change or extend Emacs.
16904 * Default Configuration::
16907 * Beginning a .emacs File::
16908 * Text and Auto-fill::
16910 * Indent Tabs Mode::
16915 * Simple Extension::
16921 @node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization
16923 @unnumberedsec Emacs' Default Configuration
16926 There are those who appreciate Emacs' default configuration. After
16927 all, Emacs starts you in C mode when you edit a C file, starts you in
16928 Fortran mode when you edit a Fortran file, and starts you in
16929 Fundamental mode when you edit an unadorned file. This all makes
16930 sense, if you do not know who is going to use Emacs. Who knows what a
16931 person hopes to do with an unadorned file? Fundamental mode is the
16932 right default for such a file, just as C mode is the right default for
16933 editing C code. (Enough programming languages have syntaxes
16934 that enable them to share or nearly share features, so C mode is
16935 now provided by by CC mode, the `C Collection'.)
16937 But when you do know who is going to use Emacs---you,
16938 yourself---then it makes sense to customize Emacs.
16940 For example, I seldom want Fundamental mode when I edit an
16941 otherwise undistinguished file; I want Text mode. This is why I
16942 customize Emacs: so it suits me.
16944 You can customize and extend Emacs by writing or adapting a
16945 @file{~/.emacs} file. This is your personal initialization file; its
16946 contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You
16947 may also add @file{.el} to @file{~/.emacs} and call it a
16948 @file{~/.emacs.el} file. In the past, you were forbidden to type the
16949 extra keystrokes that the name @file{~/.emacs.el} requires, but now
16950 you may. The new format is consistent with the Emacs Lisp file
16951 naming conventions; the old format saves typing.}
16953 A @file{~/.emacs} file contains Emacs Lisp code. You can write this
16954 code yourself; or you can use Emacs' @code{customize} feature to write
16955 the code for you. You can combine your own expressions and
16956 auto-written Customize expressions in your @file{.emacs} file.
16958 (I myself prefer to write my own expressions, except for those,
16959 particularly fonts, that I find easier to manipulate using the
16960 @code{customize} command. I combine the two methods.)
16962 Most of this chapter is about writing expressions yourself. It
16963 describes a simple @file{.emacs} file; for more information, see
16964 @ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and
16965 @ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference
16968 @node Site-wide Init, defcustom, Default Configuration, Emacs Initialization
16969 @section Site-wide Initialization Files
16971 @cindex @file{default.el} init file
16972 @cindex @file{site-init.el} init file
16973 @cindex @file{site-load.el} init file
16974 In addition to your personal initialization file, Emacs automatically
16975 loads various site-wide initialization files, if they exist. These
16976 have the same form as your @file{.emacs} file, but are loaded by
16979 Two site-wide initialization files, @file{site-load.el} and
16980 @file{site-init.el}, are loaded into Emacs and then `dumped' if a
16981 `dumped' version of Emacs is created, as is most common. (Dumped
16982 copies of Emacs load more quickly. However, once a file is loaded and
16983 dumped, a change to it does not lead to a change in Emacs unless you
16984 load it yourself or re-dump Emacs. @xref{Building Emacs, , Building
16985 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the
16986 @file{INSTALL} file.)
16988 Three other site-wide initialization files are loaded automatically
16989 each time you start Emacs, if they exist. These are
16990 @file{site-start.el}, which is loaded @emph{before} your @file{.emacs}
16991 file, and @file{default.el}, and the terminal type file, which are both
16992 loaded @emph{after} your @file{.emacs} file.
16994 Settings and definitions in your @file{.emacs} file will overwrite
16995 conflicting settings and definitions in a @file{site-start.el} file,
16996 if it exists; but the settings and definitions in a @file{default.el}
16997 or terminal type file will overwrite those in your @file{.emacs} file.
16998 (You can prevent interference from a terminal type file by setting
16999 @code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A
17000 Simple Extension}.)
17002 @c Rewritten to avoid overfull hbox.
17003 The @file{INSTALL} file that comes in the distribution contains
17004 descriptions of the @file{site-init.el} and @file{site-load.el} files.
17006 The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files
17007 control loading. These files are in the @file{lisp} directory of the
17008 Emacs distribution and are worth perusing.
17010 The @file{loaddefs.el} file contains a good many suggestions as to
17011 what to put into your own @file{.emacs} file, or into a site-wide
17012 initialization file.
17014 @node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization
17015 @section Specifying Variables using @code{defcustom}
17018 You can specify variables using @code{defcustom} so that you and
17019 others can then use Emacs' @code{customize} feature to set their
17020 values. (You cannot use @code{customize} to write function
17021 definitions; but you can write @code{defuns} in your @file{.emacs}
17022 file. Indeed, you can write any Lisp expression in your @file{.emacs}
17025 The @code{customize} feature depends on the @code{defcustom} special
17026 form. Although you can use @code{defvar} or @code{setq} for variables
17027 that users set, the @code{defcustom} special form is designed for the
17030 You can use your knowledge of @code{defvar} for writing the
17031 first three arguments for @code{defcustom}. The first argument to
17032 @code{defcustom} is the name of the variable. The second argument is
17033 the variable's initial value, if any; and this value is set only if
17034 the value has not already been set. The third argument is the
17037 The fourth and subsequent arguments to @code{defcustom} specify types
17038 and options; these are not featured in @code{defvar}. (These
17039 arguments are optional.)
17041 Each of these arguments consists of a keyword followed by a value.
17042 Each keyword starts with the colon character @samp{:}.
17045 For example, the customizable user option variable
17046 @code{text-mode-hook} looks like this:
17050 (defcustom text-mode-hook nil
17051 "Normal hook run when entering Text mode and many related modes."
17053 :options '(turn-on-auto-fill flyspell-mode)
17059 The name of the variable is @code{text-mode-hook}; it has no default
17060 value; and its documentation string tells you what it does.
17062 The @code{:type} keyword tells Emacs the kind of data to which
17063 @code{text-mode-hook} should be set and how to display the value in a
17064 Customization buffer.
17066 The @code{:options} keyword specifies a suggested list of values for
17067 the variable. Currently, you can use @code{:options} only for a hook.
17068 The list is only a suggestion; it is not exclusive; a person who sets
17069 the variable may set it to other values; the list shown following the
17070 @code{:options} keyword is intended to offer convenient choices to a
17073 Finally, the @code{:group} keyword tells the Emacs Customization
17074 command in which group the variable is located. This tells where to
17077 For more information, see @ref{Customization, , Writing Customization
17078 Definitions, elisp, The GNU Emacs Lisp Reference Manual}.
17080 Consider @code{text-mode-hook} as an example.
17082 There are two ways to customize this variable. You can use the
17083 customization command or write the appropriate expressions yourself.
17086 Using the customization command, you can type:
17093 and find that the group for editing files of data is called `data'.
17094 Enter that group. Text Mode Hook is the first member. You can click
17095 on its various options, such as @code{turn-on-auto-fill}, to set the
17096 values. After you click on the button to
17099 Save for Future Sessions
17103 Emacs will write an expression into your @file{.emacs} file.
17104 It will look like this:
17108 (custom-set-variables
17109 ;; custom-set-variables was added by Custom.
17110 ;; If you edit it by hand, you could mess it up, so be careful.
17111 ;; Your init file should contain only one such instance.
17112 ;; If there is more than one, they won't work right.
17113 '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
17118 (The @code{text-mode-hook-identify} function tells
17119 @code{toggle-text-mode-auto-fill} which buffers are in Text mode.
17120 It comes on automatically.
17123 The @code{custom-set-variables} function works somewhat differently
17124 than a @code{setq}. While I have never learned the differences, I
17125 modify the @code{custom-set-variables} expressions in my @file{.emacs}
17126 file by hand: I make the changes in what appears to me to be a
17127 reasonable manner and have not had any problems. Others prefer to use
17128 the Customization command and let Emacs do the work for them.
17130 Another @code{custom-set-@dots{}} function is @code{custom-set-faces}.
17131 This function sets the various font faces. Over time, I have set a
17132 considerable number of faces. Some of the time, I re-set them using
17133 @code{customize}; other times, I simply edit the
17134 @code{custom-set-faces} expression in my @file{.emacs} file itself.
17136 The second way to customize your @code{text-mode-hook} is to set it
17137 yourself in your @file{.emacs} file using code that has nothing to do
17138 with the @code{custom-set-@dots{}} functions.
17141 When you do this, and later use @code{customize}, you will see a
17145 CHANGED outside Customize; operating on it here may be unreliable.
17149 This message is only a warning. If you click on the button to
17152 Save for Future Sessions
17156 Emacs will write a @code{custom-set-@dots{}} expression near the end
17157 of your @file{.emacs} file that will be evaluated after your
17158 hand-written expression. It will, therefore, overrule your
17159 hand-written expression. No harm will be done. When you do this,
17160 however, be careful to remember which expression is active; if you
17161 forget, you may confuse yourself.
17163 So long as you remember where the values are set, you will have no
17164 trouble. In any event, the values are always set in your
17165 initialization file, which is usually called @file{.emacs}.
17167 I myself use @code{customize} for hardly anything. Mostly, I write
17168 expressions myself.
17172 Incidentally, @code{defsubst} defines an inline function. The syntax
17173 is just like that of @code{defun}. @code{defconst} defines a symbol
17174 as a constant. The intent is that neither programs nor users should
17175 ever change a value set by @code{defconst}
17177 @node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization
17178 @section Beginning a @file{.emacs} File
17179 @cindex @file{.emacs} file, beginning of
17181 When you start Emacs, it loads your @file{.emacs} file unless you tell
17182 it not to by specifying @samp{-q} on the command line. (The
17183 @code{emacs -q} command gives you a plain, out-of-the-box Emacs.)
17185 A @file{.emacs} file contains Lisp expressions. Often, these are no
17186 more than expressions to set values; sometimes they are function
17189 @xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs
17190 Manual}, for a short description of initialization files.
17192 This chapter goes over some of the same ground, but is a walk among
17193 extracts from a complete, long-used @file{.emacs} file---my own.
17195 The first part of the file consists of comments: reminders to myself.
17196 By now, of course, I remember these things, but when I started, I did
17202 ;;;; Bob's .emacs file
17203 ; Robert J. Chassell
17204 ; 26 September 1985
17209 Look at that date! I started this file a long time ago. I have been
17210 adding to it ever since.
17214 ; Each section in this file is introduced by a
17215 ; line beginning with four semicolons; and each
17216 ; entry is introduced by a line beginning with
17217 ; three semicolons.
17222 This describes the usual conventions for comments in Emacs Lisp.
17223 Everything on a line that follows a semicolon is a comment. Two,
17224 three, and four semicolons are used as section and subsection
17225 markers. (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference
17226 Manual}, for more about comments.)
17231 ; Control-h is the help key;
17232 ; after typing control-h, type a letter to
17233 ; indicate the subject about which you want help.
17234 ; For an explanation of the help facility,
17235 ; type control-h two times in a row.
17240 Just remember: type @kbd{C-h} two times for help.
17244 ; To find out about any mode, type control-h m
17245 ; while in that mode. For example, to find out
17246 ; about mail mode, enter mail mode and then type
17252 `Mode help', as I call this, is very helpful. Usually, it tells you
17253 all you need to know.
17255 Of course, you don't need to include comments like these in your
17256 @file{.emacs} file. I included them in mine because I kept forgetting
17257 about Mode help or the conventions for comments---but I was able to
17258 remember to look here to remind myself.
17260 @node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization
17261 @section Text and Auto Fill Mode
17263 Now we come to the part that `turns on' Text mode and
17268 ;;; Text mode and Auto Fill mode
17269 ; The next two lines put Emacs into Text mode
17270 ; and Auto Fill mode, and are for writers who
17271 ; want to start writing prose rather than code.
17273 (setq default-major-mode 'text-mode)
17274 (add-hook 'text-mode-hook 'turn-on-auto-fill)
17278 Here is the first part of this @file{.emacs} file that does something
17279 besides remind a forgetful human!
17281 The first of the two lines in parentheses tells Emacs to turn on Text
17282 mode when you find a file, @emph{unless} that file should go into some
17283 other mode, such as C mode.
17285 @cindex Per-buffer, local variables list
17286 @cindex Local variables list, per-buffer,
17287 @cindex Automatic mode selection
17288 @cindex Mode selection, automatic
17289 When Emacs reads a file, it looks at the extension to the file name,
17290 if any. (The extension is the part that comes after a @samp{.}.) If
17291 the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns
17292 on C mode. Also, Emacs looks at first nonblank line of the file; if
17293 the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs
17294 possesses a list of extensions and specifications that it uses
17295 automatically. In addition, Emacs looks near the last page for a
17296 per-buffer, ``local variables list'', if any.
17299 @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU
17302 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
17306 See sections ``How Major Modes are Chosen'' and ``Local Variables in
17307 Files'' in @cite{The GNU Emacs Manual}.
17310 Now, back to the @file{.emacs} file.
17313 Here is the line again; how does it work?
17315 @cindex Text Mode turned on
17317 (setq default-major-mode 'text-mode)
17321 This line is a short, but complete Emacs Lisp expression.
17323 We are already familiar with @code{setq}. It sets the following variable,
17324 @code{default-major-mode}, to the subsequent value, which is
17325 @code{text-mode}. The single quote mark before @code{text-mode} tells
17326 Emacs to deal directly with the @code{text-mode} variable, not with
17327 whatever it might stand for. @xref{set & setq, , Setting the Value of
17328 a Variable}, for a reminder of how @code{setq} works. The main point
17329 is that there is no difference between the procedure you use to set
17330 a value in your @file{.emacs} file and the procedure you use anywhere
17334 Here is the next line:
17336 @cindex Auto Fill mode turned on
17339 (add-hook 'text-mode-hook 'turn-on-auto-fill)
17343 In this line, the @code{add-hook} command adds
17344 @code{turn-on-auto-fill} to the variable.
17346 @code{turn-on-auto-fill} is the name of a program, that, you guessed
17347 it!, turns on Auto Fill mode.
17349 Every time Emacs turns on Text mode, Emacs runs the commands `hooked'
17350 onto Text mode. So every time Emacs turns on Text mode, Emacs also
17351 turns on Auto Fill mode.
17353 In brief, the first line causes Emacs to enter Text mode when you edit a
17354 file, unless the file name extension, a first non-blank line, or local
17355 variables to tell Emacs otherwise.
17357 Text mode among other actions, sets the syntax table to work
17358 conveniently for writers. In Text mode, Emacs considers an apostrophe
17359 as part of a word like a letter; but Emacs does not consider a period
17360 or a space as part of a word. Thus, @kbd{M-f} moves you over
17361 @samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after
17362 the @samp{t} of @samp{it's}.
17364 The second line causes Emacs to turn on Auto Fill mode when it turns
17365 on Text mode. In Auto Fill mode, Emacs automatically breaks a line
17366 that is too wide and brings the excessively wide part of the line down
17367 to the next line. Emacs breaks lines between words, not within them.
17369 When Auto Fill mode is turned off, lines continue to the right as you
17370 type them. Depending on how you set the value of
17371 @code{truncate-lines}, the words you type either disappear off the
17372 right side of the screen, or else are shown, in a rather ugly and
17373 unreadable manner, as a continuation line on the screen.
17376 In addition, in this part of my @file{.emacs} file, I tell the Emacs
17377 fill commands to insert two spaces after a colon:
17380 (setq colon-double-space t)
17383 @node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization
17384 @section Mail Aliases
17386 Here is a @code{setq} that `turns on' mail aliases, along with more
17392 ; To enter mail mode, type `C-x m'
17393 ; To enter RMAIL (for reading mail),
17396 (setq mail-aliases t)
17400 @cindex Mail aliases
17402 This @code{setq} command sets the value of the variable
17403 @code{mail-aliases} to @code{t}. Since @code{t} means true, the line
17404 says, in effect, ``Yes, use mail aliases.''
17406 Mail aliases are convenient short names for long email addresses or
17407 for lists of email addresses. The file where you keep your `aliases'
17408 is @file{~/.mailrc}. You write an alias like this:
17411 alias geo george@@foobar.wiz.edu
17415 When you write a message to George, address it to @samp{geo}; the
17416 mailer will automatically expand @samp{geo} to the full address.
17418 @node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization
17419 @section Indent Tabs Mode
17420 @cindex Tabs, preventing
17421 @findex indent-tabs-mode
17423 By default, Emacs inserts tabs in place of multiple spaces when it
17424 formats a region. (For example, you might indent many lines of text
17425 all at once with the @code{indent-region} command.) Tabs look fine on
17426 a terminal or with ordinary printing, but they produce badly indented
17427 output when you use @TeX{} or Texinfo since @TeX{} ignores tabs.
17430 The following turns off Indent Tabs mode:
17434 ;;; Prevent Extraneous Tabs
17435 (setq-default indent-tabs-mode nil)
17439 Note that this line uses @code{setq-default} rather than the
17440 @code{setq} command that we have seen before. The @code{setq-default}
17441 command sets values only in buffers that do not have their own local
17442 values for the variable.
17445 @xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}.
17447 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
17451 See sections ``Tabs vs.@: Spaces'' and ``Local Variables in
17452 Files'' in @cite{The GNU Emacs Manual}.
17455 @node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization
17456 @section Some Keybindings
17458 Now for some personal keybindings:
17462 ;;; Compare windows
17463 (global-set-key "\C-cw" 'compare-windows)
17467 @findex compare-windows
17468 @code{compare-windows} is a nifty command that compares the text in
17469 your current window with text in the next window. It makes the
17470 comparison by starting at point in each window, moving over text in
17471 each window as far as they match. I use this command all the time.
17473 This also shows how to set a key globally, for all modes.
17475 @cindex Setting a key globally
17476 @cindex Global set key
17477 @cindex Key setting globally
17478 @findex global-set-key
17479 The command is @code{global-set-key}. It is followed by the
17480 keybinding. In a @file{.emacs} file, the keybinding is written as
17481 shown: @code{\C-c} stands for `control-c', which means `press the
17482 control key and the @kbd{c} key at the same time'. The @code{w} means
17483 `press the @kbd{w} key'. The keybinding is surrounded by double
17484 quotation marks. In documentation, you would write this as @kbd{C-c
17485 w}. (If you were binding a @key{META} key, such as @kbd{M-c}, rather
17486 than a @key{CTRL} key, you would write @code{\M-c}. @xref{Init
17487 Rebinding, , Rebinding Keys in Your Init File, emacs, The GNU Emacs
17488 Manual}, for details.)
17490 The command invoked by the keys is @code{compare-windows}. Note that
17491 @code{compare-windows} is preceded by a single quote; otherwise, Emacs
17492 would first try to evaluate the symbol to determine its value.
17494 These three things, the double quotation marks, the backslash before
17495 the @samp{C}, and the single quote mark are necessary parts of
17496 keybinding that I tend to forget. Fortunately, I have come to
17497 remember that I should look at my existing @file{.emacs} file, and
17498 adapt what is there.
17500 As for the keybinding itself: @kbd{C-c w}. This combines the prefix
17501 key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This
17502 set of keys, @kbd{C-c} followed by a single character, is strictly
17503 reserved for individuals' own use. (I call these `own' keys, since
17504 these are for my own use.) You should always be able to create such a
17505 keybinding for your own use without stomping on someone else's
17506 keybinding. If you ever write an extension to Emacs, please avoid
17507 taking any of these keys for public use. Create a key like @kbd{C-c
17508 C-w} instead. Otherwise, we will run out of `own' keys.
17511 Here is another keybinding, with a comment:
17515 ;;; Keybinding for `occur'
17516 ; I use occur a lot, so let's bind it to a key:
17517 (global-set-key "\C-co" 'occur)
17522 The @code{occur} command shows all the lines in the current buffer
17523 that contain a match for a regular expression. Matching lines are
17524 shown in a buffer called @file{*Occur*}. That buffer serves as a menu
17525 to jump to occurrences.
17527 @findex global-unset-key
17528 @cindex Unbinding key
17529 @cindex Key unbinding
17531 Here is how to unbind a key, so it does not
17537 (global-unset-key "\C-xf")
17541 There is a reason for this unbinding: I found I inadvertently typed
17542 @w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a
17543 file, as I intended, I accidentally set the width for filled text,
17544 almost always to a width I did not want. Since I hardly ever reset my
17545 default width, I simply unbound the key.
17547 @findex list-buffers, @r{rebound}
17548 @findex buffer-menu, @r{bound to key}
17550 The following rebinds an existing key:
17554 ;;; Rebind `C-x C-b' for `buffer-menu'
17555 (global-set-key "\C-x\C-b" 'buffer-menu)
17559 By default, @kbd{C-x C-b} runs the
17560 @code{list-buffers} command. This command lists
17561 your buffers in @emph{another} window. Since I
17562 almost always want to do something in that
17563 window, I prefer the @code{buffer-menu}
17564 command, which not only lists the buffers,
17565 but moves point into that window.
17567 @node Keymaps, Loading Files, Keybindings, Emacs Initialization
17570 @cindex Rebinding keys
17572 Emacs uses @dfn{keymaps} to record which keys call which commands.
17573 When you use @code{global-set-key} to set the keybinding for a single
17574 command in all parts of Emacs, you are specifying the keybinding in
17575 @code{current-global-map}.
17577 Specific modes, such as C mode or Text mode, have their own keymaps;
17578 the mode-specific keymaps override the global map that is shared by
17581 The @code{global-set-key} function binds, or rebinds, the global
17582 keymap. For example, the following binds the key @kbd{C-x C-b} to the
17583 function @code{buffer-menu}:
17586 (global-set-key "\C-x\C-b" 'buffer-menu)
17589 Mode-specific keymaps are bound using the @code{define-key} function,
17590 which takes a specific keymap as an argument, as well as the key and
17591 the command. For example, my @file{.emacs} file contains the
17592 following expression to bind the @code{texinfo-insert-@@group} command
17593 to @kbd{C-c C-c g}:
17597 (define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group)
17602 The @code{texinfo-insert-@@group} function itself is a little extension
17603 to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I
17604 use this command all the time and prefer to type the three strokes
17605 @kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}.
17606 (@samp{@@group} and its matching @samp{@@end group} are commands that
17607 keep all enclosed text together on one page; many multi-line examples
17608 in this book are surrounded by @samp{@@group @dots{} @@end group}.)
17611 Here is the @code{texinfo-insert-@@group} function definition:
17615 (defun texinfo-insert-@@group ()
17616 "Insert the string @@group in a Texinfo buffer."
17618 (beginning-of-line)
17619 (insert "@@group\n"))
17623 (Of course, I could have used Abbrev mode to save typing, rather than
17624 write a function to insert a word; but I prefer key strokes consistent
17625 with other Texinfo mode key bindings.)
17627 You will see numerous @code{define-key} expressions in
17628 @file{loaddefs.el} as well as in the various mode libraries, such as
17629 @file{cc-mode.el} and @file{lisp-mode.el}.
17631 @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs
17632 Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp
17633 Reference Manual}, for more information about keymaps.
17635 @node Loading Files, Autoload, Keymaps, Emacs Initialization
17636 @section Loading Files
17637 @cindex Loading files
17640 Many people in the GNU Emacs community have written extensions to
17641 Emacs. As time goes by, these extensions are often included in new
17642 releases. For example, the Calendar and Diary packages are now part
17643 of the standard GNU Emacs, as is Calc.
17645 You can use a @code{load} command to evaluate a complete file and
17646 thereby install all the functions and variables in the file into Emacs.
17649 @c (auto-compression-mode t)
17652 (load "~/emacs/slowsplit")
17655 This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it
17656 exists, the faster, byte compiled @file{slowsplit.elc} file from the
17657 @file{emacs} sub-directory of your home directory. The file contains
17658 the function @code{split-window-quietly}, which John Robinson wrote in
17661 The @code{split-window-quietly} function splits a window with the
17662 minimum of redisplay. I installed it in 1989 because it worked well
17663 with the slow 1200 baud terminals I was then using. Nowadays, I only
17664 occasionally come across such a slow connection, but I continue to use
17665 the function because I like the way it leaves the bottom half of a
17666 buffer in the lower of the new windows and the top half in the upper
17670 To replace the key binding for the default
17671 @code{split-window-vertically}, you must also unset that key and bind
17672 the keys to @code{split-window-quietly}, like this:
17676 (global-unset-key "\C-x2")
17677 (global-set-key "\C-x2" 'split-window-quietly)
17682 If you load many extensions, as I do, then instead of specifying the
17683 exact location of the extension file, as shown above, you can specify
17684 that directory as part of Emacs' @code{load-path}. Then, when Emacs
17685 loads a file, it will search that directory as well as its default
17686 list of directories. (The default list is specified in @file{paths.h}
17687 when Emacs is built.)
17690 The following command adds your @file{~/emacs} directory to the
17691 existing load path:
17695 ;;; Emacs Load Path
17696 (setq load-path (cons "~/emacs" load-path))
17700 Incidentally, @code{load-library} is an interactive interface to the
17701 @code{load} function. The complete function looks like this:
17703 @findex load-library
17706 (defun load-library (library)
17707 "Load the library named LIBRARY.
17708 This is an interface to the function `load'."
17710 (list (completing-read "Load library: "
17711 'locate-file-completion
17712 (cons load-path (get-load-suffixes)))))
17717 The name of the function, @code{load-library}, comes from the use of
17718 `library' as a conventional synonym for `file'. The source for the
17719 @code{load-library} command is in the @file{files.el} library.
17721 Another interactive command that does a slightly different job is
17722 @code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for
17723 Emacs, emacs, The GNU Emacs Manual}, for information on the
17724 distinction between @code{load-library} and this command.
17726 @node Autoload, Simple Extension, Loading Files, Emacs Initialization
17727 @section Autoloading
17730 Instead of installing a function by loading the file that contains it,
17731 or by evaluating the function definition, you can make the function
17732 available but not actually install it until it is first called. This
17733 is called @dfn{autoloading}.
17735 When you execute an autoloaded function, Emacs automatically evaluates
17736 the file that contains the definition, and then calls the function.
17738 Emacs starts quicker with autoloaded functions, since their libraries
17739 are not loaded right away; but you need to wait a moment when you
17740 first use such a function, while its containing file is evaluated.
17742 Rarely used functions are frequently autoloaded. The
17743 @file{loaddefs.el} library contains hundreds of autoloaded functions,
17744 from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may
17745 come to use a `rare' function frequently. When you do, you should
17746 load that function's file with a @code{load} expression in your
17747 @file{.emacs} file.
17749 In my @file{.emacs} file for Emacs version 22, I load 14 libraries
17750 that contain functions that would otherwise be autoloaded. (Actually,
17751 it would have been better to include these files in my `dumped' Emacs,
17752 but I forgot. @xref{Building Emacs, , Building Emacs, elisp, The GNU
17753 Emacs Lisp Reference Manual}, and the @file{INSTALL} file for more
17756 You may also want to include autoloaded expressions in your @file{.emacs}
17757 file. @code{autoload} is a built-in function that takes up to five
17758 arguments, the final three of which are optional. The first argument
17759 is the name of the function to be autoloaded; the second is the name
17760 of the file to be loaded. The third argument is documentation for the
17761 function, and the fourth tells whether the function can be called
17762 interactively. The fifth argument tells what type of
17763 object---@code{autoload} can handle a keymap or macro as well as a
17764 function (the default is a function).
17767 Here is a typical example:
17771 (autoload 'html-helper-mode
17772 "html-helper-mode" "Edit HTML documents" t)
17777 (@code{html-helper-mode} is an alternative to @code{html-mode}, which
17778 is a standard part of the distribution).
17781 This expression autoloads the @code{html-helper-mode} function. It
17782 takes it from the @file{html-helper-mode.el} file (or from the byte
17783 compiled file @file{html-helper-mode.elc}, if it exists.) The file
17784 must be located in a directory specified by @code{load-path}. The
17785 documentation says that this is a mode to help you edit documents
17786 written in the HyperText Markup Language. You can call this mode
17787 interactively by typing @kbd{M-x html-helper-mode}. (You need to
17788 duplicate the function's regular documentation in the autoload
17789 expression because the regular function is not yet loaded, so its
17790 documentation is not available.)
17792 @xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference
17793 Manual}, for more information.
17795 @node Simple Extension, X11 Colors, Autoload, Emacs Initialization
17796 @section A Simple Extension: @code{line-to-top-of-window}
17797 @findex line-to-top-of-window
17798 @cindex Simple extension in @file{.emacs} file
17800 Here is a simple extension to Emacs that moves the line point is on to
17801 the top of the window. I use this all the time, to make text easier
17804 You can put the following code into a separate file and then load it
17805 from your @file{.emacs} file, or you can include it within your
17806 @file{.emacs} file.
17809 Here is the definition:
17813 ;;; Line to top of window;
17814 ;;; replace three keystroke sequence C-u 0 C-l
17815 (defun line-to-top-of-window ()
17816 "Move the line point is on to top of window."
17823 Now for the keybinding.
17825 Nowadays, function keys as well as mouse button events and
17826 non-@sc{ascii} characters are written within square brackets, without
17827 quotation marks. (In Emacs version 18 and before, you had to write
17828 different function key bindings for each different make of terminal.)
17830 I bind @code{line-to-top-of-window} to my @key{F6} function key like
17834 (global-set-key [f6] 'line-to-top-of-window)
17837 For more information, see @ref{Init Rebinding, , Rebinding Keys in
17838 Your Init File, emacs, The GNU Emacs Manual}.
17840 @cindex Conditional 'twixt two versions of Emacs
17841 @cindex Version of Emacs, choosing
17842 @cindex Emacs version, choosing
17843 If you run two versions of GNU Emacs, such as versions 21 and 22, and
17844 use one @file{.emacs} file, you can select which code to evaluate with
17845 the following conditional:
17850 ((string-equal (number-to-string 21) (substring (emacs-version) 10 12))
17851 ;; evaluate version 21 code
17853 ((string-equal (number-to-string 22) (substring (emacs-version) 10 12))
17854 ;; evaluate version 22 code
17859 For example, in contrast to version 20, version 21 blinks its cursor
17860 by default. I hate such blinking, as well as some other features in
17861 version 21, so I placed the following in my @file{.emacs}
17862 file@footnote{When I start instances of Emacs that do not load my
17863 @file{.emacs} file or any site file, I also turn off blinking:
17866 emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
17868 @exdent Or nowadays, using an even more sophisticated set of options,
17876 (if (string-equal "21" (substring (emacs-version) 10 12))
17878 (blink-cursor-mode 0)
17879 ;; Insert newline when you press `C-n' (next-line)
17880 ;; at the end of the buffer
17881 (setq next-line-add-newlines t)
17884 ;; Turn on image viewing
17885 (auto-image-file-mode t)
17888 ;; Turn on menu bar (this bar has text)
17889 ;; (Use numeric argument to turn on)
17893 ;; Turn off tool bar (this bar has icons)
17894 ;; (Use numeric argument to turn on)
17895 (tool-bar-mode nil)
17898 ;; Turn off tooltip mode for tool bar
17899 ;; (This mode causes icon explanations to pop up)
17900 ;; (Use numeric argument to turn on)
17902 ;; If tooltips turned on, make tips appear promptly
17903 (setq tooltip-delay 0.1) ; default is one second
17909 (You will note that instead of typing @code{(number-to-string 21)}, I
17910 decided to save typing and wrote `21' as a string, @code{"21"}, rather
17911 than convert it from an integer to a string. In this instance, this
17912 expression is better than the longer, but more general
17913 @code{(number-to-string 21)}. However, if you do not know ahead of
17914 time what type of information will be returned, then the
17915 @code{number-to-string} function will be needed.)
17917 @node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization
17918 @section X11 Colors
17920 You can specify colors when you use Emacs with the MIT X Windowing
17923 I dislike the default colors and specify my own.
17926 Here are the expressions in my @file{.emacs}
17927 file that set values:
17931 ;; Set cursor color
17932 (set-cursor-color "white")
17935 (set-mouse-color "white")
17937 ;; Set foreground and background
17938 (set-foreground-color "white")
17939 (set-background-color "darkblue")
17943 ;;; Set highlighting colors for isearch and drag
17944 (set-face-foreground 'highlight "white")
17945 (set-face-background 'highlight "blue")
17949 (set-face-foreground 'region "cyan")
17950 (set-face-background 'region "blue")
17954 (set-face-foreground 'secondary-selection "skyblue")
17955 (set-face-background 'secondary-selection "darkblue")
17959 ;; Set calendar highlighting colors
17960 (setq calendar-load-hook
17962 (set-face-foreground 'diary-face "skyblue")
17963 (set-face-background 'holiday-face "slate blue")
17964 (set-face-foreground 'holiday-face "white")))
17968 The various shades of blue soothe my eye and prevent me from seeing
17969 the screen flicker.
17971 Alternatively, I could have set my specifications in various X
17972 initialization files. For example, I could set the foreground,
17973 background, cursor, and pointer (i.e., mouse) colors in my
17974 @file{~/.Xresources} file like this:
17978 Emacs*foreground: white
17979 Emacs*background: darkblue
17980 Emacs*cursorColor: white
17981 Emacs*pointerColor: white
17985 In any event, since it is not part of Emacs, I set the root color of
17986 my X window in my @file{~/.xinitrc} file, like this@footnote{I also
17987 run more modern window managers, such as Enlightenment, Gnome, or KDE;
17988 in those cases, I often specify an image rather than a plain color.}:
17991 xsetroot -solid Navy -fg white &
17994 @node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization
17995 @section Miscellaneous Settings for a @file{.emacs} File
17997 Here are a few miscellaneous settings:
18002 Set the shape and color of the mouse cursor:
18006 ; Cursor shapes are defined in
18007 ; `/usr/include/X11/cursorfont.h';
18008 ; for example, the `target' cursor is number 128;
18009 ; the `top_left_arrow' cursor is number 132.
18013 (let ((mpointer (x-get-resource "*mpointer"
18014 "*emacs*mpointer")))
18015 ;; If you have not set your mouse pointer
18016 ;; then set it, otherwise leave as is:
18017 (if (eq mpointer nil)
18018 (setq mpointer "132")) ; top_left_arrow
18021 (setq x-pointer-shape (string-to-int mpointer))
18022 (set-mouse-color "white"))
18027 Or you can set the values of a variety of features in an alist, like
18033 default-frame-alist
18034 '((cursor-color . "white")
18035 (mouse-color . "white")
18036 (foreground-color . "white")
18037 (background-color . "DodgerBlue4")
18038 ;; (cursor-type . bar)
18039 (cursor-type . box)
18042 (tool-bar-lines . 0)
18043 (menu-bar-lines . 1)
18047 "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1")
18053 Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL}
18054 into @kbd{@key{CTRL}-h}.@*
18055 (Some older keyboards needed this, although I have not seen the
18060 ;; Translate `C-h' to <DEL>.
18061 ; (keyboard-translate ?\C-h ?\C-?)
18063 ;; Translate <DEL> to `C-h'.
18064 (keyboard-translate ?\C-? ?\C-h)
18068 @item Turn off a blinking cursor!
18072 (if (fboundp 'blink-cursor-mode)
18073 (blink-cursor-mode -1))
18078 or start GNU Emacs with the command @code{emacs -nbc}.
18080 @item Ignore case when using `grep'@*
18081 @samp{-n}@w{ } Prefix each line of output with line number@*
18082 @samp{-i}@w{ } Ignore case distinctions@*
18083 @samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-}
18086 (setq grep-command "grep -n -i -e ")
18090 @c Evidently, no longer needed in GNU Emacs 22
18092 item Automatically uncompress compressed files when visiting them
18095 (load "uncompress")
18100 @item Find an existing buffer, even if it has a different name@*
18101 This avoids problems with symbolic links.
18104 (setq find-file-existing-other-name t)
18107 @item Set your language environment and default input method
18111 (set-language-environment "latin-1")
18112 ;; Remember you can enable or disable multilingual text input
18113 ;; with the @code{toggle-input-method'} (@kbd{C-\}) command
18114 (setq default-input-method "latin-1-prefix")
18118 If you want to write with Chinese `GB' characters, set this instead:
18122 (set-language-environment "Chinese-GB")
18123 (setq default-input-method "chinese-tonepy")
18128 @subsubheading Fixing Unpleasant Key Bindings
18129 @cindex Key bindings, fixing
18130 @cindex Bindings, key, fixing unpleasant
18132 Some systems bind keys unpleasantly. Sometimes, for example, the
18133 @key{CTRL} key appears in an awkward spot rather than at the far left
18136 Usually, when people fix these sorts of keybindings, they do not
18137 change their @file{~/.emacs} file. Instead, they bind the proper keys
18138 on their consoles with the @code{loadkeys} or @code{install-keymap}
18139 commands in their boot script and then include @code{xmodmap} commands
18140 in their @file{.xinitrc} or @file{.Xsession} file for X Windows.
18148 loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz
18152 install-keymap emacs2
18158 For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps
18159 Lock} key is at the far left of the home row:
18163 # Bind the key labeled `Caps Lock' to `Control'
18164 # (Such a broken user interface suggests that keyboard manufacturers
18165 # think that computers are typewriters from 1885.)
18167 xmodmap -e "clear Lock"
18168 xmodmap -e "add Control = Caps_Lock"
18174 In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT}
18175 key to a @key{META} key:
18179 # Some ill designed keyboards have a key labeled ALT and no Meta
18180 xmodmap -e "keysym Alt_L = Meta_L Alt_L"
18184 @node Mode Line, , Miscellaneous, Emacs Initialization
18185 @section A Modified Mode Line
18186 @vindex default-mode-line-format
18187 @cindex Mode line format
18189 Finally, a feature I really like: a modified mode line.
18191 When I work over a network, I forget which machine I am using. Also,
18192 I tend to I lose track of where I am, and which line point is on.
18194 So I reset my mode line to look like this:
18197 -:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top
18200 I am visiting a file called @file{foo.texi}, on my machine
18201 @file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in
18202 Texinfo mode, and am at the top of the buffer.
18205 My @file{.emacs} file has a section that looks like this:
18209 ;; Set a Mode Line that tells me which machine, which directory,
18210 ;; and which line I am on, plus the other customary information.
18211 (setq default-mode-line-format
18215 "mouse-1: select window, mouse-2: delete others ..."))
18216 mode-line-mule-info
18218 mode-line-frame-identification
18222 mode-line-buffer-identification
18225 (system-name) 0 (string-match "\\..+" (system-name))))
18230 "mouse-1: select window, mouse-2: delete others ..."))
18231 (line-number-mode " Line %l ")
18237 "mouse-1: select window, mouse-2: delete others ..."))
18238 (:eval (mode-line-mode-name))
18241 #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
18250 Here, I redefine the default mode line. Most of the parts are from
18251 the original; but I make a few changes. I set the @emph{default} mode
18252 line format so as to permit various modes, such as Info, to override
18255 Many elements in the list are self-explanatory:
18256 @code{mode-line-modified} is a variable that tells whether the buffer
18257 has been modified, @code{mode-name} tells the name of the mode, and so
18258 on. However, the format looks complicated because of two features we
18259 have not discussed.
18261 @cindex Properties, in mode line example
18262 The first string in the mode line is a dash or hyphen, @samp{-}. In
18263 the old days, it would have been specified simply as @code{"-"}. But
18264 nowadays, Emacs can add properties to a string, such as highlighting
18265 or, as in this case, a help feature. If you place your mouse cursor
18266 over the hyphen, some help information appears (By default, you must
18267 wait seven-tenths of a second before the information appears. You can
18268 change that timing by changing the value of @code{tooltip-delay}.)
18271 The new string format has a special syntax:
18274 #("-" 0 1 (help-echo "mouse-1: select window, ..."))
18278 The @code{#(} begins a list. The first element of the list is the
18279 string itself, just one @samp{-}. The second and third
18280 elements specify the range over which the fourth element applies. A
18281 range starts @emph{after} a character, so a zero means the range
18282 starts just before the first character; a 1 means that the range ends
18283 just after the first character. The third element is the property for
18284 the range. It consists of a property list, a
18285 property name, in this case, @samp{help-echo}, followed by a value, in this
18286 case, a string. The second, third, and fourth elements of this new
18287 string format can be repeated.
18289 @xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp
18290 Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format,
18291 elisp, The GNU Emacs Lisp Reference Manual}, for more information.
18293 @code{mode-line-buffer-identification}
18294 displays the current buffer name. It is a list
18295 beginning @code{(#("%12b" 0 4 @dots{}}.
18296 The @code{#(} begins the list.
18298 The @samp{"%12b"} displays the current buffer name, using the
18299 @code{buffer-name} function with which we are familiar; the `12'
18300 specifies the maximum number of characters that will be displayed.
18301 When a name has fewer characters, whitespace is added to fill out to
18302 this number. (Buffer names can and often should be longer than 12
18303 characters; this length works well in a typical 80 column wide
18306 @code{:eval} says to evaluate the following form and use the result as
18307 a string to display. In this case, the expression displays the first
18308 component of the full system name. The end of the first component is
18309 a @samp{.} (`period'), so I use the @code{string-match} function to
18310 tell me the length of the first component. The substring from the
18311 zeroth character to that length is the name of the machine.
18314 This is the expression:
18319 (system-name) 0 (string-match "\\..+" (system-name))))
18323 @samp{%[} and @samp{%]} cause a pair of square brackets
18324 to appear for each recursive editing level. @samp{%n} says `Narrow'
18325 when narrowing is in effect. @samp{%P} tells you the percentage of
18326 the buffer that is above the bottom of the window, or `Top', `Bottom',
18327 or `All'. (A lower case @samp{p} tell you the percentage above the
18328 @emph{top} of the window.) @samp{%-} inserts enough dashes to fill
18331 Remember, ``You don't have to like Emacs to like it'' --- your own
18332 Emacs can have different colors, different commands, and different
18333 keys than a default Emacs.
18335 On the other hand, if you want to bring up a plain `out of the box'
18336 Emacs, with no customization, type:
18343 This will start an Emacs that does @emph{not} load your
18344 @file{~/.emacs} initialization file. A plain, default Emacs. Nothing
18347 @node Debugging, Conclusion, Emacs Initialization, Top
18351 GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The
18352 first is built into the internals of Emacs and is always with you;
18353 the second requires that you instrument a function before you can use it.
18355 Both debuggers are described extensively in @ref{Debugging, ,
18356 Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}.
18357 In this chapter, I will walk through a short example of each.
18364 * Debugging Exercises::
18367 @node debug, debug-on-entry, Debugging, Debugging
18368 @section @code{debug}
18371 Suppose you have written a function definition that is intended to
18372 return the sum of the numbers 1 through a given number. (This is the
18373 @code{triangle} function discussed earlier. @xref{Decrementing
18374 Example, , Example with Decrementing Counter}, for a discussion.)
18375 @c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.)
18377 However, your function definition has a bug. You have mistyped
18378 @samp{1=} for @samp{1-}. Here is the broken definition:
18380 @findex triangle-bugged
18383 (defun triangle-bugged (number)
18384 "Return sum of numbers 1 through NUMBER inclusive."
18386 (while (> number 0)
18387 (setq total (+ total number))
18388 (setq number (1= number))) ; @r{Error here.}
18393 If you are reading this in Info, you can evaluate this definition in
18394 the normal fashion. You will see @code{triangle-bugged} appear in the
18398 Now evaluate the @code{triangle-bugged} function with an
18402 (triangle-bugged 4)
18406 In GNU Emacs version 21, you will create and enter a
18407 @file{*Backtrace*} buffer that says:
18412 ---------- Buffer: *Backtrace* ----------
18413 Debugger entered--Lisp error: (void-function 1=)
18415 (setq number (1= number))
18416 (while (> number 0) (setq total (+ total number))
18417 (setq number (1= number)))
18418 (let ((total 0)) (while (> number 0) (setq total ...)
18419 (setq number ...)) total)
18423 eval((triangle-bugged 4))
18424 eval-last-sexp-1(nil)
18425 eval-last-sexp(nil)
18426 call-interactively(eval-last-sexp)
18427 ---------- Buffer: *Backtrace* ----------
18432 (I have reformatted this example slightly; the debugger does not fold
18433 long lines. As usual, you can quit the debugger by typing @kbd{q} in
18434 the @file{*Backtrace*} buffer.)
18436 In practice, for a bug as simple as this, the `Lisp error' line will
18437 tell you what you need to know to correct the definition. The
18438 function @code{1=} is `void'.
18442 In GNU Emacs 20 and before, you will see:
18445 Symbol's function definition is void:@: 1=
18449 which has the same meaning as the @file{*Backtrace*} buffer line in
18453 However, suppose you are not quite certain what is going on?
18454 You can read the complete backtrace.
18456 In this case, you need to run GNU Emacs 22, which automatically starts
18457 the debugger that puts you in the @file{*Backtrace*} buffer; or else,
18458 you need to start the debugger manually as described below.
18460 Read the @file{*Backtrace*} buffer from the bottom up; it tells you
18461 what Emacs did that led to the error. Emacs made an interactive call
18462 to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation
18463 of the @code{triangle-bugged} expression. Each line above tells you
18464 what the Lisp interpreter evaluated next.
18467 The third line from the top of the buffer is
18470 (setq number (1= number))
18474 Emacs tried to evaluate this expression; in order to do so, it tried
18475 to evaluate the inner expression shown on the second line from the
18484 This is where the error occurred; as the top line says:
18487 Debugger entered--Lisp error: (void-function 1=)
18491 You can correct the mistake, re-evaluate the function definition, and
18492 then run your test again.
18494 @node debug-on-entry, debug-on-quit, debug, Debugging
18495 @section @code{debug-on-entry}
18496 @findex debug-on-entry
18498 GNU Emacs 22 starts the debugger automatically when your function has
18502 GNU Emacs version 20 and before did not; it simply
18503 presented you with an error message. You had to start the debugger
18507 Incidentally, you can start the debugger manually for all versions of
18508 Emacs; the advantage is that the debugger runs even if you do not have
18509 a bug in your code. Sometimes your code will be free of bugs!
18511 You can enter the debugger when you call the function by calling
18512 @code{debug-on-entry}.
18519 M-x debug-on-entry RET triangle-bugged RET
18524 Now, evaluate the following:
18527 (triangle-bugged 5)
18531 All versions of Emacs will create a @file{*Backtrace*} buffer and tell
18532 you that it is beginning to evaluate the @code{triangle-bugged}
18537 ---------- Buffer: *Backtrace* ----------
18538 Debugger entered--entering a function:
18539 * triangle-bugged(5)
18540 eval((triangle-bugged 5))
18543 eval-last-sexp-1(nil)
18544 eval-last-sexp(nil)
18545 call-interactively(eval-last-sexp)
18546 ---------- Buffer: *Backtrace* ----------
18550 In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate
18551 the first expression in @code{triangle-bugged}; the buffer will look
18556 ---------- Buffer: *Backtrace* ----------
18557 Debugger entered--beginning evaluation of function call form:
18558 * (let ((total 0)) (while (> number 0) (setq total ...)
18559 (setq number ...)) total)
18560 * triangle-bugged(5)
18561 eval((triangle-bugged 5))
18564 eval-last-sexp-1(nil)
18565 eval-last-sexp(nil)
18566 call-interactively(eval-last-sexp)
18567 ---------- Buffer: *Backtrace* ----------
18572 Now, type @kbd{d} again, eight times, slowly. Each time you type
18573 @kbd{d}, Emacs will evaluate another expression in the function
18577 Eventually, the buffer will look like this:
18581 ---------- Buffer: *Backtrace* ----------
18582 Debugger entered--beginning evaluation of function call form:
18583 * (setq number (1= number))
18584 * (while (> number 0) (setq total (+ total number))
18585 (setq number (1= number)))
18588 * (let ((total 0)) (while (> number 0) (setq total ...)
18589 (setq number ...)) total)
18590 * triangle-bugged(5)
18591 eval((triangle-bugged 5))
18594 eval-last-sexp-1(nil)
18595 eval-last-sexp(nil)
18596 call-interactively(eval-last-sexp)
18597 ---------- Buffer: *Backtrace* ----------
18603 Finally, after you type @kbd{d} two more times, Emacs will reach the
18604 error, and the top two lines of the @file{*Backtrace*} buffer will look
18609 ---------- Buffer: *Backtrace* ----------
18610 Debugger entered--Lisp error: (void-function 1=)
18613 ---------- Buffer: *Backtrace* ----------
18617 By typing @kbd{d}, you were able to step through the function.
18619 You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this
18620 quits the trace, but does not cancel @code{debug-on-entry}.
18622 @findex cancel-debug-on-entry
18623 To cancel the effect of @code{debug-on-entry}, call
18624 @code{cancel-debug-on-entry} and the name of the function, like this:
18627 M-x cancel-debug-on-entry RET triangle-bugged RET
18631 (If you are reading this in Info, cancel @code{debug-on-entry} now.)
18633 @node debug-on-quit, edebug, debug-on-entry, Debugging
18634 @section @code{debug-on-quit} and @code{(debug)}
18636 In addition to setting @code{debug-on-error} or calling @code{debug-on-entry},
18637 there are two other ways to start @code{debug}.
18639 @findex debug-on-quit
18640 You can start @code{debug} whenever you type @kbd{C-g}
18641 (@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to
18642 @code{t}. This is useful for debugging infinite loops.
18645 @cindex @code{(debug)} in code
18646 Or, you can insert a line that says @code{(debug)} into your code
18647 where you want the debugger to start, like this:
18651 (defun triangle-bugged (number)
18652 "Return sum of numbers 1 through NUMBER inclusive."
18654 (while (> number 0)
18655 (setq total (+ total number))
18656 (debug) ; @r{Start debugger.}
18657 (setq number (1= number))) ; @r{Error here.}
18662 The @code{debug} function is described in detail in @ref{Debugger, ,
18663 The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}.
18665 @node edebug, Debugging Exercises, debug-on-quit, Debugging
18666 @section The @code{edebug} Source Level Debugger
18667 @cindex Source level debugger
18670 Edebug is a source level debugger. Edebug normally displays the
18671 source of the code you are debugging, with an arrow at the left that
18672 shows which line you are currently executing.
18674 You can walk through the execution of a function, line by line, or run
18675 quickly until reaching a @dfn{breakpoint} where execution stops.
18677 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
18678 Lisp Reference Manual}.
18681 Here is a bugged function definition for @code{triangle-recursively}.
18682 @xref{Recursive triangle function, , Recursion in place of a counter},
18683 for a review of it.
18687 (defun triangle-recursively-bugged (number)
18688 "Return sum of numbers 1 through NUMBER inclusive.
18693 (triangle-recursively-bugged
18694 (1= number))))) ; @r{Error here.}
18699 Normally, you would install this definition by positioning your cursor
18700 after the function's closing parenthesis and typing @kbd{C-x C-e}
18701 (@code{eval-last-sexp}) or else by positioning your cursor within the
18702 definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default,
18703 the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp
18707 However, to prepare this function definition for Edebug, you must
18708 first @dfn{instrument} the code using a different command. You can do
18709 this by positioning your cursor within the definition and typing
18712 M-x edebug-defun RET
18716 This will cause Emacs to load Edebug automatically if it is not
18717 already loaded, and properly instrument the function.
18719 After instrumenting the function, place your cursor after the
18720 following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}):
18723 (triangle-recursively-bugged 3)
18727 You will be jumped back to the source for
18728 @code{triangle-recursively-bugged} and the cursor positioned at the
18729 beginning of the @code{if} line of the function. Also, you will see
18730 an arrowhead at the left hand side of that line. The arrowhead marks
18731 the line where the function is executing. (In the following examples,
18732 we show the arrowhead with @samp{=>}; in a windowing system, you may
18733 see the arrowhead as a solid triangle in the window `fringe'.)
18736 =>@point{}(if (= number 1)
18741 In the example, the location of point is displayed with a star,
18742 @samp{@point{}} (in Info, it is displayed as @samp{-!-}).
18745 In the example, the location of point is displayed as @samp{@point{}}
18746 (in a printed book, it is displayed with a five pointed star).
18749 If you now press @key{SPC}, point will move to the next expression to
18750 be executed; the line will look like this:
18753 =>(if @point{}(= number 1)
18757 As you continue to press @key{SPC}, point will move from expression to
18758 expression. At the same time, whenever an expression returns a value,
18759 that value will be displayed in the echo area. For example, after you
18760 move point past @code{number}, you will see the following:
18763 Result: 3 (#o3, #x3, ?\C-c)
18767 This means the value of @code{number} is 3, which is octal three,
18768 hexadecimal three, and @sc{ascii} `control-c' (the third letter of the
18769 alphabet, in case you need to know this information).
18771 You can continue moving through the code until you reach the line with
18772 the error. Before evaluation, that line looks like this:
18775 => @point{}(1= number))))) ; @r{Error here.}
18780 When you press @key{SPC} once again, you will produce an error message
18784 Symbol's function definition is void:@: 1=
18790 Press @kbd{q} to quit Edebug.
18792 To remove instrumentation from a function definition, simply
18793 re-evaluate it with a command that does not instrument it.
18794 For example, you could place your cursor after the definition's
18795 closing parenthesis and type @kbd{C-x C-e}.
18797 Edebug does a great deal more than walk with you through a function.
18798 You can set it so it races through on its own, stopping only at an
18799 error or at specified stopping points; you can cause it to display the
18800 changing values of various expressions; you can find out how many
18801 times a function is called, and more.
18803 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
18804 Lisp Reference Manual}.
18807 @node Debugging Exercises, , edebug, Debugging
18808 @section Debugging Exercises
18812 Install the @code{count-words-region} function and then cause it to
18813 enter the built-in debugger when you call it. Run the command on a
18814 region containing two words. You will need to press @kbd{d} a
18815 remarkable number of times. On your system, is a `hook' called after
18816 the command finishes? (For information on hooks, see @ref{Command
18817 Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference
18821 Copy @code{count-words-region} into the @file{*scratch*} buffer,
18822 instrument the function for Edebug, and walk through its execution.
18823 The function does not need to have a bug, although you can introduce
18824 one if you wish. If the function lacks a bug, the walk-through
18825 completes without problems.
18828 While running Edebug, type @kbd{?} to see a list of all the Edebug commands.
18829 (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@:
18830 @kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix
18831 for commands made outside of the Edebug debugging buffer.)
18834 In the Edebug debugging buffer, use the @kbd{p}
18835 (@code{edebug-bounce-point}) command to see where in the region the
18836 @code{count-words-region} is working.
18839 Move point to some spot further down the function and then type the
18840 @kbd{h} (@code{edebug-goto-here}) command to jump to that location.
18843 Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to
18844 walk through the function on its own; use an upper case @kbd{T} for
18845 @code{edebug-Trace-fast-mode}.
18848 Set a breakpoint, then run Edebug in Trace mode until it reaches the
18852 @node Conclusion, the-the, Debugging, Top
18853 @chapter Conclusion
18855 We have now reached the end of this Introduction. You have now
18856 learned enough about programming in Emacs Lisp to set values, to write
18857 simple @file{.emacs} files for yourself and your friends, and write
18858 simple customizations and extensions to Emacs.
18860 This is a place to stop. Or, if you wish, you can now go onward, and
18863 You have learned some of the basic nuts and bolts of programming. But
18864 only some. There are a great many more brackets and hinges that are
18865 easy to use that we have not touched.
18867 A path you can follow right now lies among the sources to GNU Emacs
18870 @cite{The GNU Emacs Lisp Reference Manual}.
18873 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
18874 Emacs Lisp Reference Manual}.
18877 The Emacs Lisp sources are an adventure. When you read the sources and
18878 come across a function or expression that is unfamiliar, you need to
18879 figure out or find out what it does.
18881 Go to the Reference Manual. It is a thorough, complete, and fairly
18882 easy-to-read description of Emacs Lisp. It is written not only for
18883 experts, but for people who know what you know. (The @cite{Reference
18884 Manual} comes with the standard GNU Emacs distribution. Like this
18885 introduction, it comes as a Texinfo source file, so you can read it
18886 on-line and as a typeset, printed book.)
18888 Go to the other on-line help that is part of GNU Emacs: the on-line
18889 documentation for all functions and variables, and @code{find-tags},
18890 the program that takes you to sources.
18892 Here is an example of how I explore the sources. Because of its name,
18893 @file{simple.el} is the file I looked at first, a long time ago. As
18894 it happens some of the functions in @file{simple.el} are complicated,
18895 or at least look complicated at first sight. The @code{open-line}
18896 function, for example, looks complicated.
18898 You may want to walk through this function slowly, as we did with the
18899 @code{forward-sentence} function. (@xref{forward-sentence, The
18900 @code{forward-sentence} function}.) Or you may want to skip that
18901 function and look at another, such as @code{split-line}. You don't
18902 need to read all the functions. According to
18903 @code{count-words-in-defun}, the @code{split-line} function contains
18904 102 words and symbols.
18906 Even though it is short, @code{split-line} contains expressions
18907 we have not studied: @code{skip-chars-forward}, @code{indent-to},
18908 @code{current-column} and @code{insert-and-inherit}.
18910 Consider the @code{skip-chars-forward} function. (It is part of the
18911 function definition for @code{back-to-indentation}, which is shown in
18912 @ref{Review, , Review}.)
18914 In GNU Emacs, you can find out more about @code{skip-chars-forward} by
18915 typing @kbd{C-h f} (@code{describe-function}) and the name of the
18916 function. This gives you the function documentation.
18918 You may be able to guess what is done by a well named function such as
18919 @code{indent-to}; or you can look it up, too. Incidentally, the
18920 @code{describe-function} function itself is in @file{help.el}; it is
18921 one of those long, but decipherable functions. You can look up
18922 @code{describe-function} using the @kbd{C-h f} command!
18924 In this instance, since the code is Lisp, the @file{*Help*} buffer
18925 contains the name of the library containing the function's source.
18926 You can put point over the name of the library and press the RET key,
18927 which in this situation is bound to @code{help-follow}, and be taken
18928 directly to the source, in the same way as @kbd{M-.}
18931 The definition for @code{describe-function} illustrates how to
18932 customize the @code{interactive} expression without using the standard
18933 character codes; and it shows how to create a temporary buffer.
18935 (The @code{indent-to} function is written in C rather than Emacs Lisp;
18936 it is a `built-in' function. @code{help-follow} takes you to its
18937 source as does @code{find-tag}, when properly set up.)
18939 You can look at a function's source using @code{find-tag}, which is
18940 bound to @kbd{M-.} Finally, you can find out what the Reference
18941 Manual has to say by visiting the manual in Info, and typing @kbd{i}
18942 (@code{Info-index}) and the name of the function, or by looking up the
18943 function in the index to a printed copy of the manual.
18945 Similarly, you can find out what is meant by
18946 @code{insert-and-inherit}.
18948 Other interesting source files include @file{paragraphs.el},
18949 @file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el}
18950 file includes short, easily understood functions as well as longer
18951 ones. The @file{loaddefs.el} file contains the many standard
18952 autoloads and many keymaps. I have never looked at it all; only at
18953 parts. @file{loadup.el} is the file that loads the standard parts of
18954 Emacs; it tells you a great deal about how Emacs is built.
18955 (@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
18956 Reference Manual}, for more about building.)
18958 As I said, you have learned some nuts and bolts; however, and very
18959 importantly, we have hardly touched major aspects of programming; I
18960 have said nothing about how to sort information, except to use the
18961 predefined @code{sort} function; I have said nothing about how to store
18962 information, except to use variables and lists; I have said nothing
18963 about how to write programs that write programs. These are topics for
18964 another, and different kind of book, a different kind of learning.
18966 What you have done is learn enough for much practical work with GNU
18967 Emacs. What you have done is get started. This is the end of a
18970 @c ================ Appendix ================
18972 @node the-the, Kill Ring, Conclusion, Top
18973 @appendix The @code{the-the} Function
18975 @cindex Duplicated words function
18976 @cindex Words, duplicated
18978 Sometimes when you you write text, you duplicate words---as with ``you
18979 you'' near the beginning of this sentence. I find that most
18980 frequently, I duplicate ``the''; hence, I call the function for
18981 detecting duplicated words, @code{the-the}.
18984 As a first step, you could use the following regular expression to
18985 search for duplicates:
18988 \\(\\w+[ \t\n]+\\)\\1
18992 This regexp matches one or more word-constituent characters followed
18993 by one or more spaces, tabs, or newlines. However, it does not detect
18994 duplicated words on different lines, since the ending of the first
18995 word, the end of the line, is different from the ending of the second
18996 word, a space. (For more information about regular expressions, see
18997 @ref{Regexp Search, , Regular Expression Searches}, as well as
18998 @ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
18999 Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp,
19000 The GNU Emacs Lisp Reference Manual}.)
19002 You might try searching just for duplicated word-constituent
19003 characters but that does not work since the pattern detects doubles
19004 such as the two occurrences of `th' in `with the'.
19006 Another possible regexp searches for word-constituent characters
19007 followed by non-word-constituent characters, reduplicated. Here,
19008 @w{@samp{\\w+}} matches one or more word-constituent characters and
19009 @w{@samp{\\W*}} matches zero or more non-word-constituent characters.
19012 \\(\\(\\w+\\)\\W*\\)\\1
19018 Here is the pattern that I use. It is not perfect, but good enough.
19019 @w{@samp{\\b}} matches the empty string, provided it is at the beginning
19020 or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of
19021 any characters that are @emph{not} an @@-sign, space, newline, or tab.
19024 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
19027 One can write more complicated expressions, but I found that this
19028 expression is good enough, so I use it.
19030 Here is the @code{the-the} function, as I include it in my
19031 @file{.emacs} file, along with a handy global key binding:
19036 "Search forward for for a duplicated word."
19038 (message "Searching for for duplicated words ...")
19042 ;; This regexp is not perfect
19043 ;; but is fairly good over all:
19044 (if (re-search-forward
19045 "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move)
19046 (message "Found duplicated word.")
19047 (message "End of buffer")))
19051 ;; Bind `the-the' to C-c \
19052 (global-set-key "\C-c\\" 'the-the)
19061 one two two three four five
19066 You can substitute the other regular expressions shown above in the
19067 function definition and try each of them on this list.
19069 @node Kill Ring, Full Graph, the-the, Top
19070 @appendix Handling the Kill Ring
19071 @cindex Kill ring handling
19072 @cindex Handling the kill ring
19073 @cindex Ring, making a list like a
19075 The kill ring is a list that is transformed into a ring by the
19076 workings of the @code{current-kill} function. The @code{yank} and
19077 @code{yank-pop} commands use the @code{current-kill} function.
19079 This appendix describes the @code{current-kill} function as well as
19080 both the @code{yank} and the @code{yank-pop} commands, but first,
19081 consider the workings of the kill ring.
19084 The kill ring has a default maximum length of sixty items; this number
19085 is too large for an explanation. Instead, set it to four. Please
19086 evaluate the following:
19090 (setq old-kill-ring-max kill-ring-max)
19091 (setq kill-ring-max 4)
19096 Then, please copy each line of the following indented example into the
19097 kill ring. You may kill each line with @kbd{C-k} or mark it and copy
19101 (In a read-only buffer, such as the @file{*info*} buffer, the kill
19102 command, @kbd{C-k} (@code{kill-line}), will not remove the text,
19103 merely copy it to the kill ring. However, your machine may beep at
19104 you. (@code{kill-line} calls @code{kill-region}.) Alternatively, for
19105 silence, you may copy the region of each line with the @kbd{M-w}
19106 (@code{kill-ring-save}) command. You must mark each line for this
19107 command to succeed, but it does not matter at which end you put point
19111 @c texi2dvi fails when the name of the section is within ifnottex ...
19112 For a discussion of how @code{condition-case} deals with error, see
19113 @ref{Complete kill-region, , The Complete @code{kill-region}
19119 Please invoke the calls in order, so that five elements attempt to
19120 fill the kill ring:
19125 second piece of text
19127 fourth line of text
19134 Then find the value of @code{kill-ring} by evaluating
19146 ("fifth bit of text" "fourth line of text"
19147 "third line" "second piece of text")
19152 The first element, @samp{first some text}, was dropped.
19155 To return to the old value for the length of the kill ring, evaluate:
19158 (setq kill-ring-max old-kill-ring-max)
19168 @node current-kill, yank, Kill Ring, Kill Ring
19169 @comment node-name, next, previous, up
19170 @appendixsec The @code{current-kill} Function
19171 @findex current-kill
19173 The @code{current-kill} function changes the element in the kill ring
19174 to which @code{kill-ring-yank-pointer} points. (Also, the
19175 @code{kill-new} function sets @code{kill-ring-yank-pointer} to point
19176 to the latest element of the the kill ring.)
19179 The @code{current-kill} function is used by @code{yank} and by
19180 @code{yank-pop}. Here is the code for @code{current-kill}:
19184 (defun current-kill (n &optional do-not-move)
19185 "Rotate the yanking point by N places, and then return that kill.
19186 If N is zero, `interprogram-paste-function' is set, and calling it
19187 returns a string, then that string is added to the front of the
19188 kill ring and returned as the latest kill.
19191 If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
19192 yanking point; just return the Nth kill forward."
19193 (let ((interprogram-paste (and (= n 0)
19194 interprogram-paste-function
19195 (funcall interprogram-paste-function))))
19198 (if interprogram-paste
19200 ;; Disable the interprogram cut function when we add the new
19201 ;; text to the kill ring, so Emacs doesn't try to own the
19202 ;; selection, with identical text.
19203 (let ((interprogram-cut-function nil))
19204 (kill-new interprogram-paste))
19205 interprogram-paste)
19208 (or kill-ring (error "Kill ring is empty"))
19209 (let ((ARGth-kill-element
19210 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19211 (length kill-ring))
19214 (setq kill-ring-yank-pointer ARGth-kill-element))
19215 (car ARGth-kill-element)))))
19219 In addition, the @code{kill-new} function sets
19220 @code{kill-ring-yank-pointer} to the latest element of the the kill
19221 ring. And indirectly so does @code{kill-append}, since it calls
19222 @code{kill-new}. In addition, @code{kill-region} and @code{kill-line}
19223 call the @code{kill-new} function.
19226 Here is the line in @code{kill-new}, which is explained in
19227 @ref{kill-new function, , The @code{kill-new} function}.
19230 (setq kill-ring-yank-pointer kill-ring)
19234 * Understanding current-kill::
19237 @node Understanding current-kill, , current-kill, current-kill
19239 @unnumberedsubsec @code{current-kill} in Outline
19242 The @code{current-kill} function looks complex, but as usual, it can
19243 be understood by taking it apart piece by piece. First look at it in
19248 (defun current-kill (n &optional do-not-move)
19249 "Rotate the yanking point by N places, and then return that kill.
19255 This function takes two arguments, one of which is optional. It has a
19256 documentation string. It is @emph{not} interactive.
19258 The body of the function definition is a @code{let} expression, which
19259 itself has a body as well as a @var{varlist}.
19261 The @code{let} expression declares a variable that will be only usable
19262 within the bounds of this function. This variable is called
19263 @code{interprogram-paste} and is for copying to another program. It
19264 is not for copying within this instance of GNU Emacs. Most window
19265 systems provide a facility for interprogram pasting. Sadly, that
19266 facility usually provides only for the lasted element. Most windowing
19267 systems have not adopted a ring of many possibilities, even though
19268 Emacs has provided it for decades.
19270 The @code{if} expression has two parts, one if there exists
19271 @code{interprogram-paste} and one if not.
19274 Let us consider the `if not' or else-part of the @code{current-kill}
19275 function. (The then-part uses the the @code{kill-new} function, which
19276 we have already described. (@xref{kill-new function, , The
19277 @code{kill-new} function}.)
19281 (or kill-ring (error "Kill ring is empty"))
19282 (let ((ARGth-kill-element
19283 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19284 (length kill-ring))
19287 (setq kill-ring-yank-pointer ARGth-kill-element))
19288 (car ARGth-kill-element))
19293 The code first checks whether the kill ring has content; otherwise it
19297 Note that the @code{or} expression is very similar to writing
19303 (if (zerop (length kill-ring)) ; @r{if-part}
19304 (error "Kill ring is empty")) ; @r{then-part}
19310 If there is not anything in the kill ring, its length must be zero and
19311 an error message sent to the user: @samp{Kill ring is empty}. The
19312 @code{current-kill} function uses an @code{or} expression which is
19313 simpler. But an @code{if} expression reminds us what goes on.
19315 This @code{if} expression uses the function @code{zerop} which returns
19316 true if the value it is testing is zero. When @code{zerop} tests
19317 true, the then-part of the @code{if} is evaluated. The then-part is a
19318 list starting with the function @code{error}, which is a function that
19319 is similar to the @code{message} function
19320 (@pxref{message, , The @code{message} Function}), in that
19321 it prints a one-line message in the echo area. However, in addition
19322 to printing a message, @code{error} also stops evaluation of the
19323 function within which it is embedded. This means that the rest of the
19324 function will not be evaluated if the length of the kill ring is zero.
19326 Then the @code{current-kill} function selects the element to return.
19327 The selection depends on the number of places that @code{current-kill}
19328 rotates and on where @code{kill-ring-yank-pointer} points.
19330 Next, either the optional @code{do-not-move} argument is true or the
19331 current value of @code{kill-ring-yank-pointer} is set to point to the
19332 list, the first element of which is returned even if the
19333 @code{do-not-move} argument is true.
19336 * Digression concerning error::
19337 * Determining the Element ::
19340 @node Digression concerning error, Determining the Element , Understanding current-kill, Understanding current-kill
19342 @unnumberedsubsubsec Digression about the word `error'
19345 In my opinion, it is slightly misleading, at least to humans, to use
19346 the term `error' as the name of the @code{error} function. A better
19347 term would be `cancel'. Strictly speaking, of course, you cannot
19348 point to, much less rotate a pointer to a list that has no length, so
19349 from the point of view of the computer, the word `error' is correct.
19350 But a human expects to attempt this sort of thing, if only to find out
19351 whether the kill ring is full or empty. This is an act of
19354 From the human point of view, the act of exploration and discovery is
19355 not necessarily an error, and therefore should not be labelled as one,
19356 even in the bowels of a computer. As it is, the code in Emacs implies
19357 that a human who is acting virtuously, by exploring his or her
19358 environment, is making an error. This is bad. Even though the computer
19359 takes the same steps as it does when there is an `error', a term such as
19360 `cancel' would have a clearer connotation.
19362 @node Determining the Element , , Digression concerning error, Understanding current-kill
19364 @unnumberedsubsubsec Determining the Element
19367 Among other actions, the else-part of the @code{if} expression sets
19368 the value of @code{kill-ring-yank-pointer} to
19369 @code{ARGth-kill-element} when the kill ring has something in it and
19370 the value of @code{do-not-move} is @code{nil}.
19373 The code looks like this:
19377 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19378 (length kill-ring))
19383 This needs some examination. Unless it is not supposed to move the
19384 pointer, the @code{current-kill} function changes where
19385 @code{kill-ring-yank-pointer} points.
19387 @w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}}
19388 expression does. Also, clearly, @code{ARGth-kill-element} is being
19389 set to be equal to some @sc{cdr} of the kill ring, using the
19390 @code{nthcdr} function that is described in an earlier section.
19391 (@xref{copy-region-as-kill}.) How does it do this?
19393 As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function
19394 works by repeatedly taking the @sc{cdr} of a list---it takes the
19395 @sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{}
19398 The two following expressions produce the same result:
19402 (setq kill-ring-yank-pointer (cdr kill-ring))
19404 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
19408 However, the @code{nthcdr} expression is more complicated. It uses
19409 the @code{mod} function to determine which @sc{cdr} to select.
19411 (You will remember to look at inner functions first; indeed, we will
19412 have to go inside the @code{mod}.)
19414 The @code{mod} function returns the value of its first argument modulo
19415 the second; that is to say, it returns the remainder after dividing
19416 the first argument by the second. The value returned has the same
19417 sign as the second argument.
19425 @result{} 0 ;; @r{because there is no remainder}
19432 In this case, the first argument is often smaller than the second.
19444 We can guess what the @code{-} function does. It is like @code{+} but
19445 subtracts instead of adds; the @code{-} function subtracts its second
19446 argument from its first. Also, we already know what the @code{length}
19447 function does (@pxref{length}). It returns the length of a list.
19449 And @code{n} is the name of the required argument to the
19450 @code{current-kill} function.
19453 So when the first argument to @code{nthcdr} is zero, the @code{nthcdr}
19454 expression returns the whole list, as you can see by evaluating the
19459 ;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four}
19460 (nthcdr (mod (- 0 4) 4) ; (mod -4 4) @result{} 0
19461 '("fourth line of text"
19463 "second piece of text"
19464 "first some text"))
19469 When the first argument to the @code{current-kill} function is one,
19470 the @code{nthcdr} expression returns the list without its first
19475 (nthcdr (mod (- 1 4) 4)
19476 '("fourth line of text"
19478 "second piece of text"
19479 "first some text"))
19483 @cindex @samp{global variable} defined
19484 @cindex @samp{variable, global}, defined
19485 Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer}
19486 are @dfn{global variables}. That means that any expression in Emacs
19487 Lisp can access them. They are not like the local variables set by
19488 @code{let} or like the symbols in an argument list.
19489 Local variables can only be accessed
19490 within the @code{let} that defines them or the function that specifies
19491 them in an argument list (and within expressions called by them).
19494 @c texi2dvi fails when the name of the section is within ifnottex ...
19495 (@xref{Prevent confusion, , @code{let} Prevents Confusion}, and
19496 @ref{defun, , The @code{defun} Special Form}.)
19499 @node yank, yank-pop, current-kill, Kill Ring
19500 @comment node-name, next, previous, up
19501 @appendixsec @code{yank}
19504 After learning about @code{current-kill}, the code for the
19505 @code{yank} function is almost easy. It has only one tricky part, which is
19506 the computation of the argument to be passed to @code{rotate-yank-pointer}.
19509 The code looks like this:
19514 (defun yank (&optional arg)
19515 "Reinsert (\"paste\") the last stretch of killed text.
19516 More precisely, reinsert the stretch of killed text most recently
19517 killed OR yanked. Put point at end, and set mark at beginning.
19518 With just \\[universal-argument] as argument, same but put point at
19519 beginning (and mark at end). With argument N, reinsert the Nth most
19520 recently killed stretch of killed text.
19522 When this command inserts killed text into the buffer, it honors
19523 `yank-excluded-properties' and `yank-handler' as described in the
19524 doc string for `insert-for-yank-1', which see.
19526 See also the command \\[yank-pop]."
19530 (setq yank-window-start (window-start))
19531 ;; If we don't get all the way thru, make last-command indicate that
19532 ;; for the following command.
19533 (setq this-command t)
19534 (push-mark (point))
19537 (insert-for-yank (current-kill (cond
19542 ;; This is like exchange-point-and-mark,
19543 ;; but doesn't activate the mark.
19544 ;; It is cleaner to avoid activation, even though the command
19545 ;; loop would deactivate the mark because we inserted text.
19546 (goto-char (prog1 (mark t)
19547 (set-marker (mark-marker) (point) (current-buffer)))))
19550 ;; If we do get all the way thru, make this-command indicate that.
19551 (if (eq this-command t)
19552 (setq this-command 'yank))
19557 The key expression is @code{insert-for-yank}, which inserts the string
19558 returned by @code{current-kill}, but removes some text properties from
19561 However, before getting to that expression, the function set the value
19562 of @code{yank-window-start} to the position returned by the
19563 @code{(window-start)} expression, the position at which the display
19564 currently starts. It also set @code{this-command} and pushed the
19567 After it yanks the appropriate element, if the optional argument is a
19568 @sc{cons} rather than a number or nothing, put point at beginning of
19569 the yanked text and mark at its end. (The @code{prog1} function is
19570 like @code{progn} but returns the value of its first argument rather
19571 than the value of its last argument. Its first argument is forced to
19572 return the buffer's mark as an integer. You can see the documentation
19573 for these functions by placing point over them in this buffer and then
19574 typing @kbd{C-h f} (@code{describe-function}) followed by a @kbd{RET};
19575 the default is the function.)
19577 The last part of the function tells what to do when it succeeds.
19579 @node yank-pop, ring file, yank, Kill Ring
19580 @comment node-name, next, previous, up
19581 @appendixsec @code{yank-pop}
19584 After understanding @code{yank} and @code{current-kill}, you know how
19585 to approach the @code{yank-pop} function Leaving out the documentation
19586 to save space, it looks like this:
19591 (defun yank-pop (&optional arg)
19594 (if (not (eq last-command 'yank))
19595 (error "Previous command was not a yank"))
19598 (setq this-command 'yank)
19599 (unless arg (setq arg 1))
19600 (let ((inhibit-read-only t)
19601 (before (< (point) (mark t))))
19605 (funcall (or yank-undo-function 'delete-region) (point) (mark t))
19606 (funcall (or yank-undo-function 'delete-region) (mark t) (point)))
19607 (setq yank-undo-function nil)
19610 (set-marker (mark-marker) (point) (current-buffer))
19611 (insert-for-yank (current-kill arg))
19612 ;; Set the window start back where it was in the yank command,
19614 (set-window-start (selected-window) yank-window-start t)
19618 ;; This is like exchange-point-and-mark,
19619 ;; but doesn't activate the mark.
19620 ;; It is cleaner to avoid activation, even though the command
19621 ;; loop would deactivate the mark because we inserted text.
19622 (goto-char (prog1 (mark t)
19623 (set-marker (mark-marker)
19625 (current-buffer))))))
19630 The function is interactive with a small @samp{p} so the prefix
19631 argument is processed and passed to the function. The command can
19632 only be used after a previous yank; otherwise an error message is
19633 sent. This check uses the variable @code{last-command} which is
19634 set by @code{yank} and is discussed elsewhere. (@xref{copy-region-as-kill}.)
19636 The @code{let} clause sets the variable @code{before} to true or false
19637 depending whether point is before or after mark and then the region
19638 between point and mark is deleted. This is the region that was just
19639 inserted by the previous yank and it is this text that will be
19642 @code{funcall} calls its first argument as a function, passing
19643 remaining arguments to it. The first argument is whatever the
19644 @code{or} expression returns. The two remaining arguments are the
19645 positions of point and mark set by the preceding @code{yank} command.
19647 There is more, but that is the hardest part.
19649 @node ring file, , yank-pop, Kill Ring
19650 @comment node-name, next, previous, up
19651 @appendixsec The @file{ring.el} File
19652 @cindex @file{ring.el} file
19654 Interestingly, GNU Emacs posses a file called @file{ring.el} that
19655 provides many of the features we just discussed. But functions such
19656 as @code{kill-ring-yank-pointer} do not use this library, possibly
19657 because they were written earlier.
19659 @node Full Graph, Free Software and Free Manuals, Kill Ring, Top
19660 @appendix A Graph with Labelled Axes
19662 Printed axes help you understand a graph. They convey scale. In an
19663 earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we
19664 wrote the code to print the body of a graph. Here we write the code
19665 for printing and labelling vertical and horizontal axes, along with the
19669 * Labelled Example::
19670 * print-graph Varlist::
19673 * Print Whole Graph::
19676 @node Labelled Example, print-graph Varlist, Full Graph, Full Graph
19678 @unnumberedsec Labelled Example Graph
19681 Since insertions fill a buffer to the right and below point, the new
19682 graph printing function should first print the Y or vertical axis,
19683 then the body of the graph, and finally the X or horizontal axis.
19684 This sequence lays out for us the contents of the function:
19694 Print body of graph.
19701 Here is an example of how a finished graph should look:
19714 1 - ****************
19721 In this graph, both the vertical and the horizontal axes are labelled
19722 with numbers. However, in some graphs, the horizontal axis is time
19723 and would be better labelled with months, like this:
19737 Indeed, with a little thought, we can easily come up with a variety of
19738 vertical and horizontal labelling schemes. Our task could become
19739 complicated. But complications breed confusion. Rather than permit
19740 this, it is better choose a simple labelling scheme for our first
19741 effort, and to modify or replace it later.
19744 These considerations suggest the following outline for the
19745 @code{print-graph} function:
19749 (defun print-graph (numbers-list)
19750 "@var{documentation}@dots{}"
19751 (let ((height @dots{}
19755 (print-Y-axis height @dots{} )
19756 (graph-body-print numbers-list)
19757 (print-X-axis @dots{} )))
19761 We can work on each part of the @code{print-graph} function definition
19764 @node print-graph Varlist, print-Y-axis, Labelled Example, Full Graph
19765 @comment node-name, next, previous, up
19766 @appendixsec The @code{print-graph} Varlist
19767 @cindex @code{print-graph} varlist
19769 In writing the @code{print-graph} function, the first task is to write
19770 the varlist in the @code{let} expression. (We will leave aside for the
19771 moment any thoughts about making the function interactive or about the
19772 contents of its documentation string.)
19774 The varlist should set several values. Clearly, the top of the label
19775 for the vertical axis must be at least the height of the graph, which
19776 means that we must obtain this information here. Note that the
19777 @code{print-graph-body} function also requires this information. There
19778 is no reason to calculate the height of the graph in two different
19779 places, so we should change @code{print-graph-body} from the way we
19780 defined it earlier to take advantage of the calculation.
19782 Similarly, both the function for printing the X axis labels and the
19783 @code{print-graph-body} function need to learn the value of the width of
19784 each symbol. We can perform the calculation here and change the
19785 definition for @code{print-graph-body} from the way we defined it in the
19788 The length of the label for the horizontal axis must be at least as long
19789 as the graph. However, this information is used only in the function
19790 that prints the horizontal axis, so it does not need to be calculated here.
19792 These thoughts lead us directly to the following form for the varlist
19793 in the @code{let} for @code{print-graph}:
19797 (let ((height (apply 'max numbers-list)) ; @r{First version.}
19798 (symbol-width (length graph-blank)))
19803 As we shall see, this expression is not quite right.
19806 @node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph
19807 @comment node-name, next, previous, up
19808 @appendixsec The @code{print-Y-axis} Function
19809 @cindex Axis, print vertical
19810 @cindex Y axis printing
19811 @cindex Vertical axis printing
19812 @cindex Print vertical axis
19814 The job of the @code{print-Y-axis} function is to print a label for
19815 the vertical axis that looks like this:
19833 The function should be passed the height of the graph, and then should
19834 construct and insert the appropriate numbers and marks.
19836 It is easy enough to see in the figure what the Y axis label should
19837 look like; but to say in words, and then to write a function
19838 definition to do the job is another matter. It is not quite true to
19839 say that we want a number and a tic every five lines: there are only
19840 three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4),
19841 but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8,
19842 and 9). It is better to say that we want a number and a tic mark on
19843 the base line (number 1) and then that we want a number and a tic on
19844 the fifth line from the bottom and on every line that is a multiple of
19848 * Height of label::
19849 * Compute a Remainder::
19852 * print-Y-axis Penultimate::
19855 @node Height of label, Compute a Remainder, print-Y-axis, print-Y-axis
19857 @unnumberedsubsec What height should the label be?
19860 The next issue is what height the label should be? Suppose the maximum
19861 height of tallest column of the graph is seven. Should the highest
19862 label on the Y axis be @samp{5 -}, and should the graph stick up above
19863 the label? Or should the highest label be @samp{7 -}, and mark the peak
19864 of the graph? Or should the highest label be @code{10 -}, which is a
19865 multiple of five, and be higher than the topmost value of the graph?
19867 The latter form is preferred. Most graphs are drawn within rectangles
19868 whose sides are an integral number of steps long---5, 10, 15, and so
19869 on for a step distance of five. But as soon as we decide to use a
19870 step height for the vertical axis, we discover that the simple
19871 expression in the varlist for computing the height is wrong. The
19872 expression is @code{(apply 'max numbers-list)}. This returns the
19873 precise height, not the maximum height plus whatever is necessary to
19874 round up to the nearest multiple of five. A more complex expression
19877 As usual in cases like this, a complex problem becomes simpler if it is
19878 divided into several smaller problems.
19880 First, consider the case when the highest value of the graph is an
19881 integral multiple of five---when it is 5, 10, 15, or some higher
19882 multiple of five. We can use this value as the Y axis height.
19884 A fairly simply way to determine whether a number is a multiple of
19885 five is to divide it by five and see if the division results in a
19886 remainder. If there is no remainder, the number is a multiple of
19887 five. Thus, seven divided by five has a remainder of two, and seven
19888 is not an integral multiple of five. Put in slightly different
19889 language, more reminiscent of the classroom, five goes into seven
19890 once, with a remainder of two. However, five goes into ten twice,
19891 with no remainder: ten is an integral multiple of five.
19893 @node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis
19894 @appendixsubsec Side Trip: Compute a Remainder
19896 @findex % @r{(remainder function)}
19897 @cindex Remainder function, @code{%}
19898 In Lisp, the function for computing a remainder is @code{%}. The
19899 function returns the remainder of its first argument divided by its
19900 second argument. As it happens, @code{%} is a function in Emacs Lisp
19901 that you cannot discover using @code{apropos}: you find nothing if you
19902 type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to
19903 learn of the existence of @code{%} is to read about it in a book such
19904 as this or in the Emacs Lisp sources.
19906 You can try the @code{%} function by evaluating the following two
19918 The first expression returns 2 and the second expression returns 0.
19920 To test whether the returned value is zero or some other number, we
19921 can use the @code{zerop} function. This function returns @code{t} if
19922 its argument, which must be a number, is zero.
19934 Thus, the following expression will return @code{t} if the height
19935 of the graph is evenly divisible by five:
19938 (zerop (% height 5))
19942 (The value of @code{height}, of course, can be found from @code{(apply
19943 'max numbers-list)}.)
19945 On the other hand, if the value of @code{height} is not a multiple of
19946 five, we want to reset the value to the next higher multiple of five.
19947 This is straightforward arithmetic using functions with which we are
19948 already familiar. First, we divide the value of @code{height} by five
19949 to determine how many times five goes into the number. Thus, five
19950 goes into twelve twice. If we add one to this quotient and multiply by
19951 five, we will obtain the value of the next multiple of five that is
19952 larger than the height. Five goes into twelve twice. Add one to two,
19953 and multiply by five; the result is fifteen, which is the next multiple
19954 of five that is higher than twelve. The Lisp expression for this is:
19957 (* (1+ (/ height 5)) 5)
19961 For example, if you evaluate the following, the result is 15:
19964 (* (1+ (/ 12 5)) 5)
19967 All through this discussion, we have been using `five' as the value
19968 for spacing labels on the Y axis; but we may want to use some other
19969 value. For generality, we should replace `five' with a variable to
19970 which we can assign a value. The best name I can think of for this
19971 variable is @code{Y-axis-label-spacing}.
19974 Using this term, and an @code{if} expression, we produce the
19979 (if (zerop (% height Y-axis-label-spacing))
19982 (* (1+ (/ height Y-axis-label-spacing))
19983 Y-axis-label-spacing))
19988 This expression returns the value of @code{height} itself if the height
19989 is an even multiple of the value of the @code{Y-axis-label-spacing} or
19990 else it computes and returns a value of @code{height} that is equal to
19991 the next higher multiple of the value of the @code{Y-axis-label-spacing}.
19993 We can now include this expression in the @code{let} expression of the
19994 @code{print-graph} function (after first setting the value of
19995 @code{Y-axis-label-spacing}):
19996 @vindex Y-axis-label-spacing
20000 (defvar Y-axis-label-spacing 5
20001 "Number of lines from one Y axis label to next.")
20006 (let* ((height (apply 'max numbers-list))
20007 (height-of-top-line
20008 (if (zerop (% height Y-axis-label-spacing))
20013 (* (1+ (/ height Y-axis-label-spacing))
20014 Y-axis-label-spacing)))
20015 (symbol-width (length graph-blank))))
20021 (Note use of the @code{let*} function: the initial value of height is
20022 computed once by the @code{(apply 'max numbers-list)} expression and
20023 then the resulting value of @code{height} is used to compute its
20024 final value. @xref{fwd-para let, , The @code{let*} expression}, for
20025 more about @code{let*}.)
20027 @node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis
20028 @appendixsubsec Construct a Y Axis Element
20030 When we print the vertical axis, we want to insert strings such as
20031 @w{@samp{5 -}} and @w{@samp{10 - }} every five lines.
20032 Moreover, we want the numbers and dashes to line up, so shorter
20033 numbers must be padded with leading spaces. If some of the strings
20034 use two digit numbers, the strings with single digit numbers must
20035 include a leading blank space before the number.
20037 @findex number-to-string
20038 To figure out the length of the number, the @code{length} function is
20039 used. But the @code{length} function works only with a string, not with
20040 a number. So the number has to be converted from being a number to
20041 being a string. This is done with the @code{number-to-string} function.
20046 (length (number-to-string 35))
20049 (length (number-to-string 100))
20055 (@code{number-to-string} is also called @code{int-to-string}; you will
20056 see this alternative name in various sources.)
20058 In addition, in each label, each number is followed by a string such
20059 as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker.
20060 This variable is defined with @code{defvar}:
20065 (defvar Y-axis-tic " - "
20066 "String that follows number in a Y axis label.")
20070 The length of the Y label is the sum of the length of the Y axis tic
20071 mark and the length of the number of the top of the graph.
20074 (length (concat (number-to-string height) Y-axis-tic)))
20077 This value will be calculated by the @code{print-graph} function in
20078 its varlist as @code{full-Y-label-width} and passed on. (Note that we
20079 did not think to include this in the varlist when we first proposed it.)
20081 To make a complete vertical axis label, a tic mark is concatenated
20082 with a number; and the two together may be preceded by one or more
20083 spaces depending on how long the number is. The label consists of
20084 three parts: the (optional) leading spaces, the number, and the tic
20085 mark. The function is passed the value of the number for the specific
20086 row, and the value of the width of the top line, which is calculated
20087 (just once) by @code{print-graph}.
20091 (defun Y-axis-element (number full-Y-label-width)
20092 "Construct a NUMBERed label element.
20093 A numbered element looks like this ` 5 - ',
20094 and is padded as needed so all line up with
20095 the element for the largest number."
20098 (let* ((leading-spaces
20099 (- full-Y-label-width
20101 (concat (number-to-string number)
20106 (make-string leading-spaces ? )
20107 (number-to-string number)
20112 The @code{Y-axis-element} function concatenates together the leading
20113 spaces, if any; the number, as a string; and the tic mark.
20115 To figure out how many leading spaces the label will need, the
20116 function subtracts the actual length of the label---the length of the
20117 number plus the length of the tic mark---from the desired label width.
20119 @findex make-string
20120 Blank spaces are inserted using the @code{make-string} function. This
20121 function takes two arguments: the first tells it how long the string
20122 will be and the second is a symbol for the character to insert, in a
20123 special format. The format is a question mark followed by a blank
20124 space, like this, @samp{? }. @xref{Character Type, , Character Type,
20125 elisp, The GNU Emacs Lisp Reference Manual}, for a description of the
20126 syntax for characters.
20128 The @code{number-to-string} function is used in the concatenation
20129 expression, to convert the number to a string that is concatenated
20130 with the leading spaces and the tic mark.
20132 @node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis
20133 @appendixsubsec Create a Y Axis Column
20135 The preceding functions provide all the tools needed to construct a
20136 function that generates a list of numbered and blank strings to insert
20137 as the label for the vertical axis:
20139 @findex Y-axis-column
20142 (defun Y-axis-column (height width-of-label)
20143 "Construct list of Y axis labels and blank strings.
20144 For HEIGHT of line above base and WIDTH-OF-LABEL."
20148 (while (> height 1)
20149 (if (zerop (% height Y-axis-label-spacing))
20150 ;; @r{Insert label.}
20153 (Y-axis-element height width-of-label)
20157 ;; @r{Else, insert blanks.}
20160 (make-string width-of-label ? )
20162 (setq height (1- height)))
20163 ;; @r{Insert base line.}
20165 (cons (Y-axis-element 1 width-of-label) Y-axis))
20166 (nreverse Y-axis)))
20170 In this function, we start with the value of @code{height} and
20171 repetitively subtract one from its value. After each subtraction, we
20172 test to see whether the value is an integral multiple of the
20173 @code{Y-axis-label-spacing}. If it is, we construct a numbered label
20174 using the @code{Y-axis-element} function; if not, we construct a
20175 blank label using the @code{make-string} function. The base line
20176 consists of the number one followed by a tic mark.
20179 @node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis
20180 @appendixsubsec The Not Quite Final Version of @code{print-Y-axis}
20182 The list constructed by the @code{Y-axis-column} function is passed to
20183 the @code{print-Y-axis} function, which inserts the list as a column.
20185 @findex print-Y-axis
20188 (defun print-Y-axis (height full-Y-label-width)
20189 "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH.
20190 Height must be the maximum height of the graph.
20191 Full width is the width of the highest label element."
20192 ;; Value of height and full-Y-label-width
20193 ;; are passed by `print-graph'.
20196 (let ((start (point)))
20198 (Y-axis-column height full-Y-label-width))
20199 ;; @r{Place point ready for inserting graph.}
20201 ;; @r{Move point forward by value of} full-Y-label-width
20202 (forward-char full-Y-label-width)))
20206 The @code{print-Y-axis} uses the @code{insert-rectangle} function to
20207 insert the Y axis labels created by the @code{Y-axis-column} function.
20208 In addition, it places point at the correct position for printing the body of
20211 You can test @code{print-Y-axis}:
20219 Y-axis-label-spacing
20228 Copy the following expression:
20231 (print-Y-axis 12 5)
20235 Switch to the @file{*scratch*} buffer and place the cursor where you
20236 want the axis labels to start.
20239 Type @kbd{M-:} (@code{eval-expression}).
20242 Yank the @code{graph-body-print} expression into the minibuffer
20243 with @kbd{C-y} (@code{yank)}.
20246 Press @key{RET} to evaluate the expression.
20249 Emacs will print labels vertically, the top one being
20250 @w{@samp{10 -@w{ }}}. (The @code{print-graph} function
20251 will pass the value of @code{height-of-top-line}, which
20252 in this case would end up as 15.)
20255 @node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph
20256 @appendixsec The @code{print-X-axis} Function
20257 @cindex Axis, print horizontal
20258 @cindex X axis printing
20259 @cindex Print horizontal axis
20260 @cindex Horizontal axis printing
20262 X axis labels are much like Y axis labels, except that the ticks are on a
20263 line above the numbers. Labels should look like this:
20272 The first tic is under the first column of the graph and is preceded by
20273 several blank spaces. These spaces provide room in rows above for the Y
20274 axis labels. The second, third, fourth, and subsequent ticks are all
20275 spaced equally, according to the value of @code{X-axis-label-spacing}.
20277 The second row of the X axis consists of numbers, preceded by several
20278 blank spaces and also separated according to the value of the variable
20279 @code{X-axis-label-spacing}.
20281 The value of the variable @code{X-axis-label-spacing} should itself be
20282 measured in units of @code{symbol-width}, since you may want to change
20283 the width of the symbols that you are using to print the body of the
20284 graph without changing the ways the graph is labelled.
20287 * Similarities differences::
20288 * X Axis Tic Marks::
20291 @node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis
20293 @unnumberedsubsec Similarities and differences
20296 The @code{print-X-axis} function is constructed in more or less the
20297 same fashion as the @code{print-Y-axis} function except that it has
20298 two lines: the line of tic marks and the numbers. We will write a
20299 separate function to print each line and then combine them within the
20300 @code{print-X-axis} function.
20302 This is a three step process:
20306 Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}.
20309 Write a function to print the X numbers, @code{print-X-axis-numbered-line}.
20312 Write a function to print both lines, the @code{print-X-axis} function,
20313 using @code{print-X-axis-tic-line} and
20314 @code{print-X-axis-numbered-line}.
20317 @node X Axis Tic Marks, , Similarities differences, print-X-axis
20318 @appendixsubsec X Axis Tic Marks
20320 The first function should print the X axis tic marks. We must specify
20321 the tic marks themselves and their spacing:
20325 (defvar X-axis-label-spacing
20326 (if (boundp 'graph-blank)
20327 (* 5 (length graph-blank)) 5)
20328 "Number of units from one X axis label to next.")
20333 (Note that the value of @code{graph-blank} is set by another
20334 @code{defvar}. The @code{boundp} predicate checks whether it has
20335 already been set; @code{boundp} returns @code{nil} if it has not.
20336 If @code{graph-blank} were unbound and we did not use this conditional
20337 construction, in GNU Emacs 21, we would enter the debugger and see an
20338 error message saying
20339 @samp{@w{Debugger entered--Lisp error:} @w{(void-variable graph-blank)}}.)
20342 Here is the @code{defvar} for @code{X-axis-tic-symbol}:
20346 (defvar X-axis-tic-symbol "|"
20347 "String to insert to point to a column in X axis.")
20352 The goal is to make a line that looks like this:
20358 The first tic is indented so that it is under the first column, which is
20359 indented to provide space for the Y axis labels.
20361 A tic element consists of the blank spaces that stretch from one tic to
20362 the next plus a tic symbol. The number of blanks is determined by the
20363 width of the tic symbol and the @code{X-axis-label-spacing}.
20366 The code looks like this:
20370 ;;; X-axis-tic-element
20374 ;; @r{Make a string of blanks.}
20375 (- (* symbol-width X-axis-label-spacing)
20376 (length X-axis-tic-symbol))
20378 ;; @r{Concatenate blanks with tic symbol.}
20384 Next, we determine how many blanks are needed to indent the first tic
20385 mark to the first column of the graph. This uses the value of
20386 @code{full-Y-label-width} passed it by the @code{print-graph} function.
20389 The code to make @code{X-axis-leading-spaces}
20394 ;; X-axis-leading-spaces
20396 (make-string full-Y-label-width ? )
20401 We also need to determine the length of the horizontal axis, which is
20402 the length of the numbers list, and the number of ticks in the horizontal
20409 (length numbers-list)
20415 (* symbol-width X-axis-label-spacing)
20419 ;; number-of-X-ticks
20420 (if (zerop (% (X-length tic-width)))
20421 (/ (X-length tic-width))
20422 (1+ (/ (X-length tic-width))))
20427 All this leads us directly to the function for printing the X axis tic line:
20429 @findex print-X-axis-tic-line
20432 (defun print-X-axis-tic-line
20433 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
20434 "Print ticks for X axis."
20435 (insert X-axis-leading-spaces)
20436 (insert X-axis-tic-symbol) ; @r{Under first column.}
20439 ;; @r{Insert second tic in the right spot.}
20442 (- (* symbol-width X-axis-label-spacing)
20443 ;; @r{Insert white space up to second tic symbol.}
20444 (* 2 (length X-axis-tic-symbol)))
20446 X-axis-tic-symbol))
20449 ;; @r{Insert remaining ticks.}
20450 (while (> number-of-X-tics 1)
20451 (insert X-axis-tic-element)
20452 (setq number-of-X-tics (1- number-of-X-tics))))
20456 The line of numbers is equally straightforward:
20459 First, we create a numbered element with blank spaces before each number:
20461 @findex X-axis-element
20464 (defun X-axis-element (number)
20465 "Construct a numbered X axis element."
20466 (let ((leading-spaces
20467 (- (* symbol-width X-axis-label-spacing)
20468 (length (number-to-string number)))))
20469 (concat (make-string leading-spaces ? )
20470 (number-to-string number))))
20474 Next, we create the function to print the numbered line, starting with
20475 the number ``1'' under the first column:
20477 @findex print-X-axis-numbered-line
20480 (defun print-X-axis-numbered-line
20481 (number-of-X-tics X-axis-leading-spaces)
20482 "Print line of X-axis numbers"
20483 (let ((number X-axis-label-spacing))
20484 (insert X-axis-leading-spaces)
20490 ;; @r{Insert white space up to next number.}
20491 (- (* symbol-width X-axis-label-spacing) 2)
20493 (number-to-string number)))
20496 ;; @r{Insert remaining numbers.}
20497 (setq number (+ number X-axis-label-spacing))
20498 (while (> number-of-X-tics 1)
20499 (insert (X-axis-element number))
20500 (setq number (+ number X-axis-label-spacing))
20501 (setq number-of-X-tics (1- number-of-X-tics)))))
20505 Finally, we need to write the @code{print-X-axis} that uses
20506 @code{print-X-axis-tic-line} and
20507 @code{print-X-axis-numbered-line}.
20509 The function must determine the local values of the variables used by both
20510 @code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and
20511 then it must call them. Also, it must print the carriage return that
20512 separates the two lines.
20514 The function consists of a varlist that specifies five local variables,
20515 and calls to each of the two line printing functions:
20517 @findex print-X-axis
20520 (defun print-X-axis (numbers-list)
20521 "Print X axis labels to length of NUMBERS-LIST."
20522 (let* ((leading-spaces
20523 (make-string full-Y-label-width ? ))
20526 ;; symbol-width @r{is provided by} graph-body-print
20527 (tic-width (* symbol-width X-axis-label-spacing))
20528 (X-length (length numbers-list))
20536 ;; @r{Make a string of blanks.}
20537 (- (* symbol-width X-axis-label-spacing)
20538 (length X-axis-tic-symbol))
20542 ;; @r{Concatenate blanks with tic symbol.}
20543 X-axis-tic-symbol))
20547 (if (zerop (% X-length tic-width))
20548 (/ X-length tic-width)
20549 (1+ (/ X-length tic-width)))))
20552 (print-X-axis-tic-line tic-number leading-spaces X-tic)
20554 (print-X-axis-numbered-line tic-number leading-spaces)))
20559 You can test @code{print-X-axis}:
20563 Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing},
20564 @code{print-X-axis-tic-line}, as well as @code{X-axis-element},
20565 @code{print-X-axis-numbered-line}, and @code{print-X-axis}.
20568 Copy the following expression:
20573 (let ((full-Y-label-width 5)
20576 '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16))))
20581 Switch to the @file{*scratch*} buffer and place the cursor where you
20582 want the axis labels to start.
20585 Type @kbd{M-:} (@code{eval-expression}).
20588 Yank the test expression into the minibuffer
20589 with @kbd{C-y} (@code{yank)}.
20592 Press @key{RET} to evaluate the expression.
20596 Emacs will print the horizontal axis like this:
20606 @node Print Whole Graph, , print-X-axis, Full Graph
20607 @appendixsec Printing the Whole Graph
20608 @cindex Printing the whole graph
20609 @cindex Whole graph printing
20610 @cindex Graph, printing all
20612 Now we are nearly ready to print the whole graph.
20614 The function to print the graph with the proper labels follows the
20615 outline we created earlier (@pxref{Full Graph, , A Graph with Labelled
20616 Axes}), but with additions.
20619 Here is the outline:
20623 (defun print-graph (numbers-list)
20624 "@var{documentation}@dots{}"
20625 (let ((height @dots{}
20629 (print-Y-axis height @dots{} )
20630 (graph-body-print numbers-list)
20631 (print-X-axis @dots{} )))
20636 * The final version::
20637 * Test print-graph::
20638 * Graphing words in defuns::
20642 * Final printed graph::
20645 @node The final version, Test print-graph, Print Whole Graph, Print Whole Graph
20647 @unnumberedsubsec Changes for the Final Version
20650 The final version is different from what we planned in two ways:
20651 first, it contains additional values calculated once in the varlist;
20652 second, it carries an option to specify the labels' increment per row.
20653 This latter feature turns out to be essential; otherwise, a graph may
20654 have more rows than fit on a display or on a sheet of paper.
20657 This new feature requires a change to the @code{Y-axis-column}
20658 function, to add @code{vertical-step} to it. The function looks like
20661 @findex Y-axis-column @r{Final version.}
20664 ;;; @r{Final version.}
20665 (defun Y-axis-column
20666 (height width-of-label &optional vertical-step)
20667 "Construct list of labels for Y axis.
20668 HEIGHT is maximum height of graph.
20669 WIDTH-OF-LABEL is maximum width of label.
20670 VERTICAL-STEP, an option, is a positive integer
20671 that specifies how much a Y axis label increments
20672 for each line. For example, a step of 5 means
20673 that each line is five units of the graph."
20677 (number-per-line (or vertical-step 1)))
20678 (while (> height 1)
20679 (if (zerop (% height Y-axis-label-spacing))
20682 ;; @r{Insert label.}
20686 (* height number-per-line)
20691 ;; @r{Else, insert blanks.}
20694 (make-string width-of-label ? )
20696 (setq height (1- height)))
20699 ;; @r{Insert base line.}
20700 (setq Y-axis (cons (Y-axis-element
20701 (or vertical-step 1)
20704 (nreverse Y-axis)))
20708 The values for the maximum height of graph and the width of a symbol
20709 are computed by @code{print-graph} in its @code{let} expression; so
20710 @code{graph-body-print} must be changed to accept them.
20712 @findex graph-body-print @r{Final version.}
20715 ;;; @r{Final version.}
20716 (defun graph-body-print (numbers-list height symbol-width)
20717 "Print a bar graph of the NUMBERS-LIST.
20718 The numbers-list consists of the Y-axis values.
20719 HEIGHT is maximum height of graph.
20720 SYMBOL-WIDTH is number of each column."
20723 (let (from-position)
20724 (while numbers-list
20725 (setq from-position (point))
20727 (column-of-graph height (car numbers-list)))
20728 (goto-char from-position)
20729 (forward-char symbol-width)
20732 ;; @r{Draw graph column by column.}
20734 (setq numbers-list (cdr numbers-list)))
20735 ;; @r{Place point for X axis labels.}
20736 (forward-line height)
20742 Finally, the code for the @code{print-graph} function:
20744 @findex print-graph @r{Final version.}
20747 ;;; @r{Final version.}
20749 (numbers-list &optional vertical-step)
20750 "Print labelled bar graph of the NUMBERS-LIST.
20751 The numbers-list consists of the Y-axis values.
20755 Optionally, VERTICAL-STEP, a positive integer,
20756 specifies how much a Y axis label increments for
20757 each line. For example, a step of 5 means that
20758 each row is five units."
20761 (let* ((symbol-width (length graph-blank))
20762 ;; @code{height} @r{is both the largest number}
20763 ;; @r{and the number with the most digits.}
20764 (height (apply 'max numbers-list))
20767 (height-of-top-line
20768 (if (zerop (% height Y-axis-label-spacing))
20771 (* (1+ (/ height Y-axis-label-spacing))
20772 Y-axis-label-spacing)))
20775 (vertical-step (or vertical-step 1))
20776 (full-Y-label-width
20782 (* height-of-top-line vertical-step))
20788 height-of-top-line full-Y-label-width vertical-step)
20792 numbers-list height-of-top-line symbol-width)
20793 (print-X-axis numbers-list)))
20797 @node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph
20798 @appendixsubsec Testing @code{print-graph}
20801 We can test the @code{print-graph} function with a short list of numbers:
20805 Install the final versions of @code{Y-axis-column},
20806 @code{graph-body-print}, and @code{print-graph} (in addition to the
20810 Copy the following expression:
20813 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1))
20817 Switch to the @file{*scratch*} buffer and place the cursor where you
20818 want the axis labels to start.
20821 Type @kbd{M-:} (@code{eval-expression}).
20824 Yank the test expression into the minibuffer
20825 with @kbd{C-y} (@code{yank)}.
20828 Press @key{RET} to evaluate the expression.
20832 Emacs will print a graph that looks like this:
20853 On the other hand, if you pass @code{print-graph} a
20854 @code{vertical-step} value of 2, by evaluating this expression:
20857 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2)
20862 The graph looks like this:
20883 (A question: is the `2' on the bottom of the vertical axis a bug or a
20884 feature? If you think it is a bug, and should be a `1' instead, (or
20885 even a `0'), you can modify the sources.)
20887 @node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph
20888 @appendixsubsec Graphing Numbers of Words and Symbols
20890 Now for the graph for which all this code was written: a graph that
20891 shows how many function definitions contain fewer than 10 words and
20892 symbols, how many contain between 10 and 19 words and symbols, how
20893 many contain between 20 and 29 words and symbols, and so on.
20895 This is a multi-step process. First make sure you have loaded all the
20899 It is a good idea to reset the value of @code{top-of-ranges} in case
20900 you have set it to some different value. You can evaluate the
20905 (setq top-of-ranges
20908 110 120 130 140 150
20909 160 170 180 190 200
20910 210 220 230 240 250
20911 260 270 280 290 300)
20916 Next create a list of the number of words and symbols in each range.
20920 Evaluate the following:
20924 (setq list-for-graph
20927 (recursive-lengths-list-many-files
20928 (directory-files "/usr/local/emacs/lisp"
20936 On my old machine, this took about an hour. It looked though 303 Lisp
20937 files in my copy of Emacs version 19.23. After all that computing,
20938 the @code{list-for-graph} had this value:
20942 (537 1027 955 785 594 483 349 292 224 199 166 120 116 99
20943 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220)
20948 This means that my copy of Emacs had 537 function definitions with
20949 fewer than 10 words or symbols in them, 1,027 function definitions
20950 with 10 to 19 words or symbols in them, 955 function definitions with
20951 20 to 29 words or symbols in them, and so on.
20953 Clearly, just by looking at this list we can see that most function
20954 definitions contain ten to thirty words and symbols.
20956 Now for printing. We do @emph{not} want to print a graph that is
20957 1,030 lines high @dots{} Instead, we should print a graph that is
20958 fewer than twenty-five lines high. A graph that height can be
20959 displayed on almost any monitor, and easily printed on a sheet of paper.
20961 This means that each value in @code{list-for-graph} must be reduced to
20962 one-fiftieth its present value.
20964 Here is a short function to do just that, using two functions we have
20965 not yet seen, @code{mapcar} and @code{lambda}.
20969 (defun one-fiftieth (full-range)
20970 "Return list, each number one-fiftieth of previous."
20971 (mapcar '(lambda (arg) (/ arg 50)) full-range))
20975 @node lambda, mapcar, Graphing words in defuns, Print Whole Graph
20976 @appendixsubsec A @code{lambda} Expression: Useful Anonymity
20977 @cindex Anonymous function
20980 @code{lambda} is the symbol for an anonymous function, a function
20981 without a name. Every time you use an anonymous function, you need to
20982 include its whole body.
20989 (lambda (arg) (/ arg 50))
20993 is a function definition that says `return the value resulting from
20994 dividing whatever is passed to me as @code{arg} by 50'.
20997 Earlier, for example, we had a function @code{multiply-by-seven}; it
20998 multiplied its argument by 7. This function is similar, except it
20999 divides its argument by 50; and, it has no name. The anonymous
21000 equivalent of @code{multiply-by-seven} is:
21003 (lambda (number) (* 7 number))
21007 (@xref{defun, , The @code{defun} Special Form}.)
21011 If we want to multiply 3 by 7, we can write:
21013 @c !!! Clear print-postscript-figures if the computer formatting this
21014 @c document is too small and cannot handle all the diagrams and figures.
21015 @c clear print-postscript-figures
21016 @c set print-postscript-figures
21017 @c lambda example diagram #1
21021 (multiply-by-seven 3)
21022 \_______________/ ^
21028 @ifset print-postscript-figures
21032 %%%% old method of including an image
21033 % \input /usr/local/lib/tex/inputs/psfig.tex
21034 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}}
21039 @ifclear print-postscript-figures
21043 (multiply-by-seven 3)
21044 \_______________/ ^
21053 This expression returns 21.
21057 Similarly, we can write:
21059 @c lambda example diagram #2
21063 ((lambda (number) (* 7 number)) 3)
21064 \____________________________/ ^
21066 anonymous function argument
21070 @ifset print-postscript-figures
21074 %%%% old method of including an image
21075 % \input /usr/local/lib/tex/inputs/psfig.tex
21076 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}}
21081 @ifclear print-postscript-figures
21085 ((lambda (number) (* 7 number)) 3)
21086 \____________________________/ ^
21088 anonymous function argument
21096 If we want to divide 100 by 50, we can write:
21098 @c lambda example diagram #3
21102 ((lambda (arg) (/ arg 50)) 100)
21103 \______________________/ \_/
21105 anonymous function argument
21109 @ifset print-postscript-figures
21113 %%%% old method of including an image
21114 % \input /usr/local/lib/tex/inputs/psfig.tex
21115 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}}
21120 @ifclear print-postscript-figures
21124 ((lambda (arg) (/ arg 50)) 100)
21125 \______________________/ \_/
21127 anonymous function argument
21134 This expression returns 2. The 100 is passed to the function, which
21135 divides that number by 50.
21137 @xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs
21138 Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda
21139 expressions derive from the Lambda Calculus.
21141 @node mapcar, Another Bug, lambda, Print Whole Graph
21142 @appendixsubsec The @code{mapcar} Function
21145 @code{mapcar} is a function that calls its first argument with each
21146 element of its second argument, in turn. The second argument must be
21149 The @samp{map} part of the name comes from the mathematical phrase,
21150 `mapping over a domain', meaning to apply a function to each of the
21151 elements in a domain. The mathematical phrase is based on the
21152 metaphor of a surveyor walking, one step at a time, over an area he is
21153 mapping. And @samp{car}, of course, comes from the Lisp notion of the
21162 (mapcar '1+ '(2 4 6))
21168 The function @code{1+} which adds one to its argument, is executed on
21169 @emph{each} element of the list, and a new list is returned.
21171 Contrast this with @code{apply}, which applies its first argument to
21173 (@xref{Readying a Graph, , Readying a Graph}, for a explanation of
21177 In the definition of @code{one-fiftieth}, the first argument is the
21178 anonymous function:
21181 (lambda (arg) (/ arg 50))
21185 and the second argument is @code{full-range}, which will be bound to
21186 @code{list-for-graph}.
21189 The whole expression looks like this:
21192 (mapcar '(lambda (arg) (/ arg 50)) full-range))
21195 @xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs
21196 Lisp Reference Manual}, for more about @code{mapcar}.
21198 Using the @code{one-fiftieth} function, we can generate a list in
21199 which each element is one-fiftieth the size of the corresponding
21200 element in @code{list-for-graph}.
21204 (setq fiftieth-list-for-graph
21205 (one-fiftieth list-for-graph))
21210 The resulting list looks like this:
21214 (10 20 19 15 11 9 6 5 4 3 3 2 2
21215 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4)
21220 This, we are almost ready to print! (We also notice the loss of
21221 information: many of the higher ranges are 0, meaning that fewer than
21222 50 defuns had that many words or symbols---but not necessarily meaning
21223 that none had that many words or symbols.)
21225 @node Another Bug, Final printed graph, mapcar, Print Whole Graph
21226 @appendixsubsec Another Bug @dots{} Most Insidious
21227 @cindex Bug, most insidious type
21228 @cindex Insidious type of bug
21230 I said `almost ready to print'! Of course, there is a bug in the
21231 @code{print-graph} function @dots{} It has a @code{vertical-step}
21232 option, but not a @code{horizontal-step} option. The
21233 @code{top-of-range} scale goes from 10 to 300 by tens. But the
21234 @code{print-graph} function will print only by ones.
21236 This is a classic example of what some consider the most insidious
21237 type of bug, the bug of omission. This is not the kind of bug you can
21238 find by studying the code, for it is not in the code; it is an omitted
21239 feature. Your best actions are to try your program early and often;
21240 and try to arrange, as much as you can, to write code that is easy to
21241 understand and easy to change. Try to be aware, whenever you can,
21242 that whatever you have written, @emph{will} be rewritten, if not soon,
21243 eventually. A hard maxim to follow.
21245 It is the @code{print-X-axis-numbered-line} function that needs the
21246 work; and then the @code{print-X-axis} and the @code{print-graph}
21247 functions need to be adapted. Not much needs to be done; there is one
21248 nicety: the numbers ought to line up under the tic marks. This takes
21252 Here is the corrected @code{print-X-axis-numbered-line}:
21256 (defun print-X-axis-numbered-line
21257 (number-of-X-tics X-axis-leading-spaces
21258 &optional horizontal-step)
21259 "Print line of X-axis numbers"
21260 (let ((number X-axis-label-spacing)
21261 (horizontal-step (or horizontal-step 1)))
21264 (insert X-axis-leading-spaces)
21265 ;; @r{Delete extra leading spaces.}
21268 (length (number-to-string horizontal-step)))))
21273 ;; @r{Insert white space.}
21275 X-axis-label-spacing)
21278 (number-to-string horizontal-step)))
21282 (* number horizontal-step))))
21285 ;; @r{Insert remaining numbers.}
21286 (setq number (+ number X-axis-label-spacing))
21287 (while (> number-of-X-tics 1)
21288 (insert (X-axis-element
21289 (* number horizontal-step)))
21290 (setq number (+ number X-axis-label-spacing))
21291 (setq number-of-X-tics (1- number-of-X-tics)))))
21296 If you are reading this in Info, you can see the new versions of
21297 @code{print-X-axis} @code{print-graph} and evaluate them. If you are
21298 reading this in a printed book, you can see the changed lines here
21299 (the full text is too much to print).
21304 (defun print-X-axis (numbers-list horizontal-step)
21306 (print-X-axis-numbered-line
21307 tic-number leading-spaces horizontal-step))
21315 &optional vertical-step horizontal-step)
21317 (print-X-axis numbers-list horizontal-step))
21325 (defun print-X-axis (numbers-list horizontal-step)
21326 "Print X axis labels to length of NUMBERS-LIST.
21327 Optionally, HORIZONTAL-STEP, a positive integer,
21328 specifies how much an X axis label increments for
21332 ;; Value of symbol-width and full-Y-label-width
21333 ;; are passed by `print-graph'.
21334 (let* ((leading-spaces
21335 (make-string full-Y-label-width ? ))
21336 ;; symbol-width @r{is provided by} graph-body-print
21337 (tic-width (* symbol-width X-axis-label-spacing))
21338 (X-length (length numbers-list))
21344 ;; @r{Make a string of blanks.}
21345 (- (* symbol-width X-axis-label-spacing)
21346 (length X-axis-tic-symbol))
21350 ;; @r{Concatenate blanks with tic symbol.}
21351 X-axis-tic-symbol))
21353 (if (zerop (% X-length tic-width))
21354 (/ X-length tic-width)
21355 (1+ (/ X-length tic-width)))))
21359 (print-X-axis-tic-line
21360 tic-number leading-spaces X-tic)
21362 (print-X-axis-numbered-line
21363 tic-number leading-spaces horizontal-step)))
21370 (numbers-list &optional vertical-step horizontal-step)
21371 "Print labelled bar graph of the NUMBERS-LIST.
21372 The numbers-list consists of the Y-axis values.
21376 Optionally, VERTICAL-STEP, a positive integer,
21377 specifies how much a Y axis label increments for
21378 each line. For example, a step of 5 means that
21379 each row is five units.
21383 Optionally, HORIZONTAL-STEP, a positive integer,
21384 specifies how much an X axis label increments for
21386 (let* ((symbol-width (length graph-blank))
21387 ;; @code{height} @r{is both the largest number}
21388 ;; @r{and the number with the most digits.}
21389 (height (apply 'max numbers-list))
21392 (height-of-top-line
21393 (if (zerop (% height Y-axis-label-spacing))
21396 (* (1+ (/ height Y-axis-label-spacing))
21397 Y-axis-label-spacing)))
21400 (vertical-step (or vertical-step 1))
21401 (full-Y-label-width
21405 (* height-of-top-line vertical-step))
21410 height-of-top-line full-Y-label-width vertical-step)
21412 numbers-list height-of-top-line symbol-width)
21413 (print-X-axis numbers-list horizontal-step)))
21420 Graphing Definitions Re-listed
21423 Here are all the graphing definitions in their final form:
21427 (defvar top-of-ranges
21430 110 120 130 140 150
21431 160 170 180 190 200
21432 210 220 230 240 250)
21433 "List specifying ranges for `defuns-per-range'.")
21437 (defvar graph-symbol "*"
21438 "String used as symbol in graph, usually an asterisk.")
21442 (defvar graph-blank " "
21443 "String used as blank in graph, usually a blank space.
21444 graph-blank must be the same number of columns wide
21449 (defvar Y-axis-tic " - "
21450 "String that follows number in a Y axis label.")
21454 (defvar Y-axis-label-spacing 5
21455 "Number of lines from one Y axis label to next.")
21459 (defvar X-axis-tic-symbol "|"
21460 "String to insert to point to a column in X axis.")
21464 (defvar X-axis-label-spacing
21465 (if (boundp 'graph-blank)
21466 (* 5 (length graph-blank)) 5)
21467 "Number of units from one X axis label to next.")
21473 (defun count-words-in-defun ()
21474 "Return the number of words and symbols in a defun."
21475 (beginning-of-defun)
21477 (end (save-excursion (end-of-defun) (point))))
21482 (and (< (point) end)
21484 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
21486 (setq count (1+ count)))
21493 (defun lengths-list-file (filename)
21494 "Return list of definitions' lengths within FILE.
21495 The returned list is a list of numbers.
21496 Each number is the number of words or
21497 symbols in one function definition."
21501 (message "Working on `%s' ... " filename)
21503 (let ((buffer (find-file-noselect filename))
21505 (set-buffer buffer)
21506 (setq buffer-read-only t)
21508 (goto-char (point-min))
21512 (while (re-search-forward "^(defun" nil t)
21514 (cons (count-words-in-defun) lengths-list)))
21515 (kill-buffer buffer)
21522 (defun lengths-list-many-files (list-of-files)
21523 "Return list of lengths of defuns in LIST-OF-FILES."
21524 (let (lengths-list)
21525 ;;; @r{true-or-false-test}
21526 (while list-of-files
21532 ;;; @r{Generate a lengths' list.}
21534 (expand-file-name (car list-of-files)))))
21535 ;;; @r{Make files' list shorter.}
21536 (setq list-of-files (cdr list-of-files)))
21537 ;;; @r{Return final value of lengths' list.}
21544 (defun defuns-per-range (sorted-lengths top-of-ranges)
21545 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
21546 (let ((top-of-range (car top-of-ranges))
21547 (number-within-range 0)
21548 defuns-per-range-list)
21553 (while top-of-ranges
21557 ;; @r{Need number for numeric test.}
21558 (car sorted-lengths)
21559 (< (car sorted-lengths) top-of-range))
21561 ;; @r{Count number of definitions within current range.}
21562 (setq number-within-range (1+ number-within-range))
21563 (setq sorted-lengths (cdr sorted-lengths)))
21567 ;; @r{Exit inner loop but remain within outer loop.}
21569 (setq defuns-per-range-list
21570 (cons number-within-range defuns-per-range-list))
21571 (setq number-within-range 0) ; @r{Reset count to zero.}
21573 ;; @r{Move to next range.}
21574 (setq top-of-ranges (cdr top-of-ranges))
21575 ;; @r{Specify next top of range value.}
21576 (setq top-of-range (car top-of-ranges)))
21580 ;; @r{Exit outer loop and count the number of defuns larger than}
21581 ;; @r{ the largest top-of-range value.}
21582 (setq defuns-per-range-list
21584 (length sorted-lengths)
21585 defuns-per-range-list))
21587 ;; @r{Return a list of the number of definitions within each range,}
21588 ;; @r{ smallest to largest.}
21589 (nreverse defuns-per-range-list)))
21595 (defun column-of-graph (max-graph-height actual-height)
21596 "Return list of MAX-GRAPH-HEIGHT strings;
21597 ACTUAL-HEIGHT are graph-symbols.
21598 The graph-symbols are contiguous entries at the end
21600 The list will be inserted as one column of a graph.
21601 The strings are either graph-blank or graph-symbol."
21605 (let ((insert-list nil)
21606 (number-of-top-blanks
21607 (- max-graph-height actual-height)))
21609 ;; @r{Fill in @code{graph-symbols}.}
21610 (while (> actual-height 0)
21611 (setq insert-list (cons graph-symbol insert-list))
21612 (setq actual-height (1- actual-height)))
21616 ;; @r{Fill in @code{graph-blanks}.}
21617 (while (> number-of-top-blanks 0)
21618 (setq insert-list (cons graph-blank insert-list))
21619 (setq number-of-top-blanks
21620 (1- number-of-top-blanks)))
21622 ;; @r{Return whole list.}
21629 (defun Y-axis-element (number full-Y-label-width)
21630 "Construct a NUMBERed label element.
21631 A numbered element looks like this ` 5 - ',
21632 and is padded as needed so all line up with
21633 the element for the largest number."
21636 (let* ((leading-spaces
21637 (- full-Y-label-width
21639 (concat (number-to-string number)
21644 (make-string leading-spaces ? )
21645 (number-to-string number)
21652 (defun print-Y-axis
21653 (height full-Y-label-width &optional vertical-step)
21654 "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH.
21655 Height must be the maximum height of the graph.
21656 Full width is the width of the highest label element.
21657 Optionally, print according to VERTICAL-STEP."
21660 ;; Value of height and full-Y-label-width
21661 ;; are passed by `print-graph'.
21662 (let ((start (point)))
21664 (Y-axis-column height full-Y-label-width vertical-step))
21667 ;; @r{Place point ready for inserting graph.}
21669 ;; @r{Move point forward by value of} full-Y-label-width
21670 (forward-char full-Y-label-width)))
21676 (defun print-X-axis-tic-line
21677 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
21678 "Print ticks for X axis."
21679 (insert X-axis-leading-spaces)
21680 (insert X-axis-tic-symbol) ; @r{Under first column.}
21683 ;; @r{Insert second tic in the right spot.}
21686 (- (* symbol-width X-axis-label-spacing)
21687 ;; @r{Insert white space up to second tic symbol.}
21688 (* 2 (length X-axis-tic-symbol)))
21690 X-axis-tic-symbol))
21693 ;; @r{Insert remaining ticks.}
21694 (while (> number-of-X-tics 1)
21695 (insert X-axis-tic-element)
21696 (setq number-of-X-tics (1- number-of-X-tics))))
21702 (defun X-axis-element (number)
21703 "Construct a numbered X axis element."
21704 (let ((leading-spaces
21705 (- (* symbol-width X-axis-label-spacing)
21706 (length (number-to-string number)))))
21707 (concat (make-string leading-spaces ? )
21708 (number-to-string number))))
21714 (defun graph-body-print (numbers-list height symbol-width)
21715 "Print a bar graph of the NUMBERS-LIST.
21716 The numbers-list consists of the Y-axis values.
21717 HEIGHT is maximum height of graph.
21718 SYMBOL-WIDTH is number of each column."
21721 (let (from-position)
21722 (while numbers-list
21723 (setq from-position (point))
21725 (column-of-graph height (car numbers-list)))
21726 (goto-char from-position)
21727 (forward-char symbol-width)
21730 ;; @r{Draw graph column by column.}
21732 (setq numbers-list (cdr numbers-list)))
21733 ;; @r{Place point for X axis labels.}
21734 (forward-line height)
21741 (defun Y-axis-column
21742 (height width-of-label &optional vertical-step)
21743 "Construct list of labels for Y axis.
21744 HEIGHT is maximum height of graph.
21745 WIDTH-OF-LABEL is maximum width of label.
21748 VERTICAL-STEP, an option, is a positive integer
21749 that specifies how much a Y axis label increments
21750 for each line. For example, a step of 5 means
21751 that each line is five units of the graph."
21753 (number-per-line (or vertical-step 1)))
21756 (while (> height 1)
21757 (if (zerop (% height Y-axis-label-spacing))
21758 ;; @r{Insert label.}
21762 (* height number-per-line)
21767 ;; @r{Else, insert blanks.}
21770 (make-string width-of-label ? )
21772 (setq height (1- height)))
21775 ;; @r{Insert base line.}
21776 (setq Y-axis (cons (Y-axis-element
21777 (or vertical-step 1)
21780 (nreverse Y-axis)))
21786 (defun print-X-axis-numbered-line
21787 (number-of-X-tics X-axis-leading-spaces
21788 &optional horizontal-step)
21789 "Print line of X-axis numbers"
21790 (let ((number X-axis-label-spacing)
21791 (horizontal-step (or horizontal-step 1)))
21794 (insert X-axis-leading-spaces)
21796 (delete-char (- (1- (length (number-to-string horizontal-step)))))
21799 ;; @r{Insert white space up to next number.}
21800 (- (* symbol-width X-axis-label-spacing)
21801 (1- (length (number-to-string horizontal-step)))
21804 (number-to-string (* number horizontal-step))))
21807 ;; @r{Insert remaining numbers.}
21808 (setq number (+ number X-axis-label-spacing))
21809 (while (> number-of-X-tics 1)
21810 (insert (X-axis-element (* number horizontal-step)))
21811 (setq number (+ number X-axis-label-spacing))
21812 (setq number-of-X-tics (1- number-of-X-tics)))))
21818 (defun print-X-axis (numbers-list horizontal-step)
21819 "Print X axis labels to length of NUMBERS-LIST.
21820 Optionally, HORIZONTAL-STEP, a positive integer,
21821 specifies how much an X axis label increments for
21825 ;; Value of symbol-width and full-Y-label-width
21826 ;; are passed by `print-graph'.
21827 (let* ((leading-spaces
21828 (make-string full-Y-label-width ? ))
21829 ;; symbol-width @r{is provided by} graph-body-print
21830 (tic-width (* symbol-width X-axis-label-spacing))
21831 (X-length (length numbers-list))
21837 ;; @r{Make a string of blanks.}
21838 (- (* symbol-width X-axis-label-spacing)
21839 (length X-axis-tic-symbol))
21843 ;; @r{Concatenate blanks with tic symbol.}
21844 X-axis-tic-symbol))
21846 (if (zerop (% X-length tic-width))
21847 (/ X-length tic-width)
21848 (1+ (/ X-length tic-width)))))
21852 (print-X-axis-tic-line
21853 tic-number leading-spaces X-tic)
21855 (print-X-axis-numbered-line
21856 tic-number leading-spaces horizontal-step)))
21862 (defun one-fiftieth (full-range)
21863 "Return list, each number of which is 1/50th previous."
21864 (mapcar '(lambda (arg) (/ arg 50)) full-range))
21871 (numbers-list &optional vertical-step horizontal-step)
21872 "Print labelled bar graph of the NUMBERS-LIST.
21873 The numbers-list consists of the Y-axis values.
21877 Optionally, VERTICAL-STEP, a positive integer,
21878 specifies how much a Y axis label increments for
21879 each line. For example, a step of 5 means that
21880 each row is five units.
21884 Optionally, HORIZONTAL-STEP, a positive integer,
21885 specifies how much an X axis label increments for
21887 (let* ((symbol-width (length graph-blank))
21888 ;; @code{height} @r{is both the largest number}
21889 ;; @r{and the number with the most digits.}
21890 (height (apply 'max numbers-list))
21893 (height-of-top-line
21894 (if (zerop (% height Y-axis-label-spacing))
21897 (* (1+ (/ height Y-axis-label-spacing))
21898 Y-axis-label-spacing)))
21901 (vertical-step (or vertical-step 1))
21902 (full-Y-label-width
21906 (* height-of-top-line vertical-step))
21912 height-of-top-line full-Y-label-width vertical-step)
21914 numbers-list height-of-top-line symbol-width)
21915 (print-X-axis numbers-list horizontal-step)))
21922 @node Final printed graph, , Another Bug, Print Whole Graph
21923 @appendixsubsec The Printed Graph
21925 When made and installed, you can call the @code{print-graph} command
21931 (print-graph fiftieth-list-for-graph 50 10)
21961 50 - ***************** * *
21963 10 50 100 150 200 250 300 350
21970 The largest group of functions contain 10 -- 19 words and symbols each.
21972 @node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top
21973 @appendix Free Software and Free Manuals
21975 @strong{by Richard M. Stallman}
21978 The biggest deficiency in free operating systems is not in the
21979 software---it is the lack of good free manuals that we can include in
21980 these systems. Many of our most important programs do not come with
21981 full manuals. Documentation is an essential part of any software
21982 package; when an important free software package does not come with a
21983 free manual, that is a major gap. We have many such gaps today.
21985 Once upon a time, many years ago, I thought I would learn Perl. I got
21986 a copy of a free manual, but I found it hard to read. When I asked
21987 Perl users about alternatives, they told me that there were better
21988 introductory manuals---but those were not free.
21990 Why was this? The authors of the good manuals had written them for
21991 O'Reilly Associates, which published them with restrictive terms---no
21992 copying, no modification, source files not available---which exclude
21993 them from the free software community.
21995 That wasn't the first time this sort of thing has happened, and (to
21996 our community's great loss) it was far from the last. Proprietary
21997 manual publishers have enticed a great many authors to restrict their
21998 manuals since then. Many times I have heard a GNU user eagerly tell me
21999 about a manual that he is writing, with which he expects to help the
22000 GNU project---and then had my hopes dashed, as he proceeded to explain
22001 that he had signed a contract with a publisher that would restrict it
22002 so that we cannot use it.
22004 Given that writing good English is a rare skill among programmers, we
22005 can ill afford to lose manuals this way.
22008 (The Free Software Foundation
22009 @uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, ,
22010 sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html,
22011 GNU manuals}, too.)
22013 Free documentation, like free software, is a matter of freedom, not
22014 price. The problem with these manuals was not that O'Reilly Associates
22015 charged a price for printed copies---that in itself is fine. (The Free
22016 Software Foundation sells printed copies of free GNU manuals, too.)
22017 But GNU manuals are available in source code form, while these manuals
22018 are available only on paper. GNU manuals come with permission to copy
22019 and modify; the Perl manuals do not. These restrictions are the
22022 The criterion for a free manual is pretty much the same as for free
22023 software: it is a matter of giving all users certain
22024 freedoms. Redistribution (including commercial redistribution) must be
22025 permitted, so that the manual can accompany every copy of the program,
22026 on-line or on paper. Permission for modification is crucial too.
22028 As a general rule, I don't believe that it is essential for people to
22029 have permission to modify all sorts of articles and books. The issues
22030 for writings are not necessarily the same as those for software. For
22031 example, I don't think you or I are obliged to give permission to
22032 modify articles like this one, which describe our actions and our
22035 But there is a particular reason why the freedom to modify is crucial
22036 for documentation for free software. When people exercise their right
22037 to modify the software, and add or change its features, if they are
22038 conscientious they will change the manual too---so they can provide
22039 accurate and usable documentation with the modified program. A manual
22040 which forbids programmers to be conscientious and finish the job, or
22041 more precisely requires them to write a new manual from scratch if
22042 they change the program, does not fill our community's needs.
22044 While a blanket prohibition on modification is unacceptable, some
22045 kinds of limits on the method of modification pose no problem. For
22046 example, requirements to preserve the original author's copyright
22047 notice, the distribution terms, or the list of authors, are ok. It is
22048 also no problem to require modified versions to include notice that
22049 they were modified, even to have entire sections that may not be
22050 deleted or changed, as long as these sections deal with nontechnical
22051 topics. (Some GNU manuals have them.)
22053 These kinds of restrictions are not a problem because, as a practical
22054 matter, they don't stop the conscientious programmer from adapting the
22055 manual to fit the modified program. In other words, they don't block
22056 the free software community from making full use of the manual.
22058 However, it must be possible to modify all the technical content of
22059 the manual, and then distribute the result in all the usual media,
22060 through all the usual channels; otherwise, the restrictions do block
22061 the community, the manual is not free, and so we need another manual.
22063 Unfortunately, it is often hard to find someone to write another
22064 manual when a proprietary manual exists. The obstacle is that many
22065 users think that a proprietary manual is good enough---so they don't
22066 see the need to write a free manual. They do not see that the free
22067 operating system has a gap that needs filling.
22069 Why do users think that proprietary manuals are good enough? Some have
22070 not considered the issue. I hope this article will do something to
22073 Other users consider proprietary manuals acceptable for the same
22074 reason so many people consider proprietary software acceptable: they
22075 judge in purely practical terms, not using freedom as a
22076 criterion. These people are entitled to their opinions, but since
22077 those opinions spring from values which do not include freedom, they
22078 are no guide for those of us who do value freedom.
22080 Please spread the word about this issue. We continue to lose manuals
22081 to proprietary publishing. If we spread the word that proprietary
22082 manuals are not sufficient, perhaps the next person who wants to help
22083 GNU by writing documentation will realize, before it is too late, that
22084 he must above all make it free.
22086 We can also encourage commercial publishers to sell free, copylefted
22087 manuals instead of proprietary ones. One way you can help this is to
22088 check the distribution terms of a manual before you buy it, and prefer
22089 copylefted manuals to non-copylefted ones.
22093 Note: The Free Software Foundation maintains a page on its Web site
22094 that lists free books available from other publishers:@*
22095 @uref{http://www.gnu.org/doc/other-free-books.html}
22097 @node GNU Free Documentation License, Index, Free Software and Free Manuals, Top
22098 @appendix GNU Free Documentation License
22100 @cindex FDL, GNU Free Documentation License
22101 @center Version 1.2, November 2002
22104 Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
22105 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
22107 Everyone is permitted to copy and distribute verbatim copies
22108 of this license document, but changing it is not allowed.
22115 The purpose of this License is to make a manual, textbook, or other
22116 functional and useful document @dfn{free} in the sense of freedom: to
22117 assure everyone the effective freedom to copy and redistribute it,
22118 with or without modifying it, either commercially or noncommercially.
22119 Secondarily, this License preserves for the author and publisher a way
22120 to get credit for their work, while not being considered responsible
22121 for modifications made by others.
22123 This License is a kind of ``copyleft'', which means that derivative
22124 works of the document must themselves be free in the same sense. It
22125 complements the GNU General Public License, which is a copyleft
22126 license designed for free software.
22128 We have designed this License in order to use it for manuals for free
22129 software, because free software needs free documentation: a free
22130 program should come with manuals providing the same freedoms that the
22131 software does. But this License is not limited to software manuals;
22132 it can be used for any textual work, regardless of subject matter or
22133 whether it is published as a printed book. We recommend this License
22134 principally for works whose purpose is instruction or reference.
22137 APPLICABILITY AND DEFINITIONS
22139 This License applies to any manual or other work, in any medium, that
22140 contains a notice placed by the copyright holder saying it can be
22141 distributed under the terms of this License. Such a notice grants a
22142 world-wide, royalty-free license, unlimited in duration, to use that
22143 work under the conditions stated herein. The ``Document'', below,
22144 refers to any such manual or work. Any member of the public is a
22145 licensee, and is addressed as ``you''. You accept the license if you
22146 copy, modify or distribute the work in a way requiring permission
22147 under copyright law.
22149 A ``Modified Version'' of the Document means any work containing the
22150 Document or a portion of it, either copied verbatim, or with
22151 modifications and/or translated into another language.
22153 A ``Secondary Section'' is a named appendix or a front-matter section
22154 of the Document that deals exclusively with the relationship of the
22155 publishers or authors of the Document to the Document's overall
22156 subject (or to related matters) and contains nothing that could fall
22157 directly within that overall subject. (Thus, if the Document is in
22158 part a textbook of mathematics, a Secondary Section may not explain
22159 any mathematics.) The relationship could be a matter of historical
22160 connection with the subject or with related matters, or of legal,
22161 commercial, philosophical, ethical or political position regarding
22164 The ``Invariant Sections'' are certain Secondary Sections whose titles
22165 are designated, as being those of Invariant Sections, in the notice
22166 that says that the Document is released under this License. If a
22167 section does not fit the above definition of Secondary then it is not
22168 allowed to be designated as Invariant. The Document may contain zero
22169 Invariant Sections. If the Document does not identify any Invariant
22170 Sections then there are none.
22172 The ``Cover Texts'' are certain short passages of text that are listed,
22173 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
22174 the Document is released under this License. A Front-Cover Text may
22175 be at most 5 words, and a Back-Cover Text may be at most 25 words.
22177 A ``Transparent'' copy of the Document means a machine-readable copy,
22178 represented in a format whose specification is available to the
22179 general public, that is suitable for revising the document
22180 straightforwardly with generic text editors or (for images composed of
22181 pixels) generic paint programs or (for drawings) some widely available
22182 drawing editor, and that is suitable for input to text formatters or
22183 for automatic translation to a variety of formats suitable for input
22184 to text formatters. A copy made in an otherwise Transparent file
22185 format whose markup, or absence of markup, has been arranged to thwart
22186 or discourage subsequent modification by readers is not Transparent.
22187 An image format is not Transparent if used for any substantial amount
22188 of text. A copy that is not ``Transparent'' is called ``Opaque''.
22190 Examples of suitable formats for Transparent copies include plain
22191 @sc{ascii} without markup, Texinfo input format, La@TeX{} input
22192 format, @acronym{SGML} or @acronym{XML} using a publicly available
22193 @acronym{DTD}, and standard-conforming simple @acronym{HTML},
22194 PostScript or @acronym{PDF} designed for human modification. Examples
22195 of transparent image formats include @acronym{PNG}, @acronym{XCF} and
22196 @acronym{JPG}. Opaque formats include proprietary formats that can be
22197 read and edited only by proprietary word processors, @acronym{SGML} or
22198 @acronym{XML} for which the @acronym{DTD} and/or processing tools are
22199 not generally available, and the machine-generated @acronym{HTML},
22200 PostScript or @acronym{PDF} produced by some word processors for
22201 output purposes only.
22203 The ``Title Page'' means, for a printed book, the title page itself,
22204 plus such following pages as are needed to hold, legibly, the material
22205 this License requires to appear in the title page. For works in
22206 formats which do not have any title page as such, ``Title Page'' means
22207 the text near the most prominent appearance of the work's title,
22208 preceding the beginning of the body of the text.
22210 A section ``Entitled XYZ'' means a named subunit of the Document whose
22211 title either is precisely XYZ or contains XYZ in parentheses following
22212 text that translates XYZ in another language. (Here XYZ stands for a
22213 specific section name mentioned below, such as ``Acknowledgements'',
22214 ``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
22215 of such a section when you modify the Document means that it remains a
22216 section ``Entitled XYZ'' according to this definition.
22218 The Document may include Warranty Disclaimers next to the notice which
22219 states that this License applies to the Document. These Warranty
22220 Disclaimers are considered to be included by reference in this
22221 License, but only as regards disclaiming warranties: any other
22222 implication that these Warranty Disclaimers may have is void and has
22223 no effect on the meaning of this License.
22228 You may copy and distribute the Document in any medium, either
22229 commercially or noncommercially, provided that this License, the
22230 copyright notices, and the license notice saying this License applies
22231 to the Document are reproduced in all copies, and that you add no other
22232 conditions whatsoever to those of this License. You may not use
22233 technical measures to obstruct or control the reading or further
22234 copying of the copies you make or distribute. However, you may accept
22235 compensation in exchange for copies. If you distribute a large enough
22236 number of copies you must also follow the conditions in section 3.
22238 You may also lend copies, under the same conditions stated above, and
22239 you may publicly display copies.
22242 COPYING IN QUANTITY
22244 If you publish printed copies (or copies in media that commonly have
22245 printed covers) of the Document, numbering more than 100, and the
22246 Document's license notice requires Cover Texts, you must enclose the
22247 copies in covers that carry, clearly and legibly, all these Cover
22248 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
22249 the back cover. Both covers must also clearly and legibly identify
22250 you as the publisher of these copies. The front cover must present
22251 the full title with all words of the title equally prominent and
22252 visible. You may add other material on the covers in addition.
22253 Copying with changes limited to the covers, as long as they preserve
22254 the title of the Document and satisfy these conditions, can be treated
22255 as verbatim copying in other respects.
22257 If the required texts for either cover are too voluminous to fit
22258 legibly, you should put the first ones listed (as many as fit
22259 reasonably) on the actual cover, and continue the rest onto adjacent
22262 If you publish or distribute Opaque copies of the Document numbering
22263 more than 100, you must either include a machine-readable Transparent
22264 copy along with each Opaque copy, or state in or with each Opaque copy
22265 a computer-network location from which the general network-using
22266 public has access to download using public-standard network protocols
22267 a complete Transparent copy of the Document, free of added material.
22268 If you use the latter option, you must take reasonably prudent steps,
22269 when you begin distribution of Opaque copies in quantity, to ensure
22270 that this Transparent copy will remain thus accessible at the stated
22271 location until at least one year after the last time you distribute an
22272 Opaque copy (directly or through your agents or retailers) of that
22273 edition to the public.
22275 It is requested, but not required, that you contact the authors of the
22276 Document well before redistributing any large number of copies, to give
22277 them a chance to provide you with an updated version of the Document.
22282 You may copy and distribute a Modified Version of the Document under
22283 the conditions of sections 2 and 3 above, provided that you release
22284 the Modified Version under precisely this License, with the Modified
22285 Version filling the role of the Document, thus licensing distribution
22286 and modification of the Modified Version to whoever possesses a copy
22287 of it. In addition, you must do these things in the Modified Version:
22291 Use in the Title Page (and on the covers, if any) a title distinct
22292 from that of the Document, and from those of previous versions
22293 (which should, if there were any, be listed in the History section
22294 of the Document). You may use the same title as a previous version
22295 if the original publisher of that version gives permission.
22298 List on the Title Page, as authors, one or more persons or entities
22299 responsible for authorship of the modifications in the Modified
22300 Version, together with at least five of the principal authors of the
22301 Document (all of its principal authors, if it has fewer than five),
22302 unless they release you from this requirement.
22305 State on the Title page the name of the publisher of the
22306 Modified Version, as the publisher.
22309 Preserve all the copyright notices of the Document.
22312 Add an appropriate copyright notice for your modifications
22313 adjacent to the other copyright notices.
22316 Include, immediately after the copyright notices, a license notice
22317 giving the public permission to use the Modified Version under the
22318 terms of this License, in the form shown in the Addendum below.
22321 Preserve in that license notice the full lists of Invariant Sections
22322 and required Cover Texts given in the Document's license notice.
22325 Include an unaltered copy of this License.
22328 Preserve the section Entitled ``History'', Preserve its Title, and add
22329 to it an item stating at least the title, year, new authors, and
22330 publisher of the Modified Version as given on the Title Page. If
22331 there is no section Entitled ``History'' in the Document, create one
22332 stating the title, year, authors, and publisher of the Document as
22333 given on its Title Page, then add an item describing the Modified
22334 Version as stated in the previous sentence.
22337 Preserve the network location, if any, given in the Document for
22338 public access to a Transparent copy of the Document, and likewise
22339 the network locations given in the Document for previous versions
22340 it was based on. These may be placed in the ``History'' section.
22341 You may omit a network location for a work that was published at
22342 least four years before the Document itself, or if the original
22343 publisher of the version it refers to gives permission.
22346 For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
22347 the Title of the section, and preserve in the section all the
22348 substance and tone of each of the contributor acknowledgements and/or
22349 dedications given therein.
22352 Preserve all the Invariant Sections of the Document,
22353 unaltered in their text and in their titles. Section numbers
22354 or the equivalent are not considered part of the section titles.
22357 Delete any section Entitled ``Endorsements''. Such a section
22358 may not be included in the Modified Version.
22361 Do not retitle any existing section to be Entitled ``Endorsements'' or
22362 to conflict in title with any Invariant Section.
22365 Preserve any Warranty Disclaimers.
22368 If the Modified Version includes new front-matter sections or
22369 appendices that qualify as Secondary Sections and contain no material
22370 copied from the Document, you may at your option designate some or all
22371 of these sections as invariant. To do this, add their titles to the
22372 list of Invariant Sections in the Modified Version's license notice.
22373 These titles must be distinct from any other section titles.
22375 You may add a section Entitled ``Endorsements'', provided it contains
22376 nothing but endorsements of your Modified Version by various
22377 parties---for example, statements of peer review or that the text has
22378 been approved by an organization as the authoritative definition of a
22381 You may add a passage of up to five words as a Front-Cover Text, and a
22382 passage of up to 25 words as a Back-Cover Text, to the end of the list
22383 of Cover Texts in the Modified Version. Only one passage of
22384 Front-Cover Text and one of Back-Cover Text may be added by (or
22385 through arrangements made by) any one entity. If the Document already
22386 includes a cover text for the same cover, previously added by you or
22387 by arrangement made by the same entity you are acting on behalf of,
22388 you may not add another; but you may replace the old one, on explicit
22389 permission from the previous publisher that added the old one.
22391 The author(s) and publisher(s) of the Document do not by this License
22392 give permission to use their names for publicity for or to assert or
22393 imply endorsement of any Modified Version.
22396 COMBINING DOCUMENTS
22398 You may combine the Document with other documents released under this
22399 License, under the terms defined in section 4 above for modified
22400 versions, provided that you include in the combination all of the
22401 Invariant Sections of all of the original documents, unmodified, and
22402 list them all as Invariant Sections of your combined work in its
22403 license notice, and that you preserve all their Warranty Disclaimers.
22405 The combined work need only contain one copy of this License, and
22406 multiple identical Invariant Sections may be replaced with a single
22407 copy. If there are multiple Invariant Sections with the same name but
22408 different contents, make the title of each such section unique by
22409 adding at the end of it, in parentheses, the name of the original
22410 author or publisher of that section if known, or else a unique number.
22411 Make the same adjustment to the section titles in the list of
22412 Invariant Sections in the license notice of the combined work.
22414 In the combination, you must combine any sections Entitled ``History''
22415 in the various original documents, forming one section Entitled
22416 ``History''; likewise combine any sections Entitled ``Acknowledgements'',
22417 and any sections Entitled ``Dedications''. You must delete all
22418 sections Entitled ``Endorsements.''
22421 COLLECTIONS OF DOCUMENTS
22423 You may make a collection consisting of the Document and other documents
22424 released under this License, and replace the individual copies of this
22425 License in the various documents with a single copy that is included in
22426 the collection, provided that you follow the rules of this License for
22427 verbatim copying of each of the documents in all other respects.
22429 You may extract a single document from such a collection, and distribute
22430 it individually under this License, provided you insert a copy of this
22431 License into the extracted document, and follow this License in all
22432 other respects regarding verbatim copying of that document.
22435 AGGREGATION WITH INDEPENDENT WORKS
22437 A compilation of the Document or its derivatives with other separate
22438 and independent documents or works, in or on a volume of a storage or
22439 distribution medium, is called an ``aggregate'' if the copyright
22440 resulting from the compilation is not used to limit the legal rights
22441 of the compilation's users beyond what the individual works permit.
22442 When the Document is included in an aggregate, this License does not
22443 apply to the other works in the aggregate which are not themselves
22444 derivative works of the Document.
22446 If the Cover Text requirement of section 3 is applicable to these
22447 copies of the Document, then if the Document is less than one half of
22448 the entire aggregate, the Document's Cover Texts may be placed on
22449 covers that bracket the Document within the aggregate, or the
22450 electronic equivalent of covers if the Document is in electronic form.
22451 Otherwise they must appear on printed covers that bracket the whole
22457 Translation is considered a kind of modification, so you may
22458 distribute translations of the Document under the terms of section 4.
22459 Replacing Invariant Sections with translations requires special
22460 permission from their copyright holders, but you may include
22461 translations of some or all Invariant Sections in addition to the
22462 original versions of these Invariant Sections. You may include a
22463 translation of this License, and all the license notices in the
22464 Document, and any Warranty Disclaimers, provided that you also include
22465 the original English version of this License and the original versions
22466 of those notices and disclaimers. In case of a disagreement between
22467 the translation and the original version of this License or a notice
22468 or disclaimer, the original version will prevail.
22470 If a section in the Document is Entitled ``Acknowledgements'',
22471 ``Dedications'', or ``History'', the requirement (section 4) to Preserve
22472 its Title (section 1) will typically require changing the actual
22478 You may not copy, modify, sublicense, or distribute the Document except
22479 as expressly provided for under this License. Any other attempt to
22480 copy, modify, sublicense or distribute the Document is void, and will
22481 automatically terminate your rights under this License. However,
22482 parties who have received copies, or rights, from you under this
22483 License will not have their licenses terminated so long as such
22484 parties remain in full compliance.
22487 FUTURE REVISIONS OF THIS LICENSE
22489 The Free Software Foundation may publish new, revised versions
22490 of the GNU Free Documentation License from time to time. Such new
22491 versions will be similar in spirit to the present version, but may
22492 differ in detail to address new problems or concerns. See
22493 @uref{http://www.gnu.org/copyleft/}.
22495 Each version of the License is given a distinguishing version number.
22496 If the Document specifies that a particular numbered version of this
22497 License ``or any later version'' applies to it, you have the option of
22498 following the terms and conditions either of that specified version or
22499 of any later version that has been published (not as a draft) by the
22500 Free Software Foundation. If the Document does not specify a version
22501 number of this License, you may choose any version ever published (not
22502 as a draft) by the Free Software Foundation.
22506 @appendixsubsec ADDENDUM: How to use this License for your documents
22508 To use this License in a document you have written, include a copy of
22509 the License in the document and put the following copyright and
22510 license notices just after the title page:
22514 Copyright (C) @var{year} @var{your name}.
22515 Permission is granted to copy, distribute and/or modify this document
22516 under the terms of the GNU Free Documentation License, Version 1.2
22517 or any later version published by the Free Software Foundation;
22518 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
22519 A copy of the license is included in the section entitled ``GNU
22520 Free Documentation License''.
22524 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
22525 replace the ``with...Texts.'' line with this:
22529 with the Invariant Sections being @var{list their titles}, with
22530 the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
22535 If you have Invariant Sections without Cover Texts, or some other
22536 combination of the three, merge those two alternatives to suit the
22539 If your document contains nontrivial examples of program code, we
22540 recommend releasing these examples in parallel under your choice of
22541 free software license, such as the GNU General Public License,
22542 to permit their use in free software.
22544 @node Index, About the Author, GNU Free Documentation License, Top
22545 @comment node-name, next, previous, up
22549 MENU ENTRY: NODE NAME.
22555 @c Place biographical information on right-hand (verso) page
22559 \par\vfill\supereject
22560 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
22561 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
22564 \par\vfill\supereject
22565 \par\vfill\supereject
22566 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
22567 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
22576 @c ================ Biographical information ================
22580 @center About the Author
22585 @node About the Author, , Index, Top
22586 @unnumbered About the Author
22590 Robert J. Chassell has worked with GNU Emacs since 1985. He writes
22591 and edits, teaches Emacs and Emacs Lisp, and speaks throughout the
22592 world on software freedom. Chassell was a founding Director and
22593 Treasurer of the Free Software Foundation, Inc. He is co-author of
22594 the @cite{Texinfo} manual, and has edited more than a dozen other
22595 books. He graduated from Cambridge University, in England. He has an
22596 abiding interest in social and economic history and flies his own
22603 @c Prevent page number on blank verso, so eject it first.
22605 \par\vfill\supereject
22610 @evenheading @thispage @| @| @thistitle
22611 @oddheading @| @| @thispage
22617 arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf