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.06
28 @set update-date 6 November 2006
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 "../info/eintr"))
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 \if \xrefprintnodename
187 \global\def\xrefprintnodename#1{\unskip, ``#1''}
189 \global\def\xrefprintnodename#1{ ``#1''}
191 % \global\def\xrefprintnodename#1{, ``#1''}
194 @c ----------------------------------------------------
198 * Emacs Lisp Intro: (eintr).
199 A simple introduction to Emacs Lisp programming.
203 This is an @cite{Introduction to Programming in Emacs Lisp}, for
204 people who are not programmers.
206 Edition @value{edition-number}, @value{update-date}
208 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001,
209 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
215 GNU Press, @hfill @uref{http://www.gnupress.org}@*
216 a division of the @hfill General: @email{press@@gnu.org}@*
217 Free Software Foundation, Inc. @hfill Orders:@w{ } @email{sales@@gnu.org}@*
218 51 Franklin Street, Fifth Floor @hfill Tel: +1 (617) 542-5942@*
219 Boston, MA 02110-1301 USA @hfill Fax: +1 (617) 542-2652@*
226 GNU Press, Website: http://www.gnupress.org
227 a division of the General: press@@gnu.org
228 Free Software Foundation, Inc. Orders: sales@@gnu.org
229 51 Franklin Street, Fifth Floor Tel: +1 (617) 542-5942
230 Boston, MA 02110-1301 USA Fax: +1 (617) 542-2652
235 @c Printed copies are available for $30 each.@*
238 Permission is granted to copy, distribute and/or modify this document
239 under the terms of the GNU Free Documentation License, Version 1.2 or
240 any later version published by the Free Software Foundation; there
241 being no Invariant Section, with the Front-Cover Texts being ``A GNU
242 Manual'', and with the Back-Cover Texts as in (a) below. A copy of
243 the license is included in the section entitled ``GNU Free
244 Documentation License''.
246 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
247 modify this GNU Manual, like GNU software. Copies published by the
248 Free Software Foundation raise funds for GNU development.''
251 @c half title; two lines here, so do not use `shorttitlepage'
254 \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}%
256 {\begingroup\hbox{}\vskip 0.25in \chaprm%
257 \centerline{Programming in Emacs Lisp}%
258 \endgroup\page\hbox{}\page}
263 @center @titlefont{An Introduction to}
265 @center @titlefont{Programming in Emacs Lisp}
267 @center Revised Third Edition
269 @center by Robert J. Chassell
272 @vskip 0pt plus 1filll
278 @evenheading @thispage @| @| @thischapter
279 @oddheading @thissection @| @| @thispage
283 @c Keep T.O.C. short by tightening up for largebook
286 \global\parskip 2pt plus 1pt
287 \global\advance\baselineskip by -1pt
296 @node Top, Preface, (dir), (dir)
297 @top An Introduction to Programming in Emacs Lisp
301 This master menu first lists each chapter and index; then it lists
302 every node in every chapter.
305 @c >>>> Set pageno appropriately <<<<
307 @c The first page of the Preface is a roman numeral; it is the first
308 @c right handed page after the Table of Contents; hence the following
309 @c setting must be for an odd negative number.
316 * Preface:: What to look for.
317 * List Processing:: What is Lisp?
318 * Practicing Evaluation:: Running several programs.
319 * Writing Defuns:: How to write function definitions.
320 * Buffer Walk Through:: Exploring a few buffer-related functions.
321 * More Complex:: A few, even more complex functions.
322 * Narrowing & Widening:: Restricting your and Emacs attention to
324 * car cdr & cons:: Fundamental functions in Lisp.
325 * Cutting & Storing Text:: Removing text and saving it.
326 * List Implementation:: How lists are implemented in the computer.
327 * Yanking:: Pasting stored text.
328 * Loops & Recursion:: How to repeat a process.
329 * Regexp Search:: Regular expression searches.
330 * Counting Words:: A review of repetition and regexps.
331 * Words in a defun:: Counting words in a @code{defun}.
332 * Readying a Graph:: A prototype graph printing function.
333 * Emacs Initialization:: How to write a @file{.emacs} file.
334 * Debugging:: How to run the Emacs Lisp debuggers.
335 * Conclusion:: Now you have the basics.
336 * the-the:: An appendix: how to find reduplicated words.
337 * Kill Ring:: An appendix: how the kill ring works.
338 * Full Graph:: How to create a graph with labelled axes.
339 * Free Software and Free Manuals::
340 * GNU Free Documentation License::
345 --- The Detailed Node Listing ---
349 * Why:: Why learn Emacs Lisp?
350 * On Reading this Text:: Read, gain familiarity, pick up habits....
351 * Who You Are:: For whom this is written.
353 * Note for Novices:: You can read this as a novice.
358 * Lisp Lists:: What are lists?
359 * Run a Program:: Any list in Lisp is a program ready to run.
360 * Making Errors:: Generating an error message.
361 * Names & Definitions:: Names of symbols and function definitions.
362 * Lisp Interpreter:: What the Lisp interpreter does.
363 * Evaluation:: Running a program.
364 * Variables:: Returning a value from a variable.
365 * Arguments:: Passing information to a function.
366 * set & setq:: Setting the value of a variable.
367 * Summary:: The major points.
368 * Error Message Exercises::
372 * Numbers Lists:: List have numbers, other lists, in them.
373 * Lisp Atoms:: Elemental entities.
374 * Whitespace in Lists:: Formatting lists to be readable.
375 * Typing Lists:: How GNU Emacs helps you type lists.
379 * Complications:: Variables, Special forms, Lists within.
380 * Byte Compiling:: Specially processing code for speed.
384 * Evaluating Inner Lists:: Lists within lists...
388 * fill-column Example::
389 * Void Function:: The error message for a symbol
391 * Void Variable:: The error message for a symbol without a value.
395 * Data types:: Types of data passed to a function.
396 * Args as Variable or List:: An argument can be the value
397 of a variable or list.
398 * Variable Number of Arguments:: Some functions may take a
399 variable number of arguments.
400 * Wrong Type of Argument:: Passing an argument of the wrong type
402 * message:: A useful function for sending messages.
404 Setting the Value of a Variable
406 * Using set:: Setting values.
407 * Using setq:: Setting a quoted value.
408 * Counting:: Using @code{setq} to count.
410 Practicing Evaluation
412 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
414 * Buffer Names:: Buffers and files are different.
415 * Getting Buffers:: Getting a buffer itself, not merely its name.
416 * Switching Buffers:: How to change to another buffer.
417 * Buffer Size & Locations:: Where point is located and the size of
419 * Evaluation Exercise::
421 How To Write Function Definitions
423 * Primitive Functions::
424 * defun:: The @code{defun} special form.
425 * Install:: Install a function definition.
426 * Interactive:: Making a function interactive.
427 * Interactive Options:: Different options for @code{interactive}.
428 * Permanent Installation:: Installing code permanently.
429 * let:: Creating and initializing local variables.
431 * else:: If--then--else expressions.
432 * Truth & Falsehood:: What Lisp considers false and true.
433 * save-excursion:: Keeping track of point, mark, and buffer.
437 Install a Function Definition
439 * Effect of installation::
440 * Change a defun:: How to change a function definition.
442 Make a Function Interactive
444 * Interactive multiply-by-seven:: An overview.
445 * multiply-by-seven in detail:: The interactive version.
449 * Prevent confusion::
450 * Parts of let Expression::
451 * Sample let Expression::
452 * Uninitialized let Variables::
454 The @code{if} Special Form
456 * if in more detail::
457 * type-of-animal in detail:: An example of an @code{if} expression.
459 Truth and Falsehood in Emacs Lisp
461 * nil explained:: @code{nil} has two meanings.
463 @code{save-excursion}
465 * Point and mark:: A review of various locations.
466 * Template for save-excursion::
468 A Few Buffer--Related Functions
470 * Finding More:: How to find more information.
471 * simplified-beginning-of-buffer:: Shows @code{goto-char},
472 @code{point-min}, and @code{push-mark}.
473 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
474 * append-to-buffer:: Uses @code{save-excursion} and
475 @code{insert-buffer-substring}.
476 * Buffer Related Review:: Review.
479 The Definition of @code{mark-whole-buffer}
481 * mark-whole-buffer overview::
482 * Body of mark-whole-buffer:: Only three lines of code.
484 The Definition of @code{append-to-buffer}
486 * append-to-buffer overview::
487 * append interactive:: A two part interactive expression.
488 * append-to-buffer body:: Incorporates a @code{let} expression.
489 * append save-excursion:: How the @code{save-excursion} works.
491 A Few More Complex Functions
493 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
494 * insert-buffer:: Read-only, and with @code{or}.
495 * beginning-of-buffer:: Shows @code{goto-char},
496 @code{point-min}, and @code{push-mark}.
497 * Second Buffer Related Review::
498 * optional Exercise::
500 The Definition of @code{insert-buffer}
502 * insert-buffer code::
503 * insert-buffer interactive:: When you can read, but not write.
504 * insert-buffer body:: The body has an @code{or} and a @code{let}.
505 * if & or:: Using an @code{if} instead of an @code{or}.
506 * Insert or:: How the @code{or} expression works.
507 * Insert let:: Two @code{save-excursion} expressions.
508 * New insert-buffer::
510 The Interactive Expression in @code{insert-buffer}
512 * Read-only buffer:: When a buffer cannot be modified.
513 * b for interactive:: An existing buffer or else its name.
515 Complete Definition of @code{beginning-of-buffer}
517 * Optional Arguments::
518 * beginning-of-buffer opt arg:: Example with optional argument.
519 * beginning-of-buffer complete::
521 @code{beginning-of-buffer} with an Argument
523 * Disentangle beginning-of-buffer::
524 * Large buffer case::
525 * Small buffer case::
527 Narrowing and Widening
529 * Narrowing advantages:: The advantages of narrowing
530 * save-restriction:: The @code{save-restriction} special form.
531 * what-line:: The number of the line that point is on.
534 @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
536 * Strange Names:: An historical aside: why the strange names?
537 * car & cdr:: Functions for extracting part of a list.
538 * cons:: Constructing a list.
539 * nthcdr:: Calling @code{cdr} repeatedly.
541 * setcar:: Changing the first element of a list.
542 * setcdr:: Changing the rest of a list.
548 * length:: How to find the length of a list.
550 Cutting and Storing Text
552 * Storing Text:: Text is stored in a list.
553 * zap-to-char:: Cutting out text up to a character.
554 * kill-region:: Cutting text out of a region.
555 * copy-region-as-kill:: A definition for copying text.
556 * Digression into C:: Minor note on C programming language macros.
557 * defvar:: How to give a variable an initial value.
558 * cons & search-fwd Review::
563 * Complete zap-to-char:: The complete implementation.
564 * zap-to-char interactive:: A three part interactive expression.
565 * zap-to-char body:: A short overview.
566 * search-forward:: How to search for a string.
567 * progn:: The @code{progn} special form.
568 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
572 * Complete kill-region:: The function definition.
573 * condition-case:: Dealing with a problem.
576 @code{copy-region-as-kill}
578 * Complete copy-region-as-kill:: The complete function definition.
579 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
581 The Body of @code{copy-region-as-kill}
583 * last-command & this-command::
584 * kill-append function::
585 * kill-new function::
587 Initializing a Variable with @code{defvar}
589 * See variable current value::
590 * defvar and asterisk::
592 How Lists are Implemented
595 * Symbols as Chest:: Exploring a powerful metaphor.
600 * Kill Ring Overview::
601 * kill-ring-yank-pointer:: The kill ring is a list.
602 * yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
606 * while:: Causing a stretch of code to repeat.
608 * Recursion:: Causing a function to call itself.
613 * Looping with while:: Repeat so long as test returns true.
614 * Loop Example:: A @code{while} loop that uses a list.
615 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
616 * Incrementing Loop:: A loop with an incrementing counter.
617 * Decrementing Loop:: A loop with a decrementing counter.
619 A Loop with an Incrementing Counter
621 * Incrementing Example:: Counting pebbles in a triangle.
622 * Inc Example parts:: The parts of the function definition.
623 * Inc Example altogether:: Putting the function definition together.
625 Loop with a Decrementing Counter
627 * Decrementing Example:: More pebbles on the beach.
628 * Dec Example parts:: The parts of the function definition.
629 * Dec Example altogether:: Putting the function definition together.
631 Save your time: @code{dolist} and @code{dotimes}
638 * Building Robots:: Same model, different serial number ...
639 * Recursive Definition Parts:: Walk until you stop ...
640 * Recursion with list:: Using a list as the test whether to recurse.
641 * Recursive triangle function::
642 * Recursion with cond::
643 * Recursive Patterns:: Often used templates.
644 * No Deferment:: Don't store up work ...
645 * No deferment solution::
647 Recursion in Place of a Counter
649 * Recursive Example arg of 1 or 2::
650 * Recursive Example arg of 3 or 4::
658 Regular Expression Searches
660 * sentence-end:: The regular expression for @code{sentence-end}.
661 * re-search-forward:: Very similar to @code{search-forward}.
662 * forward-sentence:: A straightforward example of regexp search.
663 * forward-paragraph:: A somewhat complex example.
664 * etags:: How to create your own @file{TAGS} table.
666 * re-search Exercises::
668 @code{forward-sentence}
670 * Complete forward-sentence::
671 * fwd-sentence while loops:: Two @code{while} loops.
672 * fwd-sentence re-search:: A regular expression search.
674 @code{forward-paragraph}: a Goldmine of Functions
676 * forward-paragraph in brief:: Key parts of the function definition.
677 * fwd-para let:: The @code{let*} expression.
678 * fwd-para while:: The forward motion @code{while} loop.
680 Counting: Repetition and Regexps
683 * count-words-region:: Use a regexp, but find a problem.
684 * recursive-count-words:: Start with case of no words in region.
685 * Counting Exercise::
687 The @code{count-words-region} Function
689 * Design count-words-region:: The definition using a @code{while} loop.
690 * Whitespace Bug:: The Whitespace Bug in @code{count-words-region}.
692 Counting Words in a @code{defun}
694 * Divide and Conquer::
695 * Words and Symbols:: What to count?
696 * Syntax:: What constitutes a word or symbol?
697 * count-words-in-defun:: Very like @code{count-words}.
698 * Several defuns:: Counting several defuns in a file.
699 * Find a File:: Do you want to look at a file?
700 * lengths-list-file:: A list of the lengths of many definitions.
701 * Several files:: Counting in definitions in different files.
702 * Several files recursively:: Recursively counting in different files.
703 * Prepare the data:: Prepare the data for display in a graph.
705 Count Words in @code{defuns} in Different Files
707 * lengths-list-many-files:: Return a list of the lengths of defuns.
708 * append:: Attach one list to another.
710 Prepare the Data for Display in a Graph
712 * Sorting:: Sorting lists.
713 * Files List:: Making a list of files.
714 * Counting function definitions::
718 * Columns of a graph::
719 * graph-body-print:: How to print the body of a graph.
720 * recursive-graph-body-print::
722 * Line Graph Exercise::
724 Your @file{.emacs} File
726 * Default Configuration::
727 * Site-wide Init:: You can write site-wide init files.
728 * defcustom:: Emacs will write code for you.
729 * Beginning a .emacs File:: How to write a @code{.emacs file}.
730 * Text and Auto-fill:: Automatically wrap lines.
731 * Mail Aliases:: Use abbreviations for email addresses.
732 * Indent Tabs Mode:: Don't use tabs with @TeX{}
733 * Keybindings:: Create some personal keybindings.
734 * Keymaps:: More about key binding.
735 * Loading Files:: Load (i.e., evaluate) files automatically.
736 * Autoload:: Make functions available.
737 * Simple Extension:: Define a function; bind it to a key.
738 * X11 Colors:: Colors in X.
740 * Mode Line:: How to customize your mode line.
744 * debug:: How to use the built-in debugger.
745 * debug-on-entry:: Start debugging when you call a function.
746 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
747 * edebug:: How to use Edebug, a source level debugger.
748 * Debugging Exercises::
750 Handling the Kill Ring
753 * yank:: Paste a copy of a clipped element.
754 * yank-pop:: Insert element pointed to.
757 The @code{current-kill} Function
759 * Understanding current-kill::
761 @code{current-kill} in Outline
763 * Digression concerning error:: How to mislead humans, but not computers.
764 * Determining the Element::
766 A Graph with Labelled Axes
769 * print-graph Varlist:: @code{let} expression in @code{print-graph}.
770 * print-Y-axis:: Print a label for the vertical axis.
771 * print-X-axis:: Print a horizontal label.
772 * Print Whole Graph:: The function to print a complete graph.
774 The @code{print-Y-axis} Function
776 * Height of label:: What height for the Y axis?
777 * Compute a Remainder:: How to compute the remainder of a division.
778 * Y Axis Element:: Construct a line for the Y axis.
779 * Y-axis-column:: Generate a list of Y axis labels.
780 * print-Y-axis Penultimate:: A not quite final version.
782 The @code{print-X-axis} Function
784 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
785 * X Axis Tic Marks:: Create tic marks for the horizontal axis.
787 Printing the Whole Graph
789 * The final version:: A few changes.
790 * Test print-graph:: Run a short test.
791 * Graphing words in defuns:: Executing the final code.
792 * lambda:: How to write an anonymous function.
793 * mapcar:: Apply a function to elements of a list.
794 * Another Bug:: Yet another bug @dots{} most insidious.
795 * Final printed graph:: The graph itself!
800 @node Preface, List Processing, Top, Top
801 @comment node-name, next, previous, up
804 Most of the GNU Emacs integrated environment is written in the programming
805 language called Emacs Lisp. The code written in this programming
806 language is the software---the sets of instructions---that tell the
807 computer what to do when you give it commands. Emacs is designed so
808 that you can write new code in Emacs Lisp and easily install it as an
809 extension to the editor.
811 (GNU Emacs is sometimes called an ``extensible editor'', but it does
812 much more than provide editing capabilities. It is better to refer to
813 Emacs as an ``extensible computing environment''. However, that
814 phrase is quite a mouthful. It is easier to refer to Emacs simply as
815 an editor. Moreover, everything you do in Emacs---find the Mayan date
816 and phases of the moon, simplify polynomials, debug code, manage
817 files, read letters, write books---all these activities are kinds of
818 editing in the most general sense of the word.)
822 * On Reading this Text::
829 @node Why, On Reading this Text, Preface, Preface
831 @unnumberedsec Why Study Emacs Lisp?
834 Although Emacs Lisp is usually thought of in association only with Emacs,
835 it is a full computer programming language. You can use Emacs Lisp as
836 you would any other programming language.
838 Perhaps you want to understand programming; perhaps you want to extend
839 Emacs; or perhaps you want to become a programmer. This introduction to
840 Emacs Lisp is designed to get you started: to guide you in learning the
841 fundamentals of programming, and more importantly, to show you how you
842 can teach yourself to go further.
844 @node On Reading this Text, Who You Are, Why, Preface
845 @comment node-name, next, previous, up
846 @unnumberedsec On Reading this Text
848 All through this document, you will see little sample programs you can
849 run inside of Emacs. If you read this document in Info inside of GNU
850 Emacs, you can run the programs as they appear. (This is easy to do and
851 is explained when the examples are presented.) Alternatively, you can
852 read this introduction as a printed book while sitting beside a computer
853 running Emacs. (This is what I like to do; I like printed books.) If
854 you don't have a running Emacs beside you, you can still read this book,
855 but in this case, it is best to treat it as a novel or as a travel guide
856 to a country not yet visited: interesting, but not the same as being
859 Much of this introduction is dedicated to walk-throughs or guided tours
860 of code used in GNU Emacs. These tours are designed for two purposes:
861 first, to give you familiarity with real, working code (code you use
862 every day); and, second, to give you familiarity with the way Emacs
863 works. It is interesting to see how a working environment is
866 hope that you will pick up the habit of browsing through source code.
867 You can learn from it and mine it for ideas. Having GNU Emacs is like
868 having a dragon's cave of treasures.
870 In addition to learning about Emacs as an editor and Emacs Lisp as a
871 programming language, the examples and guided tours will give you an
872 opportunity to get acquainted with Emacs as a Lisp programming
873 environment. GNU Emacs supports programming and provides tools that
874 you will want to become comfortable using, such as @kbd{M-.} (the key
875 which invokes the @code{find-tag} command). You will also learn about
876 buffers and other objects that are part of the environment.
877 Learning about these features of Emacs is like learning new routes
878 around your home town.
881 In addition, I have written several programs as extended examples.
882 Although these are examples, the programs are real. I use them.
883 Other people use them. You may use them. Beyond the fragments of
884 programs used for illustrations, there is very little in here that is
885 `just for teaching purposes'; what you see is used. This is a great
886 advantage of Emacs Lisp: it is easy to learn to use it for work.
889 Finally, I hope to convey some of the skills for using Emacs to
890 learn aspects of programming that you don't know. You can often use
891 Emacs to help you understand what puzzles you or to find out how to do
892 something new. This self-reliance is not only a pleasure, but an
895 @node Who You Are, Lisp History, On Reading this Text, Preface
896 @comment node-name, next, previous, up
897 @unnumberedsec For Whom This is Written
899 This text is written as an elementary introduction for people who are
900 not programmers. If you are a programmer, you may not be satisfied with
901 this primer. The reason is that you may have become expert at reading
902 reference manuals and be put off by the way this text is organized.
904 An expert programmer who reviewed this text said to me:
907 @i{I prefer to learn from reference manuals. I ``dive into'' each
908 paragraph, and ``come up for air'' between paragraphs.}
910 @i{When I get to the end of a paragraph, I assume that that subject is
911 done, finished, that I know everything I need (with the
912 possible exception of the case when the next paragraph starts talking
913 about it in more detail). I expect that a well written reference manual
914 will not have a lot of redundancy, and that it will have excellent
915 pointers to the (one) place where the information I want is.}
918 This introduction is not written for this person!
920 Firstly, I try to say everything at least three times: first, to
921 introduce it; second, to show it in context; and third, to show it in a
922 different context, or to review it.
924 Secondly, I hardly ever put all the information about a subject in one
925 place, much less in one paragraph. To my way of thinking, that imposes
926 too heavy a burden on the reader. Instead I try to explain only what
927 you need to know at the time. (Sometimes I include a little extra
928 information so you won't be surprised later when the additional
929 information is formally introduced.)
931 When you read this text, you are not expected to learn everything the
932 first time. Frequently, you need only make, as it were, a `nodding
933 acquaintance' with some of the items mentioned. My hope is that I have
934 structured the text and given you enough hints that you will be alert to
935 what is important, and concentrate on it.
937 You will need to ``dive into'' some paragraphs; there is no other way
938 to read them. But I have tried to keep down the number of such
939 paragraphs. This book is intended as an approachable hill, rather than
940 as a daunting mountain.
942 This introduction to @cite{Programming in Emacs Lisp} has a companion
945 @cite{The GNU Emacs Lisp Reference Manual}.
948 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
949 Emacs Lisp Reference Manual}.
951 The reference manual has more detail than this introduction. In the
952 reference manual, all the information about one topic is concentrated
953 in one place. You should turn to it if you are like the programmer
954 quoted above. And, of course, after you have read this
955 @cite{Introduction}, you will find the @cite{Reference Manual} useful
956 when you are writing your own programs.
958 @node Lisp History, Note for Novices, Who You Are, Preface
959 @unnumberedsec Lisp History
962 Lisp was first developed in the late 1950s at the Massachusetts
963 Institute of Technology for research in artificial intelligence. The
964 great power of the Lisp language makes it superior for other purposes as
965 well, such as writing editor commands and integrated environments.
969 GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT
970 in the 1960s. It is somewhat inspired by Common Lisp, which became a
971 standard in the 1980s. However, Emacs Lisp is much simpler than Common
972 Lisp. (The standard Emacs distribution contains an optional extensions
973 file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.)
975 @node Note for Novices, Thank You, Lisp History, Preface
976 @comment node-name, next, previous, up
977 @unnumberedsec A Note for Novices
979 If you don't know GNU Emacs, you can still read this document
980 profitably. However, I recommend you learn Emacs, if only to learn to
981 move around your computer screen. You can teach yourself how to use
982 Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This
983 means you press and release the @key{CTRL} key and the @kbd{h} at the
984 same time, and then press and release @kbd{t}.)
986 Also, I often refer to one of Emacs' standard commands by listing the
987 keys which you press to invoke the command and then giving the name of
988 the command in parentheses, like this: @kbd{M-C-\}
989 (@code{indent-region}). What this means is that the
990 @code{indent-region} command is customarily invoked by typing
991 @kbd{M-C-\}. (You can, if you wish, change the keys that are typed to
992 invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, ,
993 Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your
994 @key{META} key, @key{CTRL} key and @key{\} key all at the same time.
995 (On many modern keyboards the @key{META} key is labelled
997 Sometimes a combination like this is called a keychord, since it is
998 similar to the way you play a chord on a piano. If your keyboard does
999 not have a @key{META} key, the @key{ESC} key prefix is used in place
1000 of it. In this case, @kbd{M-C-\} means that you press and release your
1001 @key{ESC} key and then type the @key{CTRL} key and the @key{\} key at
1002 the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key
1003 along with the key that is labelled @key{ALT} and, at the same time,
1004 press the @key{\} key.
1006 In addition to typing a lone keychord, you can prefix what you type
1007 with @kbd{C-u}, which is called the `universal argument'. The
1008 @kbd{C-u} keychord passes an argument to the subsequent command.
1009 Thus, to indent a region of plain text by 6 spaces, mark the region,
1010 and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number,
1011 Emacs either passes the number 4 to the command or otherwise runs the
1012 command differently than it would otherwise.) @xref{Arguments, ,
1013 Numeric Arguments, emacs, The GNU Emacs Manual}.
1015 If you are reading this in Info using GNU Emacs, you can read through
1016 this whole document just by pressing the space bar, @key{SPC}.
1017 (To learn about Info, type @kbd{C-h i} and then select Info.)
1019 A note on terminology: when I use the word Lisp alone, I often am
1020 referring to the various dialects of Lisp in general, but when I speak
1021 of Emacs Lisp, I am referring to GNU Emacs Lisp in particular.
1023 @node Thank You, , Note for Novices, Preface
1024 @comment node-name, next, previous, up
1025 @unnumberedsec Thank You
1027 My thanks to all who helped me with this book. My especial thanks to
1028 @r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland
1029 McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@:
1030 Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both
1031 @w{Philip Johnson} and @w{David Stampe} for their patient
1032 encouragement. My mistakes are my own.
1038 @c ================ Beginning of main text ================
1040 @c Start main text on right-hand (verso) page
1043 \par\vfill\supereject
1046 \par\vfill\supereject
1048 \par\vfill\supereject
1050 \par\vfill\supereject
1056 @evenheading @thispage @| @| @thischapter
1057 @oddheading @thissection @| @| @thispage
1061 @node List Processing, Practicing Evaluation, Preface, Top
1062 @comment node-name, next, previous, up
1063 @chapter List Processing
1065 To the untutored eye, Lisp is a strange programming language. In Lisp
1066 code there are parentheses everywhere. Some people even claim that
1067 the name stands for `Lots of Isolated Silly Parentheses'. But the
1068 claim is unwarranted. Lisp stands for LISt Processing, and the
1069 programming language handles @emph{lists} (and lists of lists) by
1070 putting them between parentheses. The parentheses mark the boundaries
1071 of the list. Sometimes a list is preceded by a single apostrophe or
1072 quotation mark, @samp{'}@footnote{The single apostrophe or quotation
1073 mark is an abbreviation for the function @code{quote}; you need not
1074 think about functions now; functions are defined in @ref{Making
1075 Errors, , Generate an Error Message}.} Lists are the basis of Lisp.
1081 * Names & Definitions::
1082 * Lisp Interpreter::
1088 * Error Message Exercises::
1091 @node Lisp Lists, Run a Program, List Processing, List Processing
1092 @comment node-name, next, previous, up
1096 In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}.
1097 This list is preceded by a single apostrophe. It could just as well be
1098 written as follows, which looks more like the kind of list you are likely
1099 to be familiar with:
1111 The elements of this list are the names of the four different flowers,
1112 separated from each other by whitespace and surrounded by parentheses,
1113 like flowers in a field with a stone wall around them.
1114 @cindex Flowers in a field
1119 * Whitespace in Lists::
1123 @node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists
1125 @unnumberedsubsec Numbers, Lists inside of Lists
1128 Lists can also have numbers in them, as in this list: @code{(+ 2 2)}.
1129 This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each
1130 separated by whitespace.
1132 In Lisp, both data and programs are represented the same way; that is,
1133 they are both lists of words, numbers, or other lists, separated by
1134 whitespace and surrounded by parentheses. (Since a program looks like
1135 data, one program may easily serve as data for another; this is a very
1136 powerful feature of Lisp.) (Incidentally, these two parenthetical
1137 remarks are @emph{not} Lisp lists, because they contain @samp{;} and
1138 @samp{.} as punctuation marks.)
1141 Here is another list, this time with a list inside of it:
1144 '(this list has (a list inside of it))
1147 The components of this list are the words @samp{this}, @samp{list},
1148 @samp{has}, and the list @samp{(a list inside of it)}. The interior
1149 list is made up of the words @samp{a}, @samp{list}, @samp{inside},
1150 @samp{of}, @samp{it}.
1152 @node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists
1153 @comment node-name, next, previous, up
1154 @subsection Lisp Atoms
1157 In Lisp, what we have been calling words are called @dfn{atoms}. This
1158 term comes from the historical meaning of the word atom, which means
1159 `indivisible'. As far as Lisp is concerned, the words we have been
1160 using in the lists cannot be divided into any smaller parts and still
1161 mean the same thing as part of a program; likewise with numbers and
1162 single character symbols like @samp{+}. On the other hand, unlike an
1163 ancient atom, a list can be split into parts. (@xref{car cdr & cons,
1164 , @code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
1166 In a list, atoms are separated from each other by whitespace. They can be
1167 right next to a parenthesis.
1169 @cindex @samp{empty list} defined
1170 Technically speaking, a list in Lisp consists of parentheses surrounding
1171 atoms separated by whitespace or surrounding other lists or surrounding
1172 both atoms and other lists. A list can have just one atom in it or
1173 have nothing in it at all. A list with nothing in it looks like this:
1174 @code{()}, and is called the @dfn{empty list}. Unlike anything else, an
1175 empty list is considered both an atom and a list at the same time.
1177 @cindex Symbolic expressions, introduced
1178 @cindex @samp{expression} defined
1179 @cindex @samp{form} defined
1180 The printed representation of both atoms and lists are called
1181 @dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}.
1182 The word @dfn{expression} by itself can refer to either the printed
1183 representation, or to the atom or list as it is held internally in the
1184 computer. Often, people use the term @dfn{expression}
1185 indiscriminately. (Also, in many texts, the word @dfn{form} is used
1186 as a synonym for expression.)
1188 Incidentally, the atoms that make up our universe were named such when
1189 they were thought to be indivisible; but it has been found that physical
1190 atoms are not indivisible. Parts can split off an atom or it can
1191 fission into two parts of roughly equal size. Physical atoms were named
1192 prematurely, before their truer nature was found. In Lisp, certain
1193 kinds of atom, such as an array, can be separated into parts; but the
1194 mechanism for doing this is different from the mechanism for splitting a
1195 list. As far as list operations are concerned, the atoms of a list are
1198 As in English, the meanings of the component letters of a Lisp atom
1199 are different from the meaning the letters make as a word. For
1200 example, the word for the South American sloth, the @samp{ai}, is
1201 completely different from the two words, @samp{a}, and @samp{i}.
1203 There are many kinds of atom in nature but only a few in Lisp: for
1204 example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such
1205 as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have
1206 listed in the examples above are all symbols. In everyday Lisp
1207 conversation, the word ``atom'' is not often used, because programmers
1208 usually try to be more specific about what kind of atom they are dealing
1209 with. Lisp programming is mostly about symbols (and sometimes numbers)
1210 within lists. (Incidentally, the preceding three word parenthetical
1211 remark is a proper list in Lisp, since it consists of atoms, which in
1212 this case are symbols, separated by whitespace and enclosed by
1213 parentheses, without any non-Lisp punctuation.)
1216 In addition, text between double quotation marks---even sentences or
1217 paragraphs---is an atom. Here is an example:
1218 @cindex Text between double quotation marks
1221 '(this list includes "text between quotation marks.")
1224 @cindex @samp{string} defined
1226 In Lisp, all of the quoted text including the punctuation mark and the
1227 blank spaces is a single atom. This kind of atom is called a
1228 @dfn{string} (for `string of characters') and is the sort of thing that
1229 is used for messages that a computer can print for a human to read.
1230 Strings are a different kind of atom than numbers or symbols and are
1233 @node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists
1234 @comment node-name, next, previous, up
1235 @subsection Whitespace in Lists
1236 @cindex Whitespace in lists
1239 The amount of whitespace in a list does not matter. From the point of view
1240 of the Lisp language,
1251 is exactly the same as this:
1254 '(this list looks like this)
1257 Both examples show what to Lisp is the same list, the list made up of
1258 the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and
1259 @samp{this} in that order.
1261 Extra whitespace and newlines are designed to make a list more readable
1262 by humans. When Lisp reads the expression, it gets rid of all the extra
1263 whitespace (but it needs to have at least one space between atoms in
1264 order to tell them apart.)
1266 Odd as it seems, the examples we have seen cover almost all of what Lisp
1267 lists look like! Every other list in Lisp looks more or less like one
1268 of these examples, except that the list may be longer and more complex.
1269 In brief, a list is between parentheses, a string is between quotation
1270 marks, a symbol looks like a word, and a number looks like a number.
1271 (For certain situations, square brackets, dots and a few other special
1272 characters may be used; however, we will go quite far without them.)
1274 @node Typing Lists, , Whitespace in Lists, Lisp Lists
1275 @comment node-name, next, previous, up
1276 @subsection GNU Emacs Helps You Type Lists
1277 @cindex Help typing lists
1278 @cindex Formatting help
1280 When you type a Lisp expression in GNU Emacs using either Lisp
1281 Interaction mode or Emacs Lisp mode, you have available to you several
1282 commands to format the Lisp expression so it is easy to read. For
1283 example, pressing the @key{TAB} key automatically indents the line the
1284 cursor is on by the right amount. A command to properly indent the
1285 code in a region is customarily bound to @kbd{M-C-\}. Indentation is
1286 designed so that you can see which elements of a list belong to which
1287 list---elements of a sub-list are indented more than the elements of
1290 In addition, when you type a closing parenthesis, Emacs momentarily
1291 jumps the cursor back to the matching opening parenthesis, so you can
1292 see which one it is. This is very useful, since every list you type
1293 in Lisp must have its closing parenthesis match its opening
1294 parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs
1295 Manual}, for more information about Emacs' modes.)
1297 @node Run a Program, Making Errors, Lisp Lists, List Processing
1298 @comment node-name, next, previous, up
1299 @section Run a Program
1300 @cindex Run a program
1301 @cindex Program, running one
1303 @cindex @samp{evaluate} defined
1304 A list in Lisp---any list---is a program ready to run. If you run it
1305 (for which the Lisp jargon is @dfn{evaluate}), the computer will do one
1306 of three things: do nothing except return to you the list itself; send
1307 you an error message; or, treat the first symbol in the list as a
1308 command to do something. (Usually, of course, it is the last of these
1309 three things that you really want!)
1311 @c use code for the single apostrophe, not samp.
1312 The single apostrophe, @code{'}, that I put in front of some of the
1313 example lists in preceding sections is called a @dfn{quote}; when it
1314 precedes a list, it tells Lisp to do nothing with the list, other than
1315 take it as it is written. But if there is no quote preceding a list,
1316 the first item of the list is special: it is a command for the computer
1317 to obey. (In Lisp, these commands are called @emph{functions}.) The list
1318 @code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp
1319 understands that the @code{+} is an instruction to do something with the
1320 rest of the list: add the numbers that follow.
1323 If you are reading this inside of GNU Emacs in Info, here is how you can
1324 evaluate such a list: place your cursor immediately after the right
1325 hand parenthesis of the following list and then type @kbd{C-x C-e}:
1331 @c use code for the number four, not samp.
1333 You will see the number @code{4} appear in the echo area. (In the
1334 jargon, what you have just done is ``evaluate the list.'' The echo area
1335 is the line at the bottom of the screen that displays or ``echoes''
1336 text.) Now try the same thing with a quoted list: place the cursor
1337 right after the following list and type @kbd{C-x C-e}:
1340 '(this is a quoted list)
1344 You will see @code{(this is a quoted list)} appear in the echo area.
1346 @cindex Lisp interpreter, explained
1347 @cindex Interpreter, Lisp, explained
1348 In both cases, what you are doing is giving a command to the program
1349 inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the
1350 interpreter a command to evaluate the expression. The name of the Lisp
1351 interpreter comes from the word for the task done by a human who comes
1352 up with the meaning of an expression---who ``interprets'' it.
1354 You can also evaluate an atom that is not part of a list---one that is
1355 not surrounded by parentheses; again, the Lisp interpreter translates
1356 from the humanly readable expression to the language of the computer.
1357 But before discussing this (@pxref{Variables}), we will discuss what the
1358 Lisp interpreter does when you make an error.
1360 @node Making Errors, Names & Definitions, Run a Program, List Processing
1361 @comment node-name, next, previous, up
1362 @section Generate an Error Message
1363 @cindex Generate an error message
1364 @cindex Error message generation
1366 Partly so you won't worry if you do it accidentally, we will now give
1367 a command to the Lisp interpreter that generates an error message.
1368 This is a harmless activity; and indeed, we will often try to generate
1369 error messages intentionally. Once you understand the jargon, error
1370 messages can be informative. Instead of being called ``error''
1371 messages, they should be called ``help'' messages. They are like
1372 signposts to a traveller in a strange country; deciphering them can be
1373 hard, but once understood, they can point the way.
1375 The error message is generated by a built-in GNU Emacs debugger. We
1376 will `enter the debugger'. You get out of the debugger by typing @code{q}.
1378 What we will do is evaluate a list that is not quoted and does not
1379 have a meaningful command as its first element. Here is a list almost
1380 exactly the same as the one we just used, but without the single-quote
1381 in front of it. Position the cursor right after it and type @kbd{C-x
1385 (this is an unquoted list)
1389 What you see depends on which version of Emacs you are running. GNU
1390 Emacs version 22 provides more information than version 20 and before.
1391 First, the more recent result of generating an error; then the
1392 earlier, version 20 result.
1396 In GNU Emacs version 22, a @file{*Backtrace*} window will open up and
1397 you will see the following in it:
1401 ---------- Buffer: *Backtrace* ----------
1402 Debugger entered--Lisp error: (void-function this)
1403 (this is an unquoted list)
1404 eval((this is an unquoted list))
1405 eval-last-sexp-1(nil)
1407 call-interactively(eval-last-sexp)
1408 ---------- Buffer: *Backtrace* ----------
1414 Your cursor will be in this window (you may have to wait a few seconds
1415 before it becomes visible). To quit the debugger and make the
1416 debugger window go away, type:
1423 Please type @kbd{q} right now, so you become confident that you can
1424 get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter
1427 @cindex @samp{function} defined
1428 Based on what we already know, we can almost read this error message.
1430 You read the @file{*Backtrace*} buffer from the bottom up; it tells
1431 you what Emacs did. When you typed @kbd{C-x C-e}, you made an
1432 interactive call to the command @code{eval-last-sexp}. @code{eval} is
1433 an abbreviation for `evaluate' and @code{sexp} is an abbreviation for
1434 `symbolic expression'. The command means `evaluate last symbolic
1435 expression', which is the expression just before your cursor.
1437 Each line above tells you what the Lisp interpreter evaluated next.
1438 The most recent action is at the top. The buffer is called the
1439 @file{*Backtrace*} buffer because it enables you to track Emacs
1443 At the top of the @file{*Backtrace*} buffer, you see the line:
1446 Debugger entered--Lisp error: (void-function this)
1450 The Lisp interpreter tried to evaluate the first atom of the list, the
1451 word @samp{this}. It is this action that generated the error message
1452 @samp{void-function this}.
1454 The message contains the words @samp{void-function} and @samp{this}.
1456 @cindex @samp{function} defined
1457 The word @samp{function} was mentioned once before. It is a very
1458 important word. For our purposes, we can define it by saying that a
1459 @dfn{function} is a set of instructions to the computer that tell the
1460 computer to do something.
1462 Now we can begin to understand the error message: @samp{void-function
1463 this}. The function (that is, the word @samp{this}) does not have a
1464 definition of any set of instructions for the computer to carry out.
1466 The slightly odd word, @samp{void-function}, is designed to cover the
1467 way Emacs Lisp is implemented, which is that when a symbol does not
1468 have a function definition attached to it, the place that should
1469 contain the instructions is `void'.
1471 On the other hand, since we were able to add 2 plus 2 successfully, by
1472 evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must
1473 have a set of instructions for the computer to obey and those
1474 instructions must be to add the numbers that follow the @code{+}.
1477 In GNU Emacs version 20, and in earlier versions, you will see only
1478 one line of error message; it will appear in the echo area and look
1482 Symbol's function definition is void:@: this
1486 (Also, your terminal may beep at you---some do, some don't; and others
1487 blink. This is just a device to get your attention.) The message goes
1488 away as soon as you type another key, even just to move the cursor.
1490 We know the meaning of the word @samp{Symbol}. It refers to the first
1491 atom of the list, the word @samp{this}. The word @samp{function}
1492 refers to the instructions that tell the computer what to do.
1493 (Technically, the symbol tells the computer where to find the
1494 instructions, but this is a complication we can ignore for the
1497 The error message can be understood: @samp{Symbol's function
1498 definition is void:@: this}. The symbol (that is, the word
1499 @samp{this}) lacks instructions for the computer to carry out.
1501 @node Names & Definitions, Lisp Interpreter, Making Errors, List Processing
1502 @comment node-name, next, previous, up
1503 @section Symbol Names and Function Definitions
1504 @cindex Symbol names
1506 We can articulate another characteristic of Lisp based on what we have
1507 discussed so far---an important characteristic: a symbol, like
1508 @code{+}, is not itself the set of instructions for the computer to
1509 carry out. Instead, the symbol is used, perhaps temporarily, as a way
1510 of locating the definition or set of instructions. What we see is the
1511 name through which the instructions can be found. Names of people
1512 work the same way. I can be referred to as @samp{Bob}; however, I am
1513 not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the
1514 consciousness consistently associated with a particular life-form.
1515 The name is not me, but it can be used to refer to me.
1517 In Lisp, one set of instructions can be attached to several names.
1518 For example, the computer instructions for adding numbers can be
1519 linked to the symbol @code{plus} as well as to the symbol @code{+}
1520 (and are in some dialects of Lisp). Among humans, I can be referred
1521 to as @samp{Robert} as well as @samp{Bob} and by other words as well.
1523 On the other hand, a symbol can have only one function definition
1524 attached to it at a time. Otherwise, the computer would be confused as
1525 to which definition to use. If this were the case among people, only
1526 one person in the world could be named @samp{Bob}. However, the function
1527 definition to which the name refers can be changed readily.
1528 (@xref{Install, , Install a Function Definition}.)
1530 Since Emacs Lisp is large, it is customary to name symbols in a way
1531 that identifies the part of Emacs to which the function belongs.
1532 Thus, all the names for functions that deal with Texinfo start with
1533 @samp{texinfo-} and those for functions that deal with reading mail
1534 start with @samp{rmail-}.
1536 @node Lisp Interpreter, Evaluation, Names & Definitions, List Processing
1537 @comment node-name, next, previous, up
1538 @section The Lisp Interpreter
1539 @cindex Lisp interpreter, what it does
1540 @cindex Interpreter, what it does
1542 Based on what we have seen, we can now start to figure out what the
1543 Lisp interpreter does when we command it to evaluate a list.
1544 First, it looks to see whether there is a quote before the list; if
1545 there is, the interpreter just gives us the list. On the other
1546 hand, if there is no quote, the interpreter looks at the first element
1547 in the list and sees whether it has a function definition. If it does,
1548 the interpreter carries out the instructions in the function definition.
1549 Otherwise, the interpreter prints an error message.
1551 This is how Lisp works. Simple. There are added complications which we
1552 will get to in a minute, but these are the fundamentals. Of course, to
1553 write Lisp programs, you need to know how to write function definitions
1554 and attach them to names, and how to do this without confusing either
1555 yourself or the computer.
1562 @node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter
1564 @unnumberedsubsec Complications
1567 Now, for the first complication. In addition to lists, the Lisp
1568 interpreter can evaluate a symbol that is not quoted and does not have
1569 parentheses around it. The Lisp interpreter will attempt to determine
1570 the symbol's value as a @dfn{variable}. This situation is described
1571 in the section on variables. (@xref{Variables}.)
1573 @cindex Special form
1574 The second complication occurs because some functions are unusual and do
1575 not work in the usual manner. Those that don't are called @dfn{special
1576 forms}. They are used for special jobs, like defining a function, and
1577 there are not many of them. In the next few chapters, you will be
1578 introduced to several of the more important special forms.
1580 The third and final complication is this: if the function that the
1581 Lisp interpreter is looking at is not a special form, and if it is part
1582 of a list, the Lisp interpreter looks to see whether the list has a list
1583 inside of it. If there is an inner list, the Lisp interpreter first
1584 figures out what it should do with the inside list, and then it works on
1585 the outside list. If there is yet another list embedded inside the
1586 inner list, it works on that one first, and so on. It always works on
1587 the innermost list first. The interpreter works on the innermost list
1588 first, to evaluate the result of that list. The result may be
1589 used by the enclosing expression.
1591 Otherwise, the interpreter works left to right, from one expression to
1594 @node Byte Compiling, , Complications, Lisp Interpreter
1595 @subsection Byte Compiling
1596 @cindex Byte compiling
1598 One other aspect of interpreting: the Lisp interpreter is able to
1599 interpret two kinds of entity: humanly readable code, on which we will
1600 focus exclusively, and specially processed code, called @dfn{byte
1601 compiled} code, which is not humanly readable. Byte compiled code
1602 runs faster than humanly readable code.
1604 You can transform humanly readable code into byte compiled code by
1605 running one of the compile commands such as @code{byte-compile-file}.
1606 Byte compiled code is usually stored in a file that ends with a
1607 @file{.elc} extension rather than a @file{.el} extension. You will
1608 see both kinds of file in the @file{emacs/lisp} directory; the files
1609 to read are those with @file{.el} extensions.
1611 As a practical matter, for most things you might do to customize or
1612 extend Emacs, you do not need to byte compile; and I will not discuss
1613 the topic here. @xref{Byte Compilation, , Byte Compilation, elisp,
1614 The GNU Emacs Lisp Reference Manual}, for a full description of byte
1617 @node Evaluation, Variables, Lisp Interpreter, List Processing
1618 @comment node-name, next, previous, up
1622 When the Lisp interpreter works on an expression, the term for the
1623 activity is called @dfn{evaluation}. We say that the interpreter
1624 `evaluates the expression'. I've used this term several times before.
1625 The word comes from its use in everyday language, `to ascertain the
1626 value or amount of; to appraise', according to @cite{Webster's New
1627 Collegiate Dictionary}.
1629 After evaluating an expression, the Lisp interpreter will most likely
1630 @dfn{return} the value that the computer produces by carrying out the
1631 instructions it found in the function definition, or perhaps it will
1632 give up on that function and produce an error message. (The interpreter
1633 may also find itself tossed, so to speak, to a different function or it
1634 may attempt to repeat continually what it is doing for ever and ever in
1635 what is called an `infinite loop'. These actions are less common; and
1636 we can ignore them.) Most frequently, the interpreter returns a value.
1638 @cindex @samp{side effect} defined
1639 At the same time the interpreter returns a value, it may do something
1640 else as well, such as move a cursor or copy a file; this other kind of
1641 action is called a @dfn{side effect}. Actions that we humans think are
1642 important, such as printing results, are often ``side effects'' to the
1643 Lisp interpreter. The jargon can sound peculiar, but it turns out that
1644 it is fairly easy to learn to use side effects.
1646 In summary, evaluating a symbolic expression most commonly causes the
1647 Lisp interpreter to return a value and perhaps carry out a side effect;
1648 or else produce an error.
1651 * Evaluating Inner Lists::
1654 @node Evaluating Inner Lists, , Evaluation, Evaluation
1655 @comment node-name, next, previous, up
1656 @subsection Evaluating Inner Lists
1657 @cindex Inner list evaluation
1658 @cindex Evaluating inner lists
1660 If evaluation applies to a list that is inside another list, the outer
1661 list may use the value returned by the first evaluation as information
1662 when the outer list is evaluated. This explains why inner expressions
1663 are evaluated first: the values they return are used by the outer
1667 We can investigate this process by evaluating another addition example.
1668 Place your cursor after the following expression and type @kbd{C-x C-e}:
1675 The number 8 will appear in the echo area.
1677 What happens is that the Lisp interpreter first evaluates the inner
1678 expression, @code{(+ 3 3)}, for which the value 6 is returned; then it
1679 evaluates the outer expression as if it were written @code{(+ 2 6)}, which
1680 returns the value 8. Since there are no more enclosing expressions to
1681 evaluate, the interpreter prints that value in the echo area.
1683 Now it is easy to understand the name of the command invoked by the
1684 keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The
1685 letters @code{sexp} are an abbreviation for `symbolic expression', and
1686 @code{eval} is an abbreviation for `evaluate'. The command means
1687 `evaluate last symbolic expression'.
1689 As an experiment, you can try evaluating the expression by putting the
1690 cursor at the beginning of the next line immediately following the
1691 expression, or inside the expression.
1694 Here is another copy of the expression:
1701 If you place the cursor at the beginning of the blank line that
1702 immediately follows the expression and type @kbd{C-x C-e}, you will
1703 still get the value 8 printed in the echo area. Now try putting the
1704 cursor inside the expression. If you put it right after the next to
1705 last parenthesis (so it appears to sit on top of the last parenthesis),
1706 you will get a 6 printed in the echo area! This is because the command
1707 evaluates the expression @code{(+ 3 3)}.
1709 Now put the cursor immediately after a number. Type @kbd{C-x C-e} and
1710 you will get the number itself. In Lisp, if you evaluate a number, you
1711 get the number itself---this is how numbers differ from symbols. If you
1712 evaluate a list starting with a symbol like @code{+}, you will get a
1713 value returned that is the result of the computer carrying out the
1714 instructions in the function definition attached to that name. If a
1715 symbol by itself is evaluated, something different happens, as we will
1716 see in the next section.
1718 @node Variables, Arguments, Evaluation, List Processing
1719 @comment node-name, next, previous, up
1723 In Emacs Lisp, a symbol can have a value attached to it just as it can
1724 have a function definition attached to it. The two are different.
1725 The function definition is a set of instructions that a computer will
1726 obey. A value, on the other hand, is something, such as number or a
1727 name, that can vary (which is why such a symbol is called a variable).
1728 The value of a symbol can be any expression in Lisp, such as a symbol,
1729 number, list, or string. A symbol that has a value is often called a
1732 A symbol can have both a function definition and a value attached to
1733 it at the same time. Or it can have just one or the other.
1734 The two are separate. This is somewhat similar
1735 to the way the name Cambridge can refer to the city in Massachusetts
1736 and have some information attached to the name as well, such as
1737 ``great programming center''.
1740 (Incidentally, in Emacs Lisp, a symbol can have two
1741 other things attached to it, too: a property list and a documentation
1742 string; these are discussed later.)
1745 Another way to think about this is to imagine a symbol as being a chest
1746 of drawers. The function definition is put in one drawer, the value in
1747 another, and so on. What is put in the drawer holding the value can be
1748 changed without affecting the contents of the drawer holding the
1749 function definition, and vice-verse.
1752 * fill-column Example::
1757 @node fill-column Example, Void Function, Variables, Variables
1759 @unnumberedsubsec @code{fill-column}, an Example Variable
1762 @findex fill-column, @r{an example variable}
1763 @cindex Example variable, @code{fill-column}
1764 @cindex Variable, example of, @code{fill-column}
1765 The variable @code{fill-column} illustrates a symbol with a value
1766 attached to it: in every GNU Emacs buffer, this symbol is set to some
1767 value, usually 72 or 70, but sometimes to some other value. To find the
1768 value of this symbol, evaluate it by itself. If you are reading this in
1769 Info inside of GNU Emacs, you can do this by putting the cursor after
1770 the symbol and typing @kbd{C-x C-e}:
1777 After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo
1778 area. This is the value for which @code{fill-column} is set for me as I
1779 write this. It may be different for you in your Info buffer. Notice
1780 that the value returned as a variable is printed in exactly the same way
1781 as the value returned by a function carrying out its instructions. From
1782 the point of view of the Lisp interpreter, a value returned is a value
1783 returned. What kind of expression it came from ceases to matter once
1786 A symbol can have any value attached to it or, to use the jargon, we can
1787 @dfn{bind} the variable to a value: to a number, such as 72; to a
1788 string, @code{"such as this"}; to a list, such as @code{(spruce pine
1789 oak)}; we can even bind a variable to a function definition.
1791 A symbol can be bound to a value in several ways. @xref{set & setq, ,
1792 Setting the Value of a Variable}, for information about one way to do
1795 @node Void Function, Void Variable, fill-column Example, Variables
1796 @comment node-name, next, previous, up
1797 @subsection Error Message for a Symbol Without a Function
1798 @cindex Symbol without function error
1799 @cindex Error for symbol without function
1801 When we evaluated @code{fill-column} to find its value as a variable,
1802 we did not place parentheses around the word. This is because we did
1803 not intend to use it as a function name.
1805 If @code{fill-column} were the first or only element of a list, the
1806 Lisp interpreter would attempt to find the function definition
1807 attached to it. But @code{fill-column} has no function definition.
1808 Try evaluating this:
1816 In GNU Emacs version 22, you will create a @file{*Backtrace*} buffer
1821 ---------- Buffer: *Backtrace* ----------
1822 Debugger entered--Lisp error: (void-function fill-column)
1825 eval-last-sexp-1(nil)
1827 call-interactively(eval-last-sexp)
1828 ---------- Buffer: *Backtrace* ----------
1833 (Remember, to quit the debugger and make the debugger window go away,
1834 type @kbd{q} in the @file{*Backtrace*} buffer.)
1838 In GNU Emacs 20 and before, you will produce an error message that says:
1841 Symbol's function definition is void:@: fill-column
1845 (The message will go away as soon as you move the cursor or type
1849 @node Void Variable, , Void Function, Variables
1850 @comment node-name, next, previous, up
1851 @subsection Error Message for a Symbol Without a Value
1852 @cindex Symbol without value error
1853 @cindex Error for symbol without value
1855 If you attempt to evaluate a symbol that does not have a value bound to
1856 it, you will receive an error message. You can see this by
1857 experimenting with our 2 plus 2 addition. In the following expression,
1858 put your cursor right after the @code{+}, before the first number 2,
1867 In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that
1872 ---------- Buffer: *Backtrace* ----------
1873 Debugger entered--Lisp error: (void-variable +)
1875 eval-last-sexp-1(nil)
1877 call-interactively(eval-last-sexp)
1878 ---------- Buffer: *Backtrace* ----------
1883 (As with the other times we entered the debugger, you can quit by
1884 typing @kbd{q} in the @file{*Backtrace*} buffer.)
1886 This backtrace is different from the very first error message we saw,
1887 which said, @samp{Debugger entered--Lisp error: (void-function this)}.
1888 In this case, the function does not have a value as a variable; while
1889 in the other error message, the function (the word `this') did not
1892 In this experiment with the @code{+}, what we did was cause the Lisp
1893 interpreter to evaluate the @code{+} and look for the value of the
1894 variable instead of the function definition. We did this by placing the
1895 cursor right after the symbol rather than after the parenthesis of the
1896 enclosing list as we did before. As a consequence, the Lisp interpreter
1897 evaluated the preceding s-expression, which in this case was the
1900 Since @code{+} does not have a value bound to it, just the function
1901 definition, the error message reported that the symbol's value as a
1906 In GNU Emacs version 20 and before, your error message will say:
1909 Symbol's value as variable is void:@: +
1913 The meaning is the same as in GNU Emacs 22.
1916 @node Arguments, set & setq, Variables, List Processing
1917 @comment node-name, next, previous, up
1920 @cindex Passing information to functions
1922 To see how information is passed to functions, let's look again at
1923 our old standby, the addition of two plus two. In Lisp, this is written
1930 If you evaluate this expression, the number 4 will appear in your echo
1931 area. What the Lisp interpreter does is add the numbers that follow
1934 @cindex @samp{argument} defined
1935 The numbers added by @code{+} are called the @dfn{arguments} of the
1936 function @code{+}. These numbers are the information that is given to
1937 or @dfn{passed} to the function.
1939 The word `argument' comes from the way it is used in mathematics and
1940 does not refer to a disputation between two people; instead it refers to
1941 the information presented to the function, in this case, to the
1942 @code{+}. In Lisp, the arguments to a function are the atoms or lists
1943 that follow the function. The values returned by the evaluation of
1944 these atoms or lists are passed to the function. Different functions
1945 require different numbers of arguments; some functions require none at
1946 all.@footnote{It is curious to track the path by which the word `argument'
1947 came to have two different meanings, one in mathematics and the other in
1948 everyday English. According to the @cite{Oxford English Dictionary},
1949 the word derives from the Latin for @samp{to make clear, prove}; thus it
1950 came to mean, by one thread of derivation, `the evidence offered as
1951 proof', which is to say, `the information offered', which led to its
1952 meaning in Lisp. But in the other thread of derivation, it came to mean
1953 `to assert in a manner against which others may make counter
1954 assertions', which led to the meaning of the word as a disputation.
1955 (Note here that the English word has two different definitions attached
1956 to it at the same time. By contrast, in Emacs Lisp, a symbol cannot
1957 have two different function definitions at the same time.)}
1961 * Args as Variable or List::
1962 * Variable Number of Arguments::
1963 * Wrong Type of Argument::
1967 @node Data types, Args as Variable or List, Arguments, Arguments
1968 @comment node-name, next, previous, up
1969 @subsection Arguments' Data Types
1971 @cindex Types of data
1972 @cindex Arguments' data types
1974 The type of data that should be passed to a function depends on what
1975 kind of information it uses. The arguments to a function such as
1976 @code{+} must have values that are numbers, since @code{+} adds numbers.
1977 Other functions use different kinds of data for their arguments.
1981 For example, the @code{concat} function links together or unites two or
1982 more strings of text to produce a string. The arguments are strings.
1983 Concatenating the two character strings @code{abc}, @code{def} produces
1984 the single string @code{abcdef}. This can be seen by evaluating the
1988 (concat "abc" "def")
1992 The value produced by evaluating this expression is @code{"abcdef"}.
1994 A function such as @code{substring} uses both a string and numbers as
1995 arguments. The function returns a part of the string, a substring of
1996 the first argument. This function takes three arguments. Its first
1997 argument is the string of characters, the second and third arguments are
1998 numbers that indicate the beginning and end of the substring. The
1999 numbers are a count of the number of characters (including spaces and
2000 punctuations) from the beginning of the string.
2003 For example, if you evaluate the following:
2006 (substring "The quick brown fox jumped." 16 19)
2010 you will see @code{"fox"} appear in the echo area. The arguments are the
2011 string and the two numbers.
2013 Note that the string passed to @code{substring} is a single atom even
2014 though it is made up of several words separated by spaces. Lisp counts
2015 everything between the two quotation marks as part of the string,
2016 including the spaces. You can think of the @code{substring} function as
2017 a kind of `atom smasher' since it takes an otherwise indivisible atom
2018 and extracts a part. However, @code{substring} is only able to extract
2019 a substring from an argument that is a string, not from another type of
2020 atom such as a number or symbol.
2022 @node Args as Variable or List, Variable Number of Arguments, Data types, Arguments
2023 @comment node-name, next, previous, up
2024 @subsection An Argument as the Value of a Variable or List
2026 An argument can be a symbol that returns a value when it is evaluated.
2027 For example, when the symbol @code{fill-column} by itself is evaluated,
2028 it returns a number. This number can be used in an addition.
2031 Position the cursor after the following expression and type @kbd{C-x
2039 The value will be a number two more than what you get by evaluating
2040 @code{fill-column} alone. For me, this is 74, because my value of
2041 @code{fill-column} is 72.
2043 As we have just seen, an argument can be a symbol that returns a value
2044 when evaluated. In addition, an argument can be a list that returns a
2045 value when it is evaluated. For example, in the following expression,
2046 the arguments to the function @code{concat} are the strings
2047 @w{@code{"The "}} and @w{@code{" red foxes."}} and the list
2048 @code{(number-to-string (+ 2 fill-column))}.
2050 @c For GNU Emacs 22, need number-to-string
2052 (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
2056 If you evaluate this expression---and if, as with my Emacs,
2057 @code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will
2058 appear in the echo area. (Note that you must put spaces after the
2059 word @samp{The} and before the word @samp{red} so they will appear in
2060 the final string. The function @code{number-to-string} converts the
2061 integer that the addition function returns to a string.
2062 @code{number-to-string} is also known as @code{int-to-string}.)
2064 @node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments
2065 @comment node-name, next, previous, up
2066 @subsection Variable Number of Arguments
2067 @cindex Variable number of arguments
2068 @cindex Arguments, variable number of
2070 Some functions, such as @code{concat}, @code{+} or @code{*}, take any
2071 number of arguments. (The @code{*} is the symbol for multiplication.)
2072 This can be seen by evaluating each of the following expressions in
2073 the usual way. What you will see in the echo area is printed in this
2074 text after @samp{@result{}}, which you may read as `evaluates to'.
2077 In the first set, the functions have no arguments:
2088 In this set, the functions have one argument each:
2099 In this set, the functions have three arguments each:
2103 (+ 3 4 5) @result{} 12
2105 (* 3 4 5) @result{} 60
2109 @node Wrong Type of Argument, message, Variable Number of Arguments, Arguments
2110 @comment node-name, next, previous, up
2111 @subsection Using the Wrong Type Object as an Argument
2112 @cindex Wrong type of argument
2113 @cindex Argument, wrong type of
2115 When a function is passed an argument of the wrong type, the Lisp
2116 interpreter produces an error message. For example, the @code{+}
2117 function expects the values of its arguments to be numbers. As an
2118 experiment we can pass it the quoted symbol @code{hello} instead of a
2119 number. Position the cursor after the following expression and type
2127 When you do this you will generate an error message. What has happened
2128 is that @code{+} has tried to add the 2 to the value returned by
2129 @code{'hello}, but the value returned by @code{'hello} is the symbol
2130 @code{hello}, not a number. Only numbers can be added. So @code{+}
2131 could not carry out its addition.
2134 In GNU Emacs version 22, you will create and enter a
2135 @file{*Backtrace*} buffer that says:
2140 ---------- Buffer: *Backtrace* ----------
2141 Debugger entered--Lisp error:
2142 (wrong-type-argument number-or-marker-p hello)
2144 eval((+ 2 (quote hello)))
2145 eval-last-sexp-1(nil)
2147 call-interactively(eval-last-sexp)
2148 ---------- Buffer: *Backtrace* ----------
2153 As usual, the error message tries to be helpful and makes sense after you
2154 learn how to read it.@footnote{@code{(quote hello)} is an expansion of
2155 the abbreviation @code{'hello}.}
2157 The first part of the error message is straightforward; it says
2158 @samp{wrong type argument}. Next comes the mysterious jargon word
2159 @w{@samp{number-or-marker-p}}. This word is trying to tell you what
2160 kind of argument the @code{+} expected.
2162 The symbol @code{number-or-marker-p} says that the Lisp interpreter is
2163 trying to determine whether the information presented it (the value of
2164 the argument) is a number or a marker (a special object representing a
2165 buffer position). What it does is test to see whether the @code{+} is
2166 being given numbers to add. It also tests to see whether the
2167 argument is something called a marker, which is a specific feature of
2168 Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers.
2169 When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command,
2170 its position is kept as a marker. The mark can be considered a
2171 number---the number of characters the location is from the beginning
2172 of the buffer.) In Emacs Lisp, @code{+} can be used to add the
2173 numeric value of marker positions as numbers.
2175 The @samp{p} of @code{number-or-marker-p} is the embodiment of a
2176 practice started in the early days of Lisp programming. The @samp{p}
2177 stands for `predicate'. In the jargon used by the early Lisp
2178 researchers, a predicate refers to a function to determine whether some
2179 property is true or false. So the @samp{p} tells us that
2180 @code{number-or-marker-p} is the name of a function that determines
2181 whether it is true or false that the argument supplied is a number or
2182 a marker. Other Lisp symbols that end in @samp{p} include @code{zerop},
2183 a function that tests whether its argument has the value of zero, and
2184 @code{listp}, a function that tests whether its argument is a list.
2186 Finally, the last part of the error message is the symbol @code{hello}.
2187 This is the value of the argument that was passed to @code{+}. If the
2188 addition had been passed the correct type of object, the value passed
2189 would have been a number, such as 37, rather than a symbol like
2190 @code{hello}. But then you would not have got the error message.
2194 In GNU Emacs version 20 and before, the echo area displays an error
2198 Wrong type argument:@: number-or-marker-p, hello
2201 This says, in different words, the same as the top line of the
2202 @file{*Backtrace*} buffer.
2205 @node message, , Wrong Type of Argument, Arguments
2206 @comment node-name, next, previous, up
2207 @subsection The @code{message} Function
2210 Like @code{+}, the @code{message} function takes a variable number of
2211 arguments. It is used to send messages to the user and is so useful
2212 that we will describe it here.
2215 A message is printed in the echo area. For example, you can print a
2216 message in your echo area by evaluating the following list:
2219 (message "This message appears in the echo area!")
2222 The whole string between double quotation marks is a single argument
2223 and is printed @i{in toto}. (Note that in this example, the message
2224 itself will appear in the echo area within double quotes; that is
2225 because you see the value returned by the @code{message} function. In
2226 most uses of @code{message} in programs that you write, the text will
2227 be printed in the echo area as a side-effect, without the quotes.
2228 @xref{multiply-by-seven in detail, , @code{multiply-by-seven} in
2229 detail}, for an example of this.)
2231 However, if there is a @samp{%s} in the quoted string of characters, the
2232 @code{message} function does not print the @samp{%s} as such, but looks
2233 to the argument that follows the string. It evaluates the second
2234 argument and prints the value at the location in the string where the
2238 You can see this by positioning the cursor after the following
2239 expression and typing @kbd{C-x C-e}:
2242 (message "The name of this buffer is: %s." (buffer-name))
2246 In Info, @code{"The name of this buffer is: *info*."} will appear in the
2247 echo area. The function @code{buffer-name} returns the name of the
2248 buffer as a string, which the @code{message} function inserts in place
2251 To print a value as an integer, use @samp{%d} in the same way as
2252 @samp{%s}. For example, to print a message in the echo area that
2253 states the value of the @code{fill-column}, evaluate the following:
2256 (message "The value of fill-column is %d." fill-column)
2260 On my system, when I evaluate this list, @code{"The value of
2261 fill-column is 72."} appears in my echo area@footnote{Actually, you
2262 can use @code{%s} to print a number. It is non-specific. @code{%d}
2263 prints only the part of a number left of a decimal point, and not
2264 anything that is not a number.}.
2266 If there is more than one @samp{%s} in the quoted string, the value of
2267 the first argument following the quoted string is printed at the
2268 location of the first @samp{%s} and the value of the second argument is
2269 printed at the location of the second @samp{%s}, and so on.
2272 For example, if you evaluate the following,
2276 (message "There are %d %s in the office!"
2277 (- fill-column 14) "pink elephants")
2282 a rather whimsical message will appear in your echo area. On my system
2283 it says, @code{"There are 58 pink elephants in the office!"}.
2285 The expression @code{(- fill-column 14)} is evaluated and the resulting
2286 number is inserted in place of the @samp{%d}; and the string in double
2287 quotes, @code{"pink elephants"}, is treated as a single argument and
2288 inserted in place of the @samp{%s}. (That is to say, a string between
2289 double quotes evaluates to itself, like a number.)
2291 Finally, here is a somewhat complex example that not only illustrates
2292 the computation of a number, but also shows how you can use an
2293 expression within an expression to generate the text that is substituted
2298 (message "He saw %d %s"
2302 "The quick brown foxes jumped." 16 21)
2307 In this example, @code{message} has three arguments: the string,
2308 @code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and
2309 the expression beginning with the function @code{concat}. The value
2310 resulting from the evaluation of @code{(- fill-column 32)} is inserted
2311 in place of the @samp{%d}; and the value returned by the expression
2312 beginning with @code{concat} is inserted in place of the @samp{%s}.
2314 When your fill column is 70 and you evaluate the expression, the
2315 message @code{"He saw 38 red foxes leaping."} appears in your echo
2318 @node set & setq, Summary, Arguments, List Processing
2319 @comment node-name, next, previous, up
2320 @section Setting the Value of a Variable
2321 @cindex Variable, setting value
2322 @cindex Setting value of variable
2324 @cindex @samp{bind} defined
2325 There are several ways by which a variable can be given a value. One of
2326 the ways is to use either the function @code{set} or the function
2327 @code{setq}. Another way is to use @code{let} (@pxref{let}). (The
2328 jargon for this process is to @dfn{bind} a variable to a value.)
2330 The following sections not only describe how @code{set} and @code{setq}
2331 work but also illustrate how arguments are passed.
2339 @node Using set, Using setq, set & setq, set & setq
2340 @comment node-name, next, previous, up
2341 @subsection Using @code{set}
2344 To set the value of the symbol @code{flowers} to the list @code{'(rose
2345 violet daisy buttercup)}, evaluate the following expression by
2346 positioning the cursor after the expression and typing @kbd{C-x C-e}.
2349 (set 'flowers '(rose violet daisy buttercup))
2353 The list @code{(rose violet daisy buttercup)} will appear in the echo
2354 area. This is what is @emph{returned} by the @code{set} function. As a
2355 side effect, the symbol @code{flowers} is bound to the list; that is,
2356 the symbol @code{flowers}, which can be viewed as a variable, is given
2357 the list as its value. (This process, by the way, illustrates how a
2358 side effect to the Lisp interpreter, setting the value, can be the
2359 primary effect that we humans are interested in. This is because every
2360 Lisp function must return a value if it does not get an error, but it
2361 will only have a side effect if it is designed to have one.)
2363 After evaluating the @code{set} expression, you can evaluate the symbol
2364 @code{flowers} and it will return the value you just set. Here is the
2365 symbol. Place your cursor after it and type @kbd{C-x C-e}.
2372 When you evaluate @code{flowers}, the list
2373 @code{(rose violet daisy buttercup)} appears in the echo area.
2375 Incidentally, if you evaluate @code{'flowers}, the variable with a quote
2376 in front of it, what you will see in the echo area is the symbol itself,
2377 @code{flowers}. Here is the quoted symbol, so you can try this:
2383 Note also, that when you use @code{set}, you need to quote both
2384 arguments to @code{set}, unless you want them evaluated. Since we do
2385 not want either argument evaluated, neither the variable
2386 @code{flowers} nor the list @code{(rose violet daisy buttercup)}, both
2387 are quoted. (When you use @code{set} without quoting its first
2388 argument, the first argument is evaluated before anything else is
2389 done. If you did this and @code{flowers} did not have a value
2390 already, you would get an error message that the @samp{Symbol's value
2391 as variable is void}; on the other hand, if @code{flowers} did return
2392 a value after it was evaluated, the @code{set} would attempt to set
2393 the value that was returned. There are situations where this is the
2394 right thing for the function to do; but such situations are rare.)
2396 @node Using setq, Counting, Using set, set & setq
2397 @comment node-name, next, previous, up
2398 @subsection Using @code{setq}
2401 As a practical matter, you almost always quote the first argument to
2402 @code{set}. The combination of @code{set} and a quoted first argument
2403 is so common that it has its own name: the special form @code{setq}.
2404 This special form is just like @code{set} except that the first argument
2405 is quoted automatically, so you don't need to type the quote mark
2406 yourself. Also, as an added convenience, @code{setq} permits you to set
2407 several different variables to different values, all in one expression.
2409 To set the value of the variable @code{carnivores} to the list
2410 @code{'(lion tiger leopard)} using @code{setq}, the following expression
2414 (setq carnivores '(lion tiger leopard))
2418 This is exactly the same as using @code{set} except the first argument
2419 is automatically quoted by @code{setq}. (The @samp{q} in @code{setq}
2420 means @code{quote}.)
2423 With @code{set}, the expression would look like this:
2426 (set 'carnivores '(lion tiger leopard))
2429 Also, @code{setq} can be used to assign different values to
2430 different variables. The first argument is bound to the value
2431 of the second argument, the third argument is bound to the value of the
2432 fourth argument, and so on. For example, you could use the following to
2433 assign a list of trees to the symbol @code{trees} and a list of herbivores
2434 to the symbol @code{herbivores}:
2438 (setq trees '(pine fir oak maple)
2439 herbivores '(gazelle antelope zebra))
2444 (The expression could just as well have been on one line, but it might
2445 not have fit on a page; and humans find it easier to read nicely
2448 Although I have been using the term `assign', there is another way of
2449 thinking about the workings of @code{set} and @code{setq}; and that is to
2450 say that @code{set} and @code{setq} make the symbol @emph{point} to the
2451 list. This latter way of thinking is very common and in forthcoming
2452 chapters we shall come upon at least one symbol that has `pointer' as
2453 part of its name. The name is chosen because the symbol has a value,
2454 specifically a list, attached to it; or, expressed another way,
2455 the symbol is set to ``point'' to the list.
2457 @node Counting, , Using setq, set & setq
2458 @comment node-name, next, previous, up
2459 @subsection Counting
2462 Here is an example that shows how to use @code{setq} in a counter. You
2463 might use this to count how many times a part of your program repeats
2464 itself. First set a variable to zero; then add one to the number each
2465 time the program repeats itself. To do this, you need a variable that
2466 serves as a counter, and two expressions: an initial @code{setq}
2467 expression that sets the counter variable to zero; and a second
2468 @code{setq} expression that increments the counter each time it is
2473 (setq counter 0) ; @r{Let's call this the initializer.}
2475 (setq counter (+ counter 1)) ; @r{This is the incrementer.}
2477 counter ; @r{This is the counter.}
2482 (The text following the @samp{;} are comments. @xref{Change a
2483 defun, , Change a Function Definition}.)
2485 If you evaluate the first of these expressions, the initializer,
2486 @code{(setq counter 0)}, and then evaluate the third expression,
2487 @code{counter}, the number @code{0} will appear in the echo area. If
2488 you then evaluate the second expression, the incrementer, @code{(setq
2489 counter (+ counter 1))}, the counter will get the value 1. So if you
2490 again evaluate @code{counter}, the number @code{1} will appear in the
2491 echo area. Each time you evaluate the second expression, the value of
2492 the counter will be incremented.
2494 When you evaluate the incrementer, @code{(setq counter (+ counter 1))},
2495 the Lisp interpreter first evaluates the innermost list; this is the
2496 addition. In order to evaluate this list, it must evaluate the variable
2497 @code{counter} and the number @code{1}. When it evaluates the variable
2498 @code{counter}, it receives its current value. It passes this value and
2499 the number @code{1} to the @code{+} which adds them together. The sum
2500 is then returned as the value of the inner list and passed to the
2501 @code{setq} which sets the variable @code{counter} to this new value.
2502 Thus, the value of the variable, @code{counter}, is changed.
2504 @node Summary, Error Message Exercises, set & setq, List Processing
2505 @comment node-name, next, previous, up
2508 Learning Lisp is like climbing a hill in which the first part is the
2509 steepest. You have now climbed the most difficult part; what remains
2510 becomes easier as you progress onwards.
2518 Lisp programs are made up of expressions, which are lists or single atoms.
2521 Lists are made up of zero or more atoms or inner lists, separated by whitespace and
2522 surrounded by parentheses. A list can be empty.
2525 Atoms are multi-character symbols, like @code{forward-paragraph}, single
2526 character symbols like @code{+}, strings of characters between double
2527 quotation marks, or numbers.
2530 A number evaluates to itself.
2533 A string between double quotes also evaluates to itself.
2536 When you evaluate a symbol by itself, its value is returned.
2539 When you evaluate a list, the Lisp interpreter looks at the first symbol
2540 in the list and then at the function definition bound to that symbol.
2541 Then the instructions in the function definition are carried out.
2544 A single quotation mark,
2551 , tells the Lisp interpreter that it should
2552 return the following expression as written, and not evaluate it as it
2553 would if the quote were not there.
2556 Arguments are the information passed to a function. The arguments to a
2557 function are computed by evaluating the rest of the elements of the list
2558 of which the function is the first element.
2561 A function always returns a value when it is evaluated (unless it gets
2562 an error); in addition, it may also carry out some action called a
2563 ``side effect''. In many cases, a function's primary purpose is to
2564 create a side effect.
2567 @node Error Message Exercises, , Summary, List Processing
2568 @comment node-name, next, previous, up
2571 A few simple exercises:
2575 Generate an error message by evaluating an appropriate symbol that is
2576 not within parentheses.
2579 Generate an error message by evaluating an appropriate symbol that is
2580 between parentheses.
2583 Create a counter that increments by two rather than one.
2586 Write an expression that prints a message in the echo area when
2590 @node Practicing Evaluation, Writing Defuns, List Processing, Top
2591 @comment node-name, next, previous, up
2592 @chapter Practicing Evaluation
2593 @cindex Practicing evaluation
2594 @cindex Evaluation practice
2596 Before learning how to write a function definition in Emacs Lisp, it is
2597 useful to spend a little time evaluating various expressions that have
2598 already been written. These expressions will be lists with the
2599 functions as their first (and often only) element. Since some of the
2600 functions associated with buffers are both simple and interesting, we
2601 will start with those. In this section, we will evaluate a few of
2602 these. In another section, we will study the code of several other
2603 buffer-related functions, to see how they were written.
2609 * Switching Buffers::
2610 * Buffer Size & Locations::
2611 * Evaluation Exercise::
2614 @node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation
2616 @unnumberedsec How to Evaluate
2619 @i{Whenever you give an editing command} to Emacs Lisp, such as the
2620 command to move the cursor or to scroll the screen, @i{you are evaluating
2621 an expression,} the first element of which is a function. @i{This is
2624 @cindex @samp{interactive function} defined
2625 @cindex @samp{command} defined
2626 When you type keys, you cause the Lisp interpreter to evaluate an
2627 expression and that is how you get your results. Even typing plain text
2628 involves evaluating an Emacs Lisp function, in this case, one that uses
2629 @code{self-insert-command}, which simply inserts the character you
2630 typed. The functions you evaluate by typing keystrokes are called
2631 @dfn{interactive} functions, or @dfn{commands}; how you make a function
2632 interactive will be illustrated in the chapter on how to write function
2633 definitions. @xref{Interactive, , Making a Function Interactive}.
2635 In addition to typing keyboard commands, we have seen a second way to
2636 evaluate an expression: by positioning the cursor after a list and
2637 typing @kbd{C-x C-e}. This is what we will do in the rest of this
2638 section. There are other ways to evaluate an expression as well; these
2639 will be described as we come to them.
2641 Besides being used for practicing evaluation, the functions shown in the
2642 next few sections are important in their own right. A study of these
2643 functions makes clear the distinction between buffers and files, how to
2644 switch to a buffer, and how to determine a location within it.
2646 @node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation
2647 @comment node-name, next, previous, up
2648 @section Buffer Names
2650 @findex buffer-file-name
2652 The two functions, @code{buffer-name} and @code{buffer-file-name}, show
2653 the difference between a file and a buffer. When you evaluate the
2654 following expression, @code{(buffer-name)}, the name of the buffer
2655 appears in the echo area. When you evaluate @code{(buffer-file-name)},
2656 the name of the file to which the buffer refers appears in the echo
2657 area. Usually, the name returned by @code{(buffer-name)} is the same as
2658 the name of the file to which it refers, and the name returned by
2659 @code{(buffer-file-name)} is the full path-name of the file.
2661 A file and a buffer are two different entities. A file is information
2662 recorded permanently in the computer (unless you delete it). A buffer,
2663 on the other hand, is information inside of Emacs that will vanish at
2664 the end of the editing session (or when you kill the buffer). Usually,
2665 a buffer contains information that you have copied from a file; we say
2666 the buffer is @dfn{visiting} that file. This copy is what you work on
2667 and modify. Changes to the buffer do not change the file, until you
2668 save the buffer. When you save the buffer, the buffer is copied to the file
2669 and is thus saved permanently.
2672 If you are reading this in Info inside of GNU Emacs, you can evaluate
2673 each of the following expressions by positioning the cursor after it and
2674 typing @kbd{C-x C-e}.
2685 When I do this in Info, the value returned by evaluating
2686 @code{(buffer-name)} is @file{"*info*"}, and the value returned by
2687 evaluating @code{(buffer-file-name)} is @file{nil}.
2689 On the other hand, while I am writing this Introduction, the value
2690 returned by evaluating @code{(buffer-name)} is
2691 @file{"introduction.texinfo"}, and the value returned by evaluating
2692 @code{(buffer-file-name)} is
2693 @file{"/gnu/work/intro/introduction.texinfo"}.
2695 @cindex @code{nil}, history of word
2696 The former is the name of the buffer and the latter is the name of the
2697 file. In Info, the buffer name is @file{"*info*"}. Info does not
2698 point to any file, so the result of evaluating
2699 @code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is
2700 from the Latin word for `nothing'; in this case, it means that the
2701 buffer is not associated with any file. (In Lisp, @code{nil} is also
2702 used to mean `false' and is a synonym for the empty list, @code{()}.)
2704 When I am writing, the name of my buffer is
2705 @file{"introduction.texinfo"}. The name of the file to which it
2706 points is @file{"/gnu/work/intro/introduction.texinfo"}.
2708 (In the expressions, the parentheses tell the Lisp interpreter to
2709 treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as
2710 functions; without the parentheses, the interpreter would attempt to
2711 evaluate the symbols as variables. @xref{Variables}.)
2713 In spite of the distinction between files and buffers, you will often
2714 find that people refer to a file when they mean a buffer and vice-verse.
2715 Indeed, most people say, ``I am editing a file,'' rather than saying,
2716 ``I am editing a buffer which I will soon save to a file.'' It is
2717 almost always clear from context what people mean. When dealing with
2718 computer programs, however, it is important to keep the distinction in mind,
2719 since the computer is not as smart as a person.
2721 @cindex Buffer, history of word
2722 The word `buffer', by the way, comes from the meaning of the word as a
2723 cushion that deadens the force of a collision. In early computers, a
2724 buffer cushioned the interaction between files and the computer's
2725 central processing unit. The drums or tapes that held a file and the
2726 central processing unit were pieces of equipment that were very
2727 different from each other, working at their own speeds, in spurts. The
2728 buffer made it possible for them to work together effectively.
2729 Eventually, the buffer grew from being an intermediary, a temporary
2730 holding place, to being the place where work is done. This
2731 transformation is rather like that of a small seaport that grew into a
2732 great city: once it was merely the place where cargo was warehoused
2733 temporarily before being loaded onto ships; then it became a business
2734 and cultural center in its own right.
2736 Not all buffers are associated with files. For example, a
2737 @file{*scratch*} buffer does not visit any file. Similarly, a
2738 @file{*Help*} buffer is not associated with any file.
2740 In the old days, when you lacked a @file{~/.emacs} file and started an
2741 Emacs session by typing the command @code{emacs} alone, without naming
2742 any files, Emacs started with the @file{*scratch*} buffer visible.
2743 Nowadays, you will see a splash screen. You can follow one of the
2744 commands suggested on the splash screen, visit a file, or press the
2745 spacebar to reach the @file{*scratch*} buffer.
2747 If you switch to the @file{*scratch*} buffer, type
2748 @code{(buffer-name)}, position the cursor after it, and then type
2749 @kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"}
2750 will be returned and will appear in the echo area. @code{"*scratch*"}
2751 is the name of the buffer. When you type @code{(buffer-file-name)} in
2752 the @file{*scratch*} buffer and evaluate that, @code{nil} will appear
2753 in the echo area, just as it does when you evaluate
2754 @code{(buffer-file-name)} in Info.
2756 Incidentally, if you are in the @file{*scratch*} buffer and want the
2757 value returned by an expression to appear in the @file{*scratch*}
2758 buffer itself rather than in the echo area, type @kbd{C-u C-x C-e}
2759 instead of @kbd{C-x C-e}. This causes the value returned to appear
2760 after the expression. The buffer will look like this:
2763 (buffer-name)"*scratch*"
2767 You cannot do this in Info since Info is read-only and it will not allow
2768 you to change the contents of the buffer. But you can do this in any
2769 buffer you can edit; and when you write code or documentation (such as
2770 this book), this feature is very useful.
2772 @node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation
2773 @comment node-name, next, previous, up
2774 @section Getting Buffers
2775 @findex current-buffer
2776 @findex other-buffer
2777 @cindex Getting a buffer
2779 The @code{buffer-name} function returns the @emph{name} of the buffer;
2780 to get the buffer @emph{itself}, a different function is needed: the
2781 @code{current-buffer} function. If you use this function in code, what
2782 you get is the buffer itself.
2784 A name and the object or entity to which the name refers are different
2785 from each other. You are not your name. You are a person to whom
2786 others refer by name. If you ask to speak to George and someone hands you
2787 a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r},
2788 @samp{g}, and @samp{e} written on it, you might be amused, but you would
2789 not be satisfied. You do not want to speak to the name, but to the
2790 person to whom the name refers. A buffer is similar: the name of the
2791 scratch buffer is @file{*scratch*}, but the name is not the buffer. To
2792 get a buffer itself, you need to use a function such as
2793 @code{current-buffer}.
2795 However, there is a slight complication: if you evaluate
2796 @code{current-buffer} in an expression on its own, as we will do here,
2797 what you see is a printed representation of the name of the buffer
2798 without the contents of the buffer. Emacs works this way for two
2799 reasons: the buffer may be thousands of lines long---too long to be
2800 conveniently displayed; and, another buffer may have the same contents
2801 but a different name, and it is important to distinguish between them.
2804 Here is an expression containing the function:
2811 If you evaluate this expression in Info in Emacs in the usual way,
2812 @file{#<buffer *info*>} will appear in the echo area. The special
2813 format indicates that the buffer itself is being returned, rather than
2816 Incidentally, while you can type a number or symbol into a program, you
2817 cannot do that with the printed representation of a buffer: the only way
2818 to get a buffer itself is with a function such as @code{current-buffer}.
2820 A related function is @code{other-buffer}. This returns the most
2821 recently selected buffer other than the one you are in currently, not
2822 a printed representation of its name. If you have recently switched
2823 back and forth from the @file{*scratch*} buffer, @code{other-buffer}
2824 will return that buffer.
2827 You can see this by evaluating the expression:
2834 You should see @file{#<buffer *scratch*>} appear in the echo area, or
2835 the name of whatever other buffer you switched back from most
2836 recently@footnote{Actually, by default, if the buffer from which you
2837 just switched is visible to you in another window, @code{other-buffer}
2838 will choose the most recent buffer that you cannot see; this is a
2839 subtlety that I often forget.}.
2841 @node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation
2842 @comment node-name, next, previous, up
2843 @section Switching Buffers
2844 @findex switch-to-buffer
2846 @cindex Switching to a buffer
2848 The @code{other-buffer} function actually provides a buffer when it is
2849 used as an argument to a function that requires one. We can see this
2850 by using @code{other-buffer} and @code{switch-to-buffer} to switch to a
2853 But first, a brief introduction to the @code{switch-to-buffer}
2854 function. When you switched back and forth from Info to the
2855 @file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most
2856 likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or
2857 rather, to save typing, you probably only typed @kbd{RET} if the
2858 default buffer was @file{*scratch*}, or if it was different, then you
2859 typed just part of the name, such as @code{*sc}, pressed your
2860 @kbd{TAB} key to cause it to expand to the full name, and then typed
2861 your @kbd{RET} key.} when prompted in the minibuffer for the name of
2862 the buffer to which you wanted to switch. The keystrokes, @kbd{C-x
2863 b}, cause the Lisp interpreter to evaluate the interactive function
2864 @code{switch-to-buffer}. As we said before, this is how Emacs works:
2865 different keystrokes call or run different functions. For example,
2866 @kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls
2867 @code{forward-sentence}, and so on.
2869 By writing @code{switch-to-buffer} in an expression, and giving it a
2870 buffer to switch to, we can switch buffers just the way @kbd{C-x b}
2874 Here is the Lisp expression:
2877 (switch-to-buffer (other-buffer))
2881 The symbol @code{switch-to-buffer} is the first element of the list,
2882 so the Lisp interpreter will treat it as a function and carry out the
2883 instructions that are attached to it. But before doing that, the
2884 interpreter will note that @code{other-buffer} is inside parentheses
2885 and work on that symbol first. @code{other-buffer} is the first (and
2886 in this case, the only) element of this list, so the Lisp interpreter
2887 calls or runs the function. It returns another buffer. Next, the
2888 interpreter runs @code{switch-to-buffer}, passing to it, as an
2889 argument, the other buffer, which is what Emacs will switch to. If
2890 you are reading this in Info, try this now. Evaluate the expression.
2891 (To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this
2892 expression will move you to your most recent other buffer that you
2893 cannot see. If you really want to go to your most recently selected
2894 buffer, even if you can still see it, you need to evaluate the
2895 following more complex expression:
2898 (switch-to-buffer (other-buffer (current-buffer) t))
2902 In this case, the first argument to @code{other-buffer} tells it which
2903 buffer to skip---the current one---and the second argument tells
2904 @code{other-buffer} it is OK to switch to a visible buffer.
2905 In regular use, @code{switch-to-buffer} takes you to an invisible
2906 window since you would most likely use @kbd{C-x o} (@code{other-window})
2907 to go to another visible buffer.}
2909 In the programming examples in later sections of this document, you will
2910 see the function @code{set-buffer} more often than
2911 @code{switch-to-buffer}. This is because of a difference between
2912 computer programs and humans: humans have eyes and expect to see the
2913 buffer on which they are working on their computer terminals. This is
2914 so obvious, it almost goes without saying. However, programs do not
2915 have eyes. When a computer program works on a buffer, that buffer does
2916 not need to be visible on the screen.
2918 @code{switch-to-buffer} is designed for humans and does two different
2919 things: it switches the buffer to which Emacs' attention is directed; and
2920 it switches the buffer displayed in the window to the new buffer.
2921 @code{set-buffer}, on the other hand, does only one thing: it switches
2922 the attention of the computer program to a different buffer. The buffer
2923 on the screen remains unchanged (of course, normally nothing happens
2924 there until the command finishes running).
2926 @cindex @samp{call} defined
2927 Also, we have just introduced another jargon term, the word @dfn{call}.
2928 When you evaluate a list in which the first symbol is a function, you
2929 are calling that function. The use of the term comes from the notion of
2930 the function as an entity that can do something for you if you `call'
2931 it---just as a plumber is an entity who can fix a leak if you call him
2934 @node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation
2935 @comment node-name, next, previous, up
2936 @section Buffer Size and the Location of Point
2937 @cindex Size of buffer
2939 @cindex Point location
2940 @cindex Location of point
2942 Finally, let's look at several rather simple functions,
2943 @code{buffer-size}, @code{point}, @code{point-min}, and
2944 @code{point-max}. These give information about the size of a buffer and
2945 the location of point within it.
2947 The function @code{buffer-size} tells you the size of the current
2948 buffer; that is, the function returns a count of the number of
2949 characters in the buffer.
2956 You can evaluate this in the usual way, by positioning the
2957 cursor after the expression and typing @kbd{C-x C-e}.
2959 @cindex @samp{point} defined
2960 In Emacs, the current position of the cursor is called @dfn{point}.
2961 The expression @code{(point)} returns a number that tells you where the
2962 cursor is located as a count of the number of characters from the
2963 beginning of the buffer up to point.
2966 You can see the character count for point in this buffer by evaluating
2967 the following expression in the usual way:
2974 As I write this, the value of @code{point} is 65724. The @code{point}
2975 function is frequently used in some of the examples later in this
2979 The value of point depends, of course, on its location within the
2980 buffer. If you evaluate point in this spot, the number will be larger:
2987 For me, the value of point in this location is 66043, which means that
2988 there are 319 characters (including spaces) between the two
2989 expressions. (Doubtless, you will see different numbers, since I will
2990 have edited this since I first evaluated point.)
2992 @cindex @samp{narrowing} defined
2993 The function @code{point-min} is somewhat similar to @code{point}, but
2994 it returns the value of the minimum permissible value of point in the
2995 current buffer. This is the number 1 unless @dfn{narrowing} is in
2996 effect. (Narrowing is a mechanism whereby you can restrict yourself,
2997 or a program, to operations on just a part of a buffer.
2998 @xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the
2999 function @code{point-max} returns the value of the maximum permissible
3000 value of point in the current buffer.
3002 @node Evaluation Exercise, , Buffer Size & Locations, Practicing Evaluation
3005 Find a file with which you are working and move towards its middle.
3006 Find its buffer name, file name, length, and your position in the file.
3008 @node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top
3009 @comment node-name, next, previous, up
3010 @chapter How To Write Function Definitions
3011 @cindex Definition writing
3012 @cindex Function definition writing
3013 @cindex Writing a function definition
3015 When the Lisp interpreter evaluates a list, it looks to see whether the
3016 first symbol on the list has a function definition attached to it; or,
3017 put another way, whether the symbol points to a function definition. If
3018 it does, the computer carries out the instructions in the definition. A
3019 symbol that has a function definition is called, simply, a function
3020 (although, properly speaking, the definition is the function and the
3021 symbol refers to it.)
3024 * Primitive Functions::
3028 * Interactive Options::
3029 * Permanent Installation::
3033 * Truth & Falsehood::
3039 @node Primitive Functions, defun, Writing Defuns, Writing Defuns
3041 @unnumberedsec An Aside about Primitive Functions
3043 @cindex Primitive functions
3044 @cindex Functions, primitive
3046 @cindex C language primitives
3047 @cindex Primitives written in C
3048 All functions are defined in terms of other functions, except for a few
3049 @dfn{primitive} functions that are written in the C programming
3050 language. When you write functions' definitions, you will write them in
3051 Emacs Lisp and use other functions as your building blocks. Some of the
3052 functions you will use will themselves be written in Emacs Lisp (perhaps
3053 by you) and some will be primitives written in C. The primitive
3054 functions are used exactly like those written in Emacs Lisp and behave
3055 like them. They are written in C so we can easily run GNU Emacs on any
3056 computer that has sufficient power and can run C.
3058 Let me re-emphasize this: when you write code in Emacs Lisp, you do not
3059 distinguish between the use of functions written in C and the use of
3060 functions written in Emacs Lisp. The difference is irrelevant. I
3061 mention the distinction only because it is interesting to know. Indeed,
3062 unless you investigate, you won't know whether an already-written
3063 function is written in Emacs Lisp or C.
3065 @node defun, Install, Primitive Functions, Writing Defuns
3066 @comment node-name, next, previous, up
3067 @section The @code{defun} Special Form
3069 @cindex Special form of @code{defun}
3071 @cindex @samp{function definition} defined
3072 In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to
3073 it that tells the computer what to do when the function is called.
3074 This code is called the @dfn{function definition} and is created by
3075 evaluating a Lisp expression that starts with the symbol @code{defun}
3076 (which is an abbreviation for @emph{define function}). Because
3077 @code{defun} does not evaluate its arguments in the usual way, it is
3078 called a @dfn{special form}.
3080 In subsequent sections, we will look at function definitions from the
3081 Emacs source code, such as @code{mark-whole-buffer}. In this section,
3082 we will describe a simple function definition so you can see how it
3083 looks. This function definition uses arithmetic because it makes for a
3084 simple example. Some people dislike examples using arithmetic; however,
3085 if you are such a person, do not despair. Hardly any of the code we
3086 will study in the remainder of this introduction involves arithmetic or
3087 mathematics. The examples mostly involve text in one way or another.
3089 A function definition has up to five parts following the word
3094 The name of the symbol to which the function definition should be
3098 A list of the arguments that will be passed to the function. If no
3099 arguments will be passed to the function, this is an empty list,
3103 Documentation describing the function. (Technically optional, but
3104 strongly recommended.)
3107 Optionally, an expression to make the function interactive so you can
3108 use it by typing @kbd{M-x} and then the name of the function; or by
3109 typing an appropriate key or keychord.
3111 @cindex @samp{body} defined
3113 The code that instructs the computer what to do: the @dfn{body} of the
3114 function definition.
3117 It is helpful to think of the five parts of a function definition as
3118 being organized in a template, with slots for each part:
3122 (defun @var{function-name} (@var{arguments}@dots{})
3123 "@var{optional-documentation}@dots{}"
3124 (interactive @var{argument-passing-info}) ; @r{optional}
3129 As an example, here is the code for a function that multiplies its
3130 argument by 7. (This example is not interactive. @xref{Interactive,
3131 , Making a Function Interactive}, for that information.)
3135 (defun multiply-by-seven (number)
3136 "Multiply NUMBER by seven."
3141 This definition begins with a parenthesis and the symbol @code{defun},
3142 followed by the name of the function.
3144 @cindex @samp{argument list} defined
3145 The name of the function is followed by a list that contains the
3146 arguments that will be passed to the function. This list is called
3147 the @dfn{argument list}. In this example, the list has only one
3148 element, the symbol, @code{number}. When the function is used, the
3149 symbol will be bound to the value that is used as the argument to the
3152 Instead of choosing the word @code{number} for the name of the argument,
3153 I could have picked any other name. For example, I could have chosen
3154 the word @code{multiplicand}. I picked the word `number' because it
3155 tells what kind of value is intended for this slot; but I could just as
3156 well have chosen the word `multiplicand' to indicate the role that the
3157 value placed in this slot will play in the workings of the function. I
3158 could have called it @code{foogle}, but that would have been a bad
3159 choice because it would not tell humans what it means. The choice of
3160 name is up to the programmer and should be chosen to make the meaning of
3163 Indeed, you can choose any name you wish for a symbol in an argument
3164 list, even the name of a symbol used in some other function: the name
3165 you use in an argument list is private to that particular definition.
3166 In that definition, the name refers to a different entity than any use
3167 of the same name outside the function definition. Suppose you have a
3168 nick-name `Shorty' in your family; when your family members refer to
3169 `Shorty', they mean you. But outside your family, in a movie, for
3170 example, the name `Shorty' refers to someone else. Because a name in an
3171 argument list is private to the function definition, you can change the
3172 value of such a symbol inside the body of a function without changing
3173 its value outside the function. The effect is similar to that produced
3174 by a @code{let} expression. (@xref{let, , @code{let}}.)
3177 Note also that we discuss the word `number' in two different ways: as a
3178 symbol that appears in the code, and as the name of something that will
3179 be replaced by a something else during the evaluation of the function.
3180 In the first case, @code{number} is a symbol, not a number; it happens
3181 that within the function, it is a variable who value is the number in
3182 question, but our primary interest in it is as a symbol. On the other
3183 hand, when we are talking about the function, our interest is that we
3184 will substitute a number for the word @var{number}. To keep this
3185 distinction clear, we use different typography for the two
3186 circumstances. When we talk about this function, or about how it works,
3187 we refer to this number by writing @var{number}. In the function
3188 itself, we refer to it by writing @code{number}.
3191 The argument list is followed by the documentation string that
3192 describes the function. This is what you see when you type
3193 @w{@kbd{C-h f}} and the name of a function. Incidentally, when you
3194 write a documentation string like this, you should make the first line
3195 a complete sentence since some commands, such as @code{apropos}, print
3196 only the first line of a multi-line documentation string. Also, you
3197 should not indent the second line of a documentation string, if you
3198 have one, because that looks odd when you use @kbd{C-h f}
3199 (@code{describe-function}). The documentation string is optional, but
3200 it is so useful, it should be included in almost every function you
3203 @findex * @r{(multiplication)}
3204 The third line of the example consists of the body of the function
3205 definition. (Most functions' definitions, of course, are longer than
3206 this.) In this function, the body is the list, @code{(* 7 number)}, which
3207 says to multiply the value of @var{number} by 7. (In Emacs Lisp,
3208 @code{*} is the function for multiplication, just as @code{+} is the
3209 function for addition.)
3211 When you use the @code{multiply-by-seven} function, the argument
3212 @code{number} evaluates to the actual number you want used. Here is an
3213 example that shows how @code{multiply-by-seven} is used; but don't try
3214 to evaluate this yet!
3217 (multiply-by-seven 3)
3221 The symbol @code{number}, specified in the function definition in the
3222 next section, is given or ``bound to'' the value 3 in the actual use of
3223 the function. Note that although @code{number} was inside parentheses
3224 in the function definition, the argument passed to the
3225 @code{multiply-by-seven} function is not in parentheses. The
3226 parentheses are written in the function definition so the computer can
3227 figure out where the argument list ends and the rest of the function
3230 If you evaluate this example, you are likely to get an error message.
3231 (Go ahead, try it!) This is because we have written the function
3232 definition, but not yet told the computer about the definition---we have
3233 not yet installed (or `loaded') the function definition in Emacs.
3234 Installing a function is the process that tells the Lisp interpreter the
3235 definition of the function. Installation is described in the next
3238 @node Install, Interactive, defun, Writing Defuns
3239 @comment node-name, next, previous, up
3240 @section Install a Function Definition
3241 @cindex Install a Function Definition
3242 @cindex Definition installation
3243 @cindex Function definition installation
3245 If you are reading this inside of Info in Emacs, you can try out the
3246 @code{multiply-by-seven} function by first evaluating the function
3247 definition and then evaluating @code{(multiply-by-seven 3)}. A copy of
3248 the function definition follows. Place the cursor after the last
3249 parenthesis of the function definition and type @kbd{C-x C-e}. When you
3250 do this, @code{multiply-by-seven} will appear in the echo area. (What
3251 this means is that when a function definition is evaluated, the value it
3252 returns is the name of the defined function.) At the same time, this
3253 action installs the function definition.
3257 (defun multiply-by-seven (number)
3258 "Multiply NUMBER by seven."
3264 By evaluating this @code{defun}, you have just installed
3265 @code{multiply-by-seven} in Emacs. The function is now just as much a
3266 part of Emacs as @code{forward-word} or any other editing function you
3267 use. (@code{multiply-by-seven} will stay installed until you quit
3268 Emacs. To reload code automatically whenever you start Emacs, see
3269 @ref{Permanent Installation, , Installing Code Permanently}.)
3272 * Effect of installation::
3276 @node Effect of installation, Change a defun, Install, Install
3278 @unnumberedsubsec The effect of installation
3281 You can see the effect of installing @code{multiply-by-seven} by
3282 evaluating the following sample. Place the cursor after the following
3283 expression and type @kbd{C-x C-e}. The number 21 will appear in the
3287 (multiply-by-seven 3)
3290 If you wish, you can read the documentation for the function by typing
3291 @kbd{C-h f} (@code{describe-function}) and then the name of the
3292 function, @code{multiply-by-seven}. When you do this, a
3293 @file{*Help*} window will appear on your screen that says:
3297 multiply-by-seven is a Lisp function.
3298 (multiply-by-seven NUMBER)
3300 Multiply NUMBER by seven.
3305 (To return to a single window on your screen, type @kbd{C-x 1}.)
3307 @node Change a defun, , Effect of installation, Install
3308 @comment node-name, next, previous, up
3309 @subsection Change a Function Definition
3310 @cindex Changing a function definition
3311 @cindex Function definition, how to change
3312 @cindex Definition, how to change
3314 If you want to change the code in @code{multiply-by-seven}, just rewrite
3315 it. To install the new version in place of the old one, evaluate the
3316 function definition again. This is how you modify code in Emacs. It is
3319 As an example, you can change the @code{multiply-by-seven} function to
3320 add the number to itself seven times instead of multiplying the number
3321 by seven. It produces the same answer, but by a different path. At
3322 the same time, we will add a comment to the code; a comment is text
3323 that the Lisp interpreter ignores, but that a human reader may find
3324 useful or enlightening. The comment is that this is the ``second
3329 (defun multiply-by-seven (number) ; @r{Second version.}
3330 "Multiply NUMBER by seven."
3331 (+ number number number number number number number))
3335 @cindex Comments in Lisp code
3336 The comment follows a semicolon, @samp{;}. In Lisp, everything on a
3337 line that follows a semicolon is a comment. The end of the line is the
3338 end of the comment. To stretch a comment over two or more lines, begin
3339 each line with a semicolon.
3341 @xref{Beginning a .emacs File, , Beginning a @file{.emacs}
3342 File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp
3343 Reference Manual}, for more about comments.
3345 You can install this version of the @code{multiply-by-seven} function by
3346 evaluating it in the same way you evaluated the first function: place
3347 the cursor after the last parenthesis and type @kbd{C-x C-e}.
3349 In summary, this is how you write code in Emacs Lisp: you write a
3350 function; install it; test it; and then make fixes or enhancements and
3353 @node Interactive, Interactive Options, Install, Writing Defuns
3354 @comment node-name, next, previous, up
3355 @section Make a Function Interactive
3356 @cindex Interactive functions
3359 You make a function interactive by placing a list that begins with
3360 the special form @code{interactive} immediately after the
3361 documentation. A user can invoke an interactive function by typing
3362 @kbd{M-x} and then the name of the function; or by typing the keys to
3363 which it is bound, for example, by typing @kbd{C-n} for
3364 @code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}.
3366 Interestingly, when you call an interactive function interactively,
3367 the value returned is not automatically displayed in the echo area.
3368 This is because you often call an interactive function for its side
3369 effects, such as moving forward by a word or line, and not for the
3370 value returned. If the returned value were displayed in the echo area
3371 each time you typed a key, it would be very distracting.
3374 * Interactive multiply-by-seven::
3375 * multiply-by-seven in detail::
3378 @node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive
3380 @unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview
3383 Both the use of the special form @code{interactive} and one way to
3384 display a value in the echo area can be illustrated by creating an
3385 interactive version of @code{multiply-by-seven}.
3392 (defun multiply-by-seven (number) ; @r{Interactive version.}
3393 "Multiply NUMBER by seven."
3395 (message "The result is %d" (* 7 number)))
3400 You can install this code by placing your cursor after it and typing
3401 @kbd{C-x C-e}. The name of the function will appear in your echo area.
3402 Then, you can use this code by typing @kbd{C-u} and a number and then
3403 typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase
3404 @samp{The result is @dots{}} followed by the product will appear in the
3407 Speaking more generally, you invoke a function like this in either of two
3412 By typing a prefix argument that contains the number to be passed, and
3413 then typing @kbd{M-x} and the name of the function, as with
3414 @kbd{C-u 3 M-x forward-sentence}; or,
3417 By typing whatever key or keychord the function is bound to, as with
3422 Both the examples just mentioned work identically to move point forward
3423 three sentences. (Since @code{multiply-by-seven} is not bound to a key,
3424 it could not be used as an example of key binding.)
3426 (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command
3429 A prefix argument is passed to an interactive function by typing the
3430 @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by
3431 typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you
3432 type @kbd{C-u} without a number, it defaults to 4).
3434 @node multiply-by-seven in detail, , Interactive multiply-by-seven, Interactive
3435 @comment node-name, next, previous, up
3436 @subsection An Interactive @code{multiply-by-seven}
3438 Let's look at the use of the special form @code{interactive} and then at
3439 the function @code{message} in the interactive version of
3440 @code{multiply-by-seven}. You will recall that the function definition
3445 (defun multiply-by-seven (number) ; @r{Interactive version.}
3446 "Multiply NUMBER by seven."
3448 (message "The result is %d" (* 7 number)))
3452 In this function, the expression, @code{(interactive "p")}, is a list of
3453 two elements. The @code{"p"} tells Emacs to pass the prefix argument to
3454 the function and use its value for the argument of the function.
3457 The argument will be a number. This means that the symbol
3458 @code{number} will be bound to a number in the line:
3461 (message "The result is %d" (* 7 number))
3466 For example, if your prefix argument is 5, the Lisp interpreter will
3467 evaluate the line as if it were:
3470 (message "The result is %d" (* 7 5))
3474 (If you are reading this in GNU Emacs, you can evaluate this expression
3475 yourself.) First, the interpreter will evaluate the inner list, which
3476 is @code{(* 7 5)}. This returns a value of 35. Next, it
3477 will evaluate the outer list, passing the values of the second and
3478 subsequent elements of the list to the function @code{message}.
3480 As we have seen, @code{message} is an Emacs Lisp function especially
3481 designed for sending a one line message to a user. (@xref{message, ,
3482 The @code{message} function}.) In summary, the @code{message}
3483 function prints its first argument in the echo area as is, except for
3484 occurrences of @samp{%d} or @samp{%s} (and various other %-sequences
3485 which we have not mentioned). When it sees a control sequence, the
3486 function looks to the second or subsequent arguments and prints the
3487 value of the argument in the location in the string where the control
3488 sequence is located.
3490 In the interactive @code{multiply-by-seven} function, the control string
3491 is @samp{%d}, which requires a number, and the value returned by
3492 evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35
3493 is printed in place of the @samp{%d} and the message is @samp{The result
3496 (Note that when you call the function @code{multiply-by-seven}, the
3497 message is printed without quotes, but when you call @code{message}, the
3498 text is printed in double quotes. This is because the value returned by
3499 @code{message} is what appears in the echo area when you evaluate an
3500 expression whose first element is @code{message}; but when embedded in a
3501 function, @code{message} prints the text as a side effect without
3504 @node Interactive Options, Permanent Installation, Interactive, Writing Defuns
3505 @comment node-name, next, previous, up
3506 @section Different Options for @code{interactive}
3507 @cindex Options for @code{interactive}
3508 @cindex Interactive options
3510 In the example, @code{multiply-by-seven} used @code{"p"} as the
3511 argument to @code{interactive}. This argument told Emacs to interpret
3512 your typing either @kbd{C-u} followed by a number or @key{META}
3513 followed by a number as a command to pass that number to the function
3514 as its argument. Emacs has more than twenty characters predefined for
3515 use with @code{interactive}. In almost every case, one of these
3516 options will enable you to pass the right information interactively to
3517 a function. (@xref{Interactive Codes, , Code Characters for
3518 @code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.)
3521 Consider the function @code{zap-to-char}. Its interactive expression
3525 (interactive "p\ncZap to char: ")
3528 The first part of the argument to @code{interactive} is @samp{p}, with
3529 which you are already familiar. This argument tells Emacs to
3530 interpret a `prefix', as a number to be passed to the function. You
3531 can specify a prefix either by typing @kbd{C-u} followed by a number
3532 or by typing @key{META} followed by a number. The prefix is the
3533 number of specified characters. Thus, if your prefix is three and the
3534 specified character is @samp{x}, then you will delete all the text up
3535 to and including the third next @samp{x}. If you do not set a prefix,
3536 then you delete all the text up to and including the specified
3537 character, but no more.
3539 The @samp{c} tells the function the name of the character to which to delete.
3541 More formally, a function with two or more arguments can have
3542 information passed to each argument by adding parts to the string that
3543 follows @code{interactive}. When you do this, the information is
3544 passed to each argument in the same order it is specified in the
3545 @code{interactive} list. In the string, each part is separated from
3546 the next part by a @samp{\n}, which is a newline. For example, you
3547 can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }.
3548 This causes Emacs to pass the value of the prefix argument (if there
3549 is one) and the character.
3551 In this case, the function definition looks like the following, where
3552 @code{arg} and @code{char} are the symbols to which @code{interactive}
3553 binds the prefix argument and the specified character:
3557 (defun @var{name-of-function} (arg char)
3558 "@var{documentation}@dots{}"
3559 (interactive "p\ncZap to char: ")
3560 @var{body-of-function}@dots{})
3565 (The space after the colon in the prompt makes it look better when you
3566 are prompted. @xref{copy-to-buffer, , The Definition of
3567 @code{copy-to-buffer}}, for an example.)
3569 When a function does not take arguments, @code{interactive} does not
3570 require any. Such a function contains the simple expression
3571 @code{(interactive)}. The @code{mark-whole-buffer} function is like
3574 Alternatively, if the special letter-codes are not right for your
3575 application, you can pass your own arguments to @code{interactive} as
3578 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}},
3579 for an example. @xref{Using Interactive, , Using @code{Interactive},
3580 elisp, The GNU Emacs Lisp Reference Manual}, for a more complete
3581 explanation about this technique.
3583 @node Permanent Installation, let, Interactive Options, Writing Defuns
3584 @comment node-name, next, previous, up
3585 @section Install Code Permanently
3586 @cindex Install code permanently
3587 @cindex Permanent code installation
3588 @cindex Code installation
3590 When you install a function definition by evaluating it, it will stay
3591 installed until you quit Emacs. The next time you start a new session
3592 of Emacs, the function will not be installed unless you evaluate the
3593 function definition again.
3595 At some point, you may want to have code installed automatically
3596 whenever you start a new session of Emacs. There are several ways of
3601 If you have code that is just for yourself, you can put the code for the
3602 function definition in your @file{.emacs} initialization file. When you
3603 start Emacs, your @file{.emacs} file is automatically evaluated and all
3604 the function definitions within it are installed.
3605 @xref{Emacs Initialization, , Your @file{.emacs} File}.
3608 Alternatively, you can put the function definitions that you want
3609 installed in one or more files of their own and use the @code{load}
3610 function to cause Emacs to evaluate and thereby install each of the
3611 functions in the files.
3612 @xref{Loading Files, , Loading Files}.
3615 Thirdly, if you have code that your whole site will use, it is usual
3616 to put it in a file called @file{site-init.el} that is loaded when
3617 Emacs is built. This makes the code available to everyone who uses
3618 your machine. (See the @file{INSTALL} file that is part of the Emacs
3622 Finally, if you have code that everyone who uses Emacs may want, you
3623 can post it on a computer network or send a copy to the Free Software
3624 Foundation. (When you do this, please license the code and its
3625 documentation under a license that permits other people to run, copy,
3626 study, modify, and redistribute the code and which protects you from
3627 having your work taken from you.) If you send a copy of your code to
3628 the Free Software Foundation, and properly protect yourself and
3629 others, it may be included in the next release of Emacs. In large
3630 part, this is how Emacs has grown over the past years, by donations.
3632 @node let, if, Permanent Installation, Writing Defuns
3633 @comment node-name, next, previous, up
3637 The @code{let} expression is a special form in Lisp that you will need
3638 to use in most function definitions.
3640 @code{let} is used to attach or bind a symbol to a value in such a way
3641 that the Lisp interpreter will not confuse the variable with a
3642 variable of the same name that is not part of the function.
3644 To understand why the @code{let} special form is necessary, consider
3645 the situation in which you own a home that you generally refer to as
3646 `the house', as in the sentence, ``The house needs painting.'' If you
3647 are visiting a friend and your host refers to `the house', he is
3648 likely to be referring to @emph{his} house, not yours, that is, to a
3651 If your friend is referring to his house and you think he is referring
3652 to your house, you may be in for some confusion. The same thing could
3653 happen in Lisp if a variable that is used inside of one function has
3654 the same name as a variable that is used inside of another function,
3655 and the two are not intended to refer to the same value. The
3656 @code{let} special form prevents this kind of confusion.
3659 * Prevent confusion::
3660 * Parts of let Expression::
3661 * Sample let Expression::
3662 * Uninitialized let Variables::
3665 @node Prevent confusion, Parts of let Expression, let, let
3667 @unnumberedsubsec @code{let} Prevents Confusion
3670 @cindex @samp{local variable} defined
3671 @cindex @samp{variable, local}, defined
3672 The @code{let} special form prevents confusion. @code{let} creates a
3673 name for a @dfn{local variable} that overshadows any use of the same
3674 name outside the @code{let} expression. This is like understanding
3675 that whenever your host refers to `the house', he means his house, not
3676 yours. (Symbols used in argument lists work the same way.
3677 @xref{defun, , The @code{defun} Special Form}.)
3679 Local variables created by a @code{let} expression retain their value
3680 @emph{only} within the @code{let} expression itself (and within
3681 expressions called within the @code{let} expression); the local
3682 variables have no effect outside the @code{let} expression.
3684 Another way to think about @code{let} is that it is like a @code{setq}
3685 that is temporary and local. The values set by @code{let} are
3686 automatically undone when the @code{let} is finished. The setting
3687 only affects expressions that are inside the bounds of the @code{let}
3688 expression. In computer science jargon, we would say ``the binding of
3689 a symbol is visible only in functions called in the @code{let} form;
3690 in Emacs Lisp, scoping is dynamic, not lexical.''
3692 @code{let} can create more than one variable at once. Also,
3693 @code{let} gives each variable it creates an initial value, either a
3694 value specified by you, or @code{nil}. (In the jargon, this is called
3695 `binding the variable to the value'.) After @code{let} has created
3696 and bound the variables, it executes the code in the body of the
3697 @code{let}, and returns the value of the last expression in the body,
3698 as the value of the whole @code{let} expression. (`Execute' is a jargon
3699 term that means to evaluate a list; it comes from the use of the word
3700 meaning `to give practical effect to' (@cite{Oxford English
3701 Dictionary}). Since you evaluate an expression to perform an action,
3702 `execute' has evolved as a synonym to `evaluate'.)
3704 @node Parts of let Expression, Sample let Expression, Prevent confusion, let
3705 @comment node-name, next, previous, up
3706 @subsection The Parts of a @code{let} Expression
3707 @cindex @code{let} expression, parts of
3708 @cindex Parts of @code{let} expression
3710 @cindex @samp{varlist} defined
3711 A @code{let} expression is a list of three parts. The first part is
3712 the symbol @code{let}. The second part is a list, called a
3713 @dfn{varlist}, each element of which is either a symbol by itself or a
3714 two-element list, the first element of which is a symbol. The third
3715 part of the @code{let} expression is the body of the @code{let}. The
3716 body usually consists of one or more lists.
3719 A template for a @code{let} expression looks like this:
3722 (let @var{varlist} @var{body}@dots{})
3726 The symbols in the varlist are the variables that are given initial
3727 values by the @code{let} special form. Symbols by themselves are given
3728 the initial value of @code{nil}; and each symbol that is the first
3729 element of a two-element list is bound to the value that is returned
3730 when the Lisp interpreter evaluates the second element.
3732 Thus, a varlist might look like this: @code{(thread (needles 3))}. In
3733 this case, in a @code{let} expression, Emacs binds the symbol
3734 @code{thread} to an initial value of @code{nil}, and binds the symbol
3735 @code{needles} to an initial value of 3.
3737 When you write a @code{let} expression, what you do is put the
3738 appropriate expressions in the slots of the @code{let} expression
3741 If the varlist is composed of two-element lists, as is often the case,
3742 the template for the @code{let} expression looks like this:
3746 (let ((@var{variable} @var{value})
3747 (@var{variable} @var{value})
3753 @node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let
3754 @comment node-name, next, previous, up
3755 @subsection Sample @code{let} Expression
3756 @cindex Sample @code{let} expression
3757 @cindex @code{let} expression sample
3759 The following expression creates and gives initial values
3760 to the two variables @code{zebra} and @code{tiger}. The body of the
3761 @code{let} expression is a list which calls the @code{message} function.
3765 (let ((zebra 'stripes)
3767 (message "One kind of animal has %s and another is %s."
3772 Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}.
3774 The two variables are @code{zebra} and @code{tiger}. Each variable is
3775 the first element of a two-element list and each value is the second
3776 element of its two-element list. In the varlist, Emacs binds the
3777 variable @code{zebra} to the value @code{stripes}@footnote{According
3778 to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras
3779 become impossibly dangerous as they grow older'' but the claim here is
3780 that they do not become fierce like a tiger. (1997, W. W. Norton and
3781 Co., ISBN 0-393-03894-2, page 171)}, and binds the
3782 variable @code{tiger} to the value @code{fierce}. In this example,
3783 both values are symbols preceded by a quote. The values could just as
3784 well have been another list or a string. The body of the @code{let}
3785 follows after the list holding the variables. In this example, the
3786 body is a list that uses the @code{message} function to print a string
3790 You may evaluate the example in the usual fashion, by placing the
3791 cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do
3792 this, the following will appear in the echo area:
3795 "One kind of animal has stripes and another is fierce."
3798 As we have seen before, the @code{message} function prints its first
3799 argument, except for @samp{%s}. In this example, the value of the variable
3800 @code{zebra} is printed at the location of the first @samp{%s} and the
3801 value of the variable @code{tiger} is printed at the location of the
3804 @node Uninitialized let Variables, , Sample let Expression, let
3805 @comment node-name, next, previous, up
3806 @subsection Uninitialized Variables in a @code{let} Statement
3807 @cindex Uninitialized @code{let} variables
3808 @cindex @code{let} variables uninitialized
3810 If you do not bind the variables in a @code{let} statement to specific
3811 initial values, they will automatically be bound to an initial value of
3812 @code{nil}, as in the following expression:
3821 "Here are %d variables with %s, %s, and %s value."
3822 birch pine fir oak))
3827 Here, the varlist is @code{((birch 3) pine fir (oak 'some))}.
3830 If you evaluate this expression in the usual way, the following will
3831 appear in your echo area:
3834 "Here are 3 variables with nil, nil, and some value."
3838 In this example, Emacs binds the symbol @code{birch} to the number 3,
3839 binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds
3840 the symbol @code{oak} to the value @code{some}.
3842 Note that in the first part of the @code{let}, the variables @code{pine}
3843 and @code{fir} stand alone as atoms that are not surrounded by
3844 parentheses; this is because they are being bound to @code{nil}, the
3845 empty list. But @code{oak} is bound to @code{some} and so is a part of
3846 the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the
3847 number 3 and so is in a list with that number. (Since a number
3848 evaluates to itself, the number does not need to be quoted. Also, the
3849 number is printed in the message using a @samp{%d} rather than a
3850 @samp{%s}.) The four variables as a group are put into a list to
3851 delimit them from the body of the @code{let}.
3853 @node if, else, let, Writing Defuns
3854 @comment node-name, next, previous, up
3855 @section The @code{if} Special Form
3857 @cindex Conditional with @code{if}
3859 A third special form, in addition to @code{defun} and @code{let}, is the
3860 conditional @code{if}. This form is used to instruct the computer to
3861 make decisions. You can write function definitions without using
3862 @code{if}, but it is used often enough, and is important enough, to be
3863 included here. It is used, for example, in the code for the
3864 function @code{beginning-of-buffer}.
3866 The basic idea behind an @code{if}, is that ``@emph{if} a test is true,
3867 @emph{then} an expression is evaluated.'' If the test is not true, the
3868 expression is not evaluated. For example, you might make a decision
3869 such as, ``if it is warm and sunny, then go to the beach!''
3872 * if in more detail::
3873 * type-of-animal in detail::
3876 @node if in more detail, type-of-animal in detail, if, if
3878 @unnumberedsubsec @code{if} in more detail
3881 @cindex @samp{if-part} defined
3882 @cindex @samp{then-part} defined
3883 An @code{if} expression written in Lisp does not use the word `then';
3884 the test and the action are the second and third elements of the list
3885 whose first element is @code{if}. Nonetheless, the test part of an
3886 @code{if} expression is often called the @dfn{if-part} and the second
3887 argument is often called the @dfn{then-part}.
3889 Also, when an @code{if} expression is written, the true-or-false-test
3890 is usually written on the same line as the symbol @code{if}, but the
3891 action to carry out if the test is true, the ``then-part'', is written
3892 on the second and subsequent lines. This makes the @code{if}
3893 expression easier to read.
3897 (if @var{true-or-false-test}
3898 @var{action-to-carry-out-if-test-is-true})
3903 The true-or-false-test will be an expression that
3904 is evaluated by the Lisp interpreter.
3906 Here is an example that you can evaluate in the usual manner. The test
3907 is whether the number 5 is greater than the number 4. Since it is, the
3908 message @samp{5 is greater than 4!} will be printed.
3912 (if (> 5 4) ; @r{if-part}
3913 (message "5 is greater than 4!")) ; @r{then-part}
3918 (The function @code{>} tests whether its first argument is greater than
3919 its second argument and returns true if it is.)
3920 @findex > (greater than)
3922 Of course, in actual use, the test in an @code{if} expression will not
3923 be fixed for all time as it is by the expression @code{(> 5 4)}.
3924 Instead, at least one of the variables used in the test will be bound to
3925 a value that is not known ahead of time. (If the value were known ahead
3926 of time, we would not need to run the test!)
3928 For example, the value may be bound to an argument of a function
3929 definition. In the following function definition, the character of the
3930 animal is a value that is passed to the function. If the value bound to
3931 @code{characteristic} is @code{fierce}, then the message, @samp{It's a
3932 tiger!} will be printed; otherwise, @code{nil} will be returned.
3936 (defun type-of-animal (characteristic)
3937 "Print message in echo area depending on CHARACTERISTIC.
3938 If the CHARACTERISTIC is the symbol `fierce',
3939 then warn of a tiger."
3940 (if (equal characteristic 'fierce)
3941 (message "It's a tiger!")))
3947 If you are reading this inside of GNU Emacs, you can evaluate the
3948 function definition in the usual way to install it in Emacs, and then you
3949 can evaluate the following two expressions to see the results:
3953 (type-of-animal 'fierce)
3955 (type-of-animal 'zebra)
3960 @c Following sentences rewritten to prevent overfull hbox.
3962 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
3963 following message printed in the echo area: @code{"It's a tiger!"}; and
3964 when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil}
3965 printed in the echo area.
3967 @node type-of-animal in detail, , if in more detail, if
3968 @comment node-name, next, previous, up
3969 @subsection The @code{type-of-animal} Function in Detail
3971 Let's look at the @code{type-of-animal} function in detail.
3973 The function definition for @code{type-of-animal} was written by filling
3974 the slots of two templates, one for a function definition as a whole, and
3975 a second for an @code{if} expression.
3978 The template for every function that is not interactive is:
3982 (defun @var{name-of-function} (@var{argument-list})
3983 "@var{documentation}@dots{}"
3989 The parts of the function that match this template look like this:
3993 (defun type-of-animal (characteristic)
3994 "Print message in echo area depending on CHARACTERISTIC.
3995 If the CHARACTERISTIC is the symbol `fierce',
3996 then warn of a tiger."
3997 @var{body: the} @code{if} @var{expression})
4001 The name of function is @code{type-of-animal}; it is passed the value
4002 of one argument. The argument list is followed by a multi-line
4003 documentation string. The documentation string is included in the
4004 example because it is a good habit to write documentation string for
4005 every function definition. The body of the function definition
4006 consists of the @code{if} expression.
4009 The template for an @code{if} expression looks like this:
4013 (if @var{true-or-false-test}
4014 @var{action-to-carry-out-if-the-test-returns-true})
4019 In the @code{type-of-animal} function, the code for the @code{if}
4024 (if (equal characteristic 'fierce)
4025 (message "It's a tiger!")))
4030 Here, the true-or-false-test is the expression:
4033 (equal characteristic 'fierce)
4037 In Lisp, @code{equal} is a function that determines whether its first
4038 argument is equal to its second argument. The second argument is the
4039 quoted symbol @code{'fierce} and the first argument is the value of the
4040 symbol @code{characteristic}---in other words, the argument passed to
4043 In the first exercise of @code{type-of-animal}, the argument
4044 @code{fierce} is passed to @code{type-of-animal}. Since @code{fierce}
4045 is equal to @code{fierce}, the expression, @code{(equal characteristic
4046 'fierce)}, returns a value of true. When this happens, the @code{if}
4047 evaluates the second argument or then-part of the @code{if}:
4048 @code{(message "It's tiger!")}.
4050 On the other hand, in the second exercise of @code{type-of-animal}, the
4051 argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra}
4052 is not equal to @code{fierce}, so the then-part is not evaluated and
4053 @code{nil} is returned by the @code{if} expression.
4055 @node else, Truth & Falsehood, if, Writing Defuns
4056 @comment node-name, next, previous, up
4057 @section If--then--else Expressions
4060 An @code{if} expression may have an optional third argument, called
4061 the @dfn{else-part}, for the case when the true-or-false-test returns
4062 false. When this happens, the second argument or then-part of the
4063 overall @code{if} expression is @emph{not} evaluated, but the third or
4064 else-part @emph{is} evaluated. You might think of this as the cloudy
4065 day alternative for the decision ``if it is warm and sunny, then go to
4066 the beach, else read a book!''.
4068 The word ``else'' is not written in the Lisp code; the else-part of an
4069 @code{if} expression comes after the then-part. In the written Lisp, the
4070 else-part is usually written to start on a line of its own and is
4071 indented less than the then-part:
4075 (if @var{true-or-false-test}
4076 @var{action-to-carry-out-if-the-test-returns-true}
4077 @var{action-to-carry-out-if-the-test-returns-false})
4081 For example, the following @code{if} expression prints the message @samp{4
4082 is not greater than 5!} when you evaluate it in the usual way:
4086 (if (> 4 5) ; @r{if-part}
4087 (message "5 is greater than 4!") ; @r{then-part}
4088 (message "4 is not greater than 5!")) ; @r{else-part}
4093 Note that the different levels of indentation make it easy to
4094 distinguish the then-part from the else-part. (GNU Emacs has several
4095 commands that automatically indent @code{if} expressions correctly.
4096 @xref{Typing Lists, , GNU Emacs Helps You Type Lists}.)
4098 We can extend the @code{type-of-animal} function to include an
4099 else-part by simply incorporating an additional part to the @code{if}
4103 You can see the consequences of doing this if you evaluate the following
4104 version of the @code{type-of-animal} function definition to install it
4105 and then evaluate the two subsequent expressions to pass different
4106 arguments to the function.
4110 (defun type-of-animal (characteristic) ; @r{Second version.}
4111 "Print message in echo area depending on CHARACTERISTIC.
4112 If the CHARACTERISTIC is the symbol `fierce',
4113 then warn of a tiger;
4114 else say it's not fierce."
4115 (if (equal characteristic 'fierce)
4116 (message "It's a tiger!")
4117 (message "It's not fierce!")))
4124 (type-of-animal 'fierce)
4126 (type-of-animal 'zebra)
4131 @c Following sentence rewritten to prevent overfull hbox.
4133 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
4134 following message printed in the echo area: @code{"It's a tiger!"}; but
4135 when you evaluate @code{(type-of-animal 'zebra)}, you will see
4136 @code{"It's not fierce!"}.
4138 (Of course, if the @var{characteristic} were @code{ferocious}, the
4139 message @code{"It's not fierce!"} would be printed; and it would be
4140 misleading! When you write code, you need to take into account the
4141 possibility that some such argument will be tested by the @code{if}
4142 and write your program accordingly.)
4144 @node Truth & Falsehood, save-excursion, else, Writing Defuns
4145 @comment node-name, next, previous, up
4146 @section Truth and Falsehood in Emacs Lisp
4147 @cindex Truth and falsehood in Emacs Lisp
4148 @cindex Falsehood and truth in Emacs Lisp
4151 There is an important aspect to the truth test in an @code{if}
4152 expression. So far, we have spoken of `true' and `false' as values of
4153 predicates as if they were new kinds of Emacs Lisp objects. In fact,
4154 `false' is just our old friend @code{nil}. Anything else---anything
4157 The expression that tests for truth is interpreted as @dfn{true}
4158 if the result of evaluating it is a value that is not @code{nil}. In
4159 other words, the result of the test is considered true if the value
4160 returned is a number such as 47, a string such as @code{"hello"}, or a
4161 symbol (other than @code{nil}) such as @code{flowers}, or a list (so
4162 long as it is not empty), or even a buffer!
4168 @node nil explained, , Truth & Falsehood, Truth & Falsehood
4170 @unnumberedsubsec An explanation of @code{nil}
4173 Before illustrating a test for truth, we need an explanation of @code{nil}.
4175 In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the
4176 empty list. Second, it means false and is the value returned when a
4177 true-or-false-test tests false. @code{nil} can be written as an empty
4178 list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is
4179 concerned, @code{()} and @code{nil} are the same. Humans, however, tend
4180 to use @code{nil} for false and @code{()} for the empty list.
4182 In Emacs Lisp, any value that is not @code{nil}---is not the empty
4183 list---is considered true. This means that if an evaluation returns
4184 something that is not an empty list, an @code{if} expression will test
4185 true. For example, if a number is put in the slot for the test, it
4186 will be evaluated and will return itself, since that is what numbers
4187 do when evaluated. In this conditional, the @code{if} expression will
4188 test true. The expression tests false only when @code{nil}, an empty
4189 list, is returned by evaluating the expression.
4191 You can see this by evaluating the two expressions in the following examples.
4193 In the first example, the number 4 is evaluated as the test in the
4194 @code{if} expression and returns itself; consequently, the then-part
4195 of the expression is evaluated and returned: @samp{true} appears in
4196 the echo area. In the second example, the @code{nil} indicates false;
4197 consequently, the else-part of the expression is evaluated and
4198 returned: @samp{false} appears in the echo area.
4215 Incidentally, if some other useful value is not available for a test that
4216 returns true, then the Lisp interpreter will return the symbol @code{t}
4217 for true. For example, the expression @code{(> 5 4)} returns @code{t}
4218 when evaluated, as you can see by evaluating it in the usual way:
4226 On the other hand, this function returns @code{nil} if the test is false.
4232 @node save-excursion, Review, Truth & Falsehood, Writing Defuns
4233 @comment node-name, next, previous, up
4234 @section @code{save-excursion}
4235 @findex save-excursion
4236 @cindex Region, what it is
4237 @cindex Preserving point, mark, and buffer
4238 @cindex Point, mark, buffer preservation
4242 The @code{save-excursion} function is the fourth and final special form
4243 that we will discuss in this chapter.
4245 In Emacs Lisp programs used for editing, the @code{save-excursion}
4246 function is very common. It saves the location of point and mark,
4247 executes the body of the function, and then restores point and mark to
4248 their previous positions if their locations were changed. Its primary
4249 purpose is to keep the user from being surprised and disturbed by
4250 unexpected movement of point or mark.
4254 * Template for save-excursion::
4257 @node Point and mark, Template for save-excursion, save-excursion, save-excursion
4259 @unnumberedsubsec Point and Mark
4262 Before discussing @code{save-excursion}, however, it may be useful
4263 first to review what point and mark are in GNU Emacs. @dfn{Point} is
4264 the current location of the cursor. Wherever the cursor
4265 is, that is point. More precisely, on terminals where the cursor
4266 appears to be on top of a character, point is immediately before the
4267 character. In Emacs Lisp, point is an integer. The first character in
4268 a buffer is number one, the second is number two, and so on. The
4269 function @code{point} returns the current position of the cursor as a
4270 number. Each buffer has its own value for point.
4272 The @dfn{mark} is another position in the buffer; its value can be set
4273 with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If
4274 a mark has been set, you can use the command @kbd{C-x C-x}
4275 (@code{exchange-point-and-mark}) to cause the cursor to jump to the mark
4276 and set the mark to be the previous position of point. In addition, if
4277 you set another mark, the position of the previous mark is saved in the
4278 mark ring. Many mark positions can be saved this way. You can jump the
4279 cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more
4282 The part of the buffer between point and mark is called @dfn{the
4283 region}. Numerous commands work on the region, including
4284 @code{center-region}, @code{count-lines-region}, @code{kill-region}, and
4285 @code{print-region}.
4287 The @code{save-excursion} special form saves the locations of point and
4288 mark and restores those positions after the code within the body of the
4289 special form is evaluated by the Lisp interpreter. Thus, if point were
4290 in the beginning of a piece of text and some code moved point to the end
4291 of the buffer, the @code{save-excursion} would put point back to where
4292 it was before, after the expressions in the body of the function were
4295 In Emacs, a function frequently moves point as part of its internal
4296 workings even though a user would not expect this. For example,
4297 @code{count-lines-region} moves point. To prevent the user from being
4298 bothered by jumps that are both unexpected and (from the user's point of
4299 view) unnecessary, @code{save-excursion} is often used to keep point and
4300 mark in the location expected by the user. The use of
4301 @code{save-excursion} is good housekeeping.
4303 To make sure the house stays clean, @code{save-excursion} restores the
4304 values of point and mark even if something goes wrong in the code inside
4305 of it (or, to be more precise and to use the proper jargon, ``in case of
4306 abnormal exit''). This feature is very helpful.
4308 In addition to recording the values of point and mark,
4309 @code{save-excursion} keeps track of the current buffer, and restores
4310 it, too. This means you can write code that will change the buffer and
4311 have @code{save-excursion} switch you back to the original buffer.
4312 This is how @code{save-excursion} is used in @code{append-to-buffer}.
4313 (@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
4315 @node Template for save-excursion, , Point and mark, save-excursion
4316 @comment node-name, next, previous, up
4317 @subsection Template for a @code{save-excursion} Expression
4320 The template for code using @code{save-excursion} is simple:
4330 The body of the function is one or more expressions that will be
4331 evaluated in sequence by the Lisp interpreter. If there is more than
4332 one expression in the body, the value of the last one will be returned
4333 as the value of the @code{save-excursion} function. The other
4334 expressions in the body are evaluated only for their side effects; and
4335 @code{save-excursion} itself is used only for its side effect (which
4336 is restoring the positions of point and mark).
4339 In more detail, the template for a @code{save-excursion} expression
4345 @var{first-expression-in-body}
4346 @var{second-expression-in-body}
4347 @var{third-expression-in-body}
4349 @var{last-expression-in-body})
4354 An expression, of course, may be a symbol on its own or a list.
4356 In Emacs Lisp code, a @code{save-excursion} expression often occurs
4357 within the body of a @code{let} expression. It looks like this:
4367 @node Review, defun Exercises, save-excursion, Writing Defuns
4368 @comment node-name, next, previous, up
4371 In the last few chapters we have introduced a fair number of functions
4372 and special forms. Here they are described in brief, along with a few
4373 similar functions that have not been mentioned yet.
4376 @item eval-last-sexp
4377 Evaluate the last symbolic expression before the current location of
4378 point. The value is printed in the echo area unless the function is
4379 invoked with an argument; in that case, the output is printed in the
4380 current buffer. This command is normally bound to @kbd{C-x C-e}.
4383 Define function. This special form has up to five parts: the name,
4384 a template for the arguments that will be passed to the function,
4385 documentation, an optional interactive declaration, and the body of the
4389 For example, in an early version of Emacs, the function definition was
4390 as follows. (It is slightly more complex now that it seeks the first
4391 non-whitespace character rather than the first visible character.)
4395 (defun back-to-indentation ()
4396 "Move point to first visible character on line."
4398 (beginning-of-line 1)
4399 (skip-chars-forward " \t"))
4406 (defun backward-to-indentation (&optional arg)
4407 "Move backward ARG lines and position at first nonblank character."
4409 (forward-line (- (or arg 1)))
4410 (skip-chars-forward " \t"))
4412 (defun back-to-indentation ()
4413 "Move point to the first non-whitespace character on this line."
4415 (beginning-of-line 1)
4416 (skip-syntax-forward " " (line-end-position))
4417 ;; Move back over chars that have whitespace syntax but have the p flag.
4418 (backward-prefix-chars))
4422 Declare to the interpreter that the function can be used
4423 interactively. This special form may be followed by a string with one
4424 or more parts that pass the information to the arguments of the
4425 function, in sequence. These parts may also tell the interpreter to
4426 prompt for information. Parts of the string are separated by
4427 newlines, @samp{\n}.
4430 Common code characters are:
4434 The name of an existing buffer.
4437 The name of an existing file.
4440 The numeric prefix argument. (Note that this `p' is lower case.)
4443 Point and the mark, as two numeric arguments, smallest first. This
4444 is the only code letter that specifies two successive arguments
4448 @xref{Interactive Codes, , Code Characters for @samp{interactive},
4449 elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of
4453 Declare that a list of variables is for use within the body of the
4454 @code{let} and give them an initial value, either @code{nil} or a
4455 specified value; then evaluate the rest of the expressions in the body
4456 of the @code{let} and return the value of the last one. Inside the
4457 body of the @code{let}, the Lisp interpreter does not see the values of
4458 the variables of the same names that are bound outside of the
4466 (let ((foo (buffer-name))
4467 (bar (buffer-size)))
4469 "This buffer is %s and has %d characters."
4474 @item save-excursion
4475 Record the values of point and mark and the current buffer before
4476 evaluating the body of this special form. Restore the values of point
4477 and mark and buffer afterward.
4484 (message "We are %d characters into this buffer."
4487 (goto-char (point-min)) (point))))
4492 Evaluate the first argument to the function; if it is true, evaluate
4493 the second argument; else evaluate the third argument, if there is one.
4495 The @code{if} special form is called a @dfn{conditional}. There are
4496 other conditionals in Emacs Lisp, but @code{if} is perhaps the most
4505 (number-to-string 22)
4506 (substring (emacs-version) 10 12))
4507 (message "This is version 22 Emacs")
4508 (message "This is not version 22 Emacs"))
4514 Test whether two objects are the same. @code{equal} uses one meaning
4515 of the word `same' and @code{eq} uses another: @code{equal} returns
4516 true if the two objects have a similar structure and contents, such as
4517 two copies of the same book. On the other hand, @code{eq}, returns
4518 true if both arguments are actually the same object.
4527 The @code{<} function tests whether its first argument is smaller than
4528 its second argument. A corresponding function, @code{>}, tests whether
4529 the first argument is greater than the second. Likewise, @code{<=}
4530 tests whether the first argument is less than or equal to the second and
4531 @code{>=} tests whether the first argument is greater than or equal to
4532 the second. In all cases, both arguments must be numbers or markers
4533 (markers indicate positions in buffers).
4537 The @code{=} function tests whether two arguments, both numbers or
4544 The @code{string-lessp} function tests whether its first argument is
4545 smaller than the second argument. A shorter, alternative name for the
4546 same function (a @code{defalias}) is @code{string<}.
4548 The arguments to @code{string-lessp} must be strings or symbols; the
4549 ordering is lexicographic, so case is significant. The print names of
4550 symbols are used instead of the symbols themselves.
4552 @cindex @samp{empty string} defined
4553 An empty string, @samp{""}, a string with no characters in it, is
4554 smaller than any string of characters.
4556 @code{string-equal} provides the corresponding test for equality. Its
4557 shorter, alternative name is @code{string=}. There are no string test
4558 functions that correspond to @var{>}, @code{>=}, or @code{<=}.
4561 Print a message in the echo area. The first argument is a string that
4562 can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of
4563 arguments that follow the string. The argument used by @samp{%s} must
4564 be a string or a symbol; the argument used by @samp{%d} must be a
4565 number. The argument used by @samp{%c} must be an @sc{ascii} code
4566 number; it will be printed as the character with that @sc{ascii} code.
4567 (Various other %-sequences have not been mentioned.)
4571 The @code{setq} function sets the value of its first argument to the
4572 value of the second argument. The first argument is automatically
4573 quoted by @code{setq}. It does the same for succeeding pairs of
4574 arguments. Another function, @code{set}, takes only two arguments and
4575 evaluates both of them before setting the value returned by its first
4576 argument to the value returned by its second argument.
4579 Without an argument, return the name of the buffer, as a string.
4581 @itemx buffer-file-name
4582 Without an argument, return the name of the file the buffer is
4585 @item current-buffer
4586 Return the buffer in which Emacs is active; it may not be
4587 the buffer that is visible on the screen.
4590 Return the most recently selected buffer (other than the buffer passed
4591 to @code{other-buffer} as an argument and other than the current
4594 @item switch-to-buffer
4595 Select a buffer for Emacs to be active in and display it in the current
4596 window so users can look at it. Usually bound to @kbd{C-x b}.
4599 Switch Emacs' attention to a buffer on which programs will run. Don't
4600 alter what the window is showing.
4603 Return the number of characters in the current buffer.
4606 Return the value of the current position of the cursor, as an
4607 integer counting the number of characters from the beginning of the
4611 Return the minimum permissible value of point in
4612 the current buffer. This is 1, unless narrowing is in effect.
4615 Return the value of the maximum permissible value of point in the
4616 current buffer. This is the end of the buffer, unless narrowing is in
4621 @node defun Exercises, , Review, Writing Defuns
4626 Write a non-interactive function that doubles the value of its
4627 argument, a number. Make that function interactive.
4630 Write a function that tests whether the current value of
4631 @code{fill-column} is greater than the argument passed to the function,
4632 and if so, prints an appropriate message.
4635 @node Buffer Walk Through, More Complex, Writing Defuns, Top
4636 @comment node-name, next, previous, up
4637 @chapter A Few Buffer--Related Functions
4639 In this chapter we study in detail several of the functions used in GNU
4640 Emacs. This is called a ``walk-through''. These functions are used as
4641 examples of Lisp code, but are not imaginary examples; with the
4642 exception of the first, simplified function definition, these functions
4643 show the actual code used in GNU Emacs. You can learn a great deal from
4644 these definitions. The functions described here are all related to
4645 buffers. Later, we will study other functions.
4649 * simplified-beginning-of-buffer::
4650 * mark-whole-buffer::
4651 * append-to-buffer::
4652 * Buffer Related Review::
4653 * Buffer Exercises::
4656 @node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through
4657 @section Finding More Information
4659 @findex describe-function, @r{introduced}
4660 @cindex Find function documentation
4661 In this walk-through, I will describe each new function as we come to
4662 it, sometimes in detail and sometimes briefly. If you are interested,
4663 you can get the full documentation of any Emacs Lisp function at any
4664 time by typing @kbd{C-h f} and then the name of the function (and then
4665 @key{RET}). Similarly, you can get the full documentation for a
4666 variable by typing @kbd{C-h v} and then the name of the variable (and
4669 @cindex Find source of function
4670 @c In version 22, tells location both of C and of Emacs Lisp
4671 Also, @code{describe-function} will tell you the location of the
4672 function definition.
4674 Put point into the name of the file that contains the function and
4675 press the @key{RET} key. In this case, @key{RET} means
4676 @code{push-button} rather than `return' or `enter'. Emacs will take
4677 you directly to the function definition.
4682 If you move point over the file name and press
4683 the @key{RET} key, which in this case means @code{help-follow} rather
4684 than `return' or `enter', Emacs will take you directly to the function
4688 More generally, if you want to see a function in its original source
4689 file, you can use the @code{find-tags} function to jump to it.
4690 @code{find-tags} works with a wide variety of languages, not just
4691 Lisp, and C, and it works with non-programming text as well. For
4692 example, @code{find-tags} will jump to the various nodes in the
4693 Texinfo source file of this document.
4694 The @code{find-tags} function depends on `tags tables' that record
4695 the locations of the functions, variables, and other items to which
4696 @code{find-tags} jumps.
4698 To use the @code{find-tags} command, type @kbd{M-.} (i.e., press the
4699 period key while holding down the @key{META} key, or else type the
4700 @key{ESC} key and then type the period key), and then, at the prompt,
4701 type in the name of the function whose source code you want to see,
4702 such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will
4703 switch buffers and display the source code for the function on your
4704 screen. To switch back to your current buffer, type @kbd{C-x b
4705 @key{RET}}. (On some keyboards, the @key{META} key is labelled
4708 @c !!! 22.1.1 tags table location in this paragraph
4709 @cindex TAGS table, specifying
4711 Depending on how the initial default values of your copy of Emacs are
4712 set, you may also need to specify the location of your `tags table',
4713 which is a file called @file{TAGS}. For example, if you are
4714 interested in Emacs sources, the tags table you will most likely want,
4715 if it has already been created for you, will be in a subdirectory of
4716 the @file{/usr/local/share/emacs/} directory; thus you would use the
4717 @code{M-x visit-tags-table} command and specify a pathname such as
4718 @file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table
4719 has not already been created, you will have to create it yourself. It
4720 will in a file such as @file{/usr/local/src/emacs/src/TAGS}.
4723 To create a @file{TAGS} file in a specific directory, switch to that
4724 directory in Emacs using @kbd{M-x cd} command, or list the directory
4725 with @kbd{C-x d} (@code{dired}). Then run the compile command, with
4726 @w{@code{etags *.el}} as the command to execute:
4729 M-x compile RET etags *.el RET
4732 For more information, see @ref{etags, , Create Your Own @file{TAGS} File}.
4734 After you become more familiar with Emacs Lisp, you will find that you will
4735 frequently use @code{find-tags} to navigate your way around source code;
4736 and you will create your own @file{TAGS} tables.
4738 @cindex Library, as term for `file'
4739 Incidentally, the files that contain Lisp code are conventionally
4740 called @dfn{libraries}. The metaphor is derived from that of a
4741 specialized library, such as a law library or an engineering library,
4742 rather than a general library. Each library, or file, contains
4743 functions that relate to a particular topic or activity, such as
4744 @file{abbrev.el} for handling abbreviations and other typing
4745 shortcuts, and @file{help.el} for on-line help. (Sometimes several
4746 libraries provide code for a single activity, as the various
4747 @file{rmail@dots{}} files provide code for reading electronic mail.)
4748 In @cite{The GNU Emacs Manual}, you will see sentences such as ``The
4749 @kbd{C-h p} command lets you search the standard Emacs Lisp libraries
4750 by topic keywords.''
4752 @node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through
4753 @comment node-name, next, previous, up
4754 @section A Simplified @code{beginning-of-buffer} Definition
4755 @findex simplified-beginning-of-buffer
4757 The @code{beginning-of-buffer} command is a good function to start with
4758 since you are likely to be familiar with it and it is easy to
4759 understand. Used as an interactive command, @code{beginning-of-buffer}
4760 moves the cursor to the beginning of the buffer, leaving the mark at the
4761 previous position. It is generally bound to @kbd{M-<}.
4763 In this section, we will discuss a shortened version of the function
4764 that shows how it is most frequently used. This shortened function
4765 works as written, but it does not contain the code for a complex option.
4766 In another section, we will describe the entire function.
4767 (@xref{beginning-of-buffer, , Complete Definition of
4768 @code{beginning-of-buffer}}.)
4770 Before looking at the code, let's consider what the function
4771 definition has to contain: it must include an expression that makes
4772 the function interactive so it can be called by typing @kbd{M-x
4773 beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it
4774 must include code to leave a mark at the original position in the
4775 buffer; and it must include code to move the cursor to the beginning
4779 Here is the complete text of the shortened version of the function:
4783 (defun simplified-beginning-of-buffer ()
4784 "Move point to the beginning of the buffer;
4785 leave mark at previous position."
4788 (goto-char (point-min)))
4792 Like all function definitions, this definition has five parts following
4793 the special form @code{defun}:
4797 The name: in this example, @code{simplified-beginning-of-buffer}.
4800 A list of the arguments: in this example, an empty list, @code{()},
4803 The documentation string.
4806 The interactive expression.
4813 In this function definition, the argument list is empty; this means that
4814 this function does not require any arguments. (When we look at the
4815 definition for the complete function, we will see that it may be passed
4816 an optional argument.)
4818 The interactive expression tells Emacs that the function is intended to
4819 be used interactively. In this example, @code{interactive} does not have
4820 an argument because @code{simplified-beginning-of-buffer} does not
4824 The body of the function consists of the two lines:
4829 (goto-char (point-min))
4833 The first of these lines is the expression, @code{(push-mark)}. When
4834 this expression is evaluated by the Lisp interpreter, it sets a mark at
4835 the current position of the cursor, wherever that may be. The position
4836 of this mark is saved in the mark ring.
4838 The next line is @code{(goto-char (point-min))}. This expression
4839 jumps the cursor to the minimum point in the buffer, that is, to the
4840 beginning of the buffer (or to the beginning of the accessible portion
4841 of the buffer if it is narrowed. @xref{Narrowing & Widening, ,
4842 Narrowing and Widening}.)
4844 The @code{push-mark} command sets a mark at the place where the cursor
4845 was located before it was moved to the beginning of the buffer by the
4846 @code{(goto-char (point-min))} expression. Consequently, you can, if
4847 you wish, go back to where you were originally by typing @kbd{C-x C-x}.
4849 That is all there is to the function definition!
4851 @findex describe-function
4852 When you are reading code such as this and come upon an unfamiliar
4853 function, such as @code{goto-char}, you can find out what it does by
4854 using the @code{describe-function} command. To use this command, type
4855 @kbd{C-h f} and then type in the name of the function and press
4856 @key{RET}. The @code{describe-function} command will print the
4857 function's documentation string in a @file{*Help*} window. For
4858 example, the documentation for @code{goto-char} is:
4862 Set point to POSITION, a number or marker.
4863 Beginning of buffer is position (point-min), end is (point-max).
4868 The function's one argument is the desired position.
4871 (The prompt for @code{describe-function} will offer you the symbol
4872 under or preceding the cursor, so you can save typing by positioning
4873 the cursor right over or after the function and then typing @kbd{C-h f
4876 The @code{end-of-buffer} function definition is written in the same way as
4877 the @code{beginning-of-buffer} definition except that the body of the
4878 function contains the expression @code{(goto-char (point-max))} in place
4879 of @code{(goto-char (point-min))}.
4881 @node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through
4882 @comment node-name, next, previous, up
4883 @section The Definition of @code{mark-whole-buffer}
4884 @findex mark-whole-buffer
4886 The @code{mark-whole-buffer} function is no harder to understand than the
4887 @code{simplified-beginning-of-buffer} function. In this case, however,
4888 we will look at the complete function, not a shortened version.
4890 The @code{mark-whole-buffer} function is not as commonly used as the
4891 @code{beginning-of-buffer} function, but is useful nonetheless: it
4892 marks a whole buffer as a region by putting point at the beginning and
4893 a mark at the end of the buffer. It is generally bound to @kbd{C-x
4897 * mark-whole-buffer overview::
4898 * Body of mark-whole-buffer::
4901 @node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer
4903 @unnumberedsubsec An overview of @code{mark-whole-buffer}
4907 In GNU Emacs 22, the code for the complete function looks like this:
4911 (defun mark-whole-buffer ()
4912 "Put point at beginning and mark at end of buffer.
4913 You probably should not use this function in Lisp programs;
4914 it is usually a mistake for a Lisp function to use any subroutine
4915 that uses or sets the mark."
4918 (push-mark (point-max) nil t)
4919 (goto-char (point-min)))
4924 Like all other functions, the @code{mark-whole-buffer} function fits
4925 into the template for a function definition. The template looks like
4930 (defun @var{name-of-function} (@var{argument-list})
4931 "@var{documentation}@dots{}"
4932 (@var{interactive-expression}@dots{})
4937 Here is how the function works: the name of the function is
4938 @code{mark-whole-buffer}; it is followed by an empty argument list,
4939 @samp{()}, which means that the function does not require arguments.
4940 The documentation comes next.
4942 The next line is an @code{(interactive)} expression that tells Emacs
4943 that the function will be used interactively. These details are similar
4944 to the @code{simplified-beginning-of-buffer} function described in the
4948 @node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer
4949 @comment node-name, next, previous, up
4950 @subsection Body of @code{mark-whole-buffer}
4952 The body of the @code{mark-whole-buffer} function consists of three
4959 (push-mark (point-max) nil t)
4960 (goto-char (point-min))
4964 The first of these lines is the expression, @code{(push-mark (point))}.
4966 This line does exactly the same job as the first line of the body of
4967 the @code{simplified-beginning-of-buffer} function, which is written
4968 @code{(push-mark)}. In both cases, the Lisp interpreter sets a mark
4969 at the current position of the cursor.
4971 I don't know why the expression in @code{mark-whole-buffer} is written
4972 @code{(push-mark (point))} and the expression in
4973 @code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps
4974 whoever wrote the code did not know that the arguments for
4975 @code{push-mark} are optional and that if @code{push-mark} is not
4976 passed an argument, the function automatically sets mark at the
4977 location of point by default. Or perhaps the expression was written
4978 so as to parallel the structure of the next line. In any case, the
4979 line causes Emacs to determine the position of point and set a mark
4982 In earlier versions of GNU Emacs, the next line of
4983 @code{mark-whole-buffer} was @code{(push-mark (point-max))}. This
4984 expression sets a mark at the point in the buffer that has the highest
4985 number. This will be the end of the buffer (or, if the buffer is
4986 narrowed, the end of the accessible portion of the buffer.
4987 @xref{Narrowing & Widening, , Narrowing and Widening}, for more about
4988 narrowing.) After this mark has been set, the previous mark, the one
4989 set at point, is no longer set, but Emacs remembers its position, just
4990 as all other recent marks are always remembered. This means that you
4991 can, if you wish, go back to that position by typing @kbd{C-u
4995 In GNU Emacs 22, the @code{(point-max)} is slightly more complicated.
4999 (push-mark (point-max) nil t)
5003 The expression works nearly the same as before. It sets a mark at the
5004 highest numbered place in the buffer that it can. However, in this
5005 version, @code{push-mark} has two additional arguments. The second
5006 argument to @code{push-mark} is @code{nil}. This tells the function
5007 it @emph{should} display a message that says `Mark set' when it pushes
5008 the mark. The third argument is @code{t}. This tells
5009 @code{push-mark} to activate the mark when Transient Mark mode is
5010 turned on. Transient Mark mode highlights the currently active
5011 region. It is often turned off.
5013 Finally, the last line of the function is @code{(goto-char
5014 (point-min)))}. This is written exactly the same way as it is written
5015 in @code{beginning-of-buffer}. The expression moves the cursor to
5016 the minimum point in the buffer, that is, to the beginning of the buffer
5017 (or to the beginning of the accessible portion of the buffer). As a
5018 result of this, point is placed at the beginning of the buffer and mark
5019 is set at the end of the buffer. The whole buffer is, therefore, the
5022 @node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through
5023 @comment node-name, next, previous, up
5024 @section The Definition of @code{append-to-buffer}
5025 @findex append-to-buffer
5027 The @code{append-to-buffer} command is more complex than the
5028 @code{mark-whole-buffer} command. What it does is copy the region
5029 (that is, the part of the buffer between point and mark) from the
5030 current buffer to a specified buffer.
5033 * append-to-buffer overview::
5034 * append interactive::
5035 * append-to-buffer body::
5036 * append save-excursion::
5039 @node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer
5041 @unnumberedsubsec An Overview of @code{append-to-buffer}
5044 @findex insert-buffer-substring
5045 The @code{append-to-buffer} command uses the
5046 @code{insert-buffer-substring} function to copy the region.
5047 @code{insert-buffer-substring} is described by its name: it takes a
5048 string of characters from part of a buffer, a ``substring'', and
5049 inserts them into another buffer.
5051 Most of @code{append-to-buffer} is
5052 concerned with setting up the conditions for
5053 @code{insert-buffer-substring} to work: the code must specify both the
5054 buffer to which the text will go, the window it comes from and goes
5055 to, and the region that will be copied.
5058 Here is the complete text of the function:
5062 (defun append-to-buffer (buffer start end)
5063 "Append to specified buffer the text of the region.
5064 It is inserted into that buffer before its point.
5068 When calling from a program, give three arguments:
5069 BUFFER (or buffer name), START and END.
5070 START and END specify the portion of the current buffer to be copied."
5072 (list (read-buffer "Append to buffer: " (other-buffer
5073 (current-buffer) t))
5074 (region-beginning) (region-end)))
5077 (let ((oldbuf (current-buffer)))
5079 (let* ((append-to (get-buffer-create buffer))
5080 (windows (get-buffer-window-list append-to t t))
5082 (set-buffer append-to)
5083 (setq point (point))
5084 (barf-if-buffer-read-only)
5085 (insert-buffer-substring oldbuf start end)
5086 (dolist (window windows)
5087 (when (= (window-point window) point)
5088 (set-window-point window (point))))))))
5092 The function can be understood by looking at it as a series of
5093 filled-in templates.
5095 The outermost template is for the function definition. In this
5096 function, it looks like this (with several slots filled in):
5100 (defun append-to-buffer (buffer start end)
5101 "@var{documentation}@dots{}"
5102 (interactive @dots{})
5107 The first line of the function includes its name and three arguments.
5108 The arguments are the @code{buffer} to which the text will be copied, and
5109 the @code{start} and @code{end} of the region in the current buffer that
5112 The next part of the function is the documentation, which is clear and
5113 complete. As is conventional, the three arguments are written in
5114 upper case so you will notice them easily. Even better, they are
5115 described in the same order as in the argument list.
5117 Note that the documentation distinguishes between a buffer and its
5118 name. (The function can handle either.)
5120 @node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer
5121 @comment node-name, next, previous, up
5122 @subsection The @code{append-to-buffer} Interactive Expression
5124 Since the @code{append-to-buffer} function will be used interactively,
5125 the function must have an @code{interactive} expression. (For a
5126 review of @code{interactive}, see @ref{Interactive, , Making a
5127 Function Interactive}.) The expression reads as follows:
5133 "Append to buffer: "
5134 (other-buffer (current-buffer) t))
5141 This expression is not one with letters standing for parts, as
5142 described earlier. Instead, it starts a list with thee parts.
5144 The first part of the list is an expression to read the name of a
5145 buffer and return it as a string. That is @code{read-buffer}. The
5146 function requires a prompt as its first argument, @samp{"Append to
5147 buffer: "}. Its second argument tells the command what value to
5148 provide if you don't specify anything.
5150 In this case that second argument is an expression containing the
5151 function @code{other-buffer}, an exception, and a @samp{t}, standing
5154 The first argument to @code{other-buffer}, the exception, is yet
5155 another function, @code{current-buffer}. That is not going to be
5156 returned. The second argument is the symbol for true, @code{t}. that
5157 tells @code{other-buffer} that it may show visible buffers (except in
5158 this case, it will not show the current buffer, which makes sense).
5161 The expression looks like this:
5164 (other-buffer (current-buffer) t)
5167 The second and third arguments to the @code{list} expression are
5168 @code{(region-beginning)} and @code{(region-end)}. These two
5169 functions specify the beginning and end of the text to be appended.
5172 Originally, the command used the letters @samp{B} and @samp{r}.
5173 The whole @code{interactive} expression looked like this:
5176 (interactive "BAppend to buffer:@: \nr")
5180 But when that was done, the default value of the buffer switched to
5181 was invisible. That was not wanted.
5183 (The prompt was separated from the second argument with a newline,
5184 @samp{\n}. It was followed by an @samp{r} that told Emacs to bind the
5185 two arguments that follow the symbol @code{buffer} in the function's
5186 argument list (that is, @code{start} and @code{end}) to the values of
5187 point and mark. That argument worked fine.)
5189 @node append-to-buffer body, append save-excursion, append interactive, append-to-buffer
5190 @comment node-name, next, previous, up
5191 @subsection The Body of @code{append-to-buffer}
5194 in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el
5196 (defun append-to-buffer (buffer start end)
5197 "Append to specified buffer the text of the region.
5198 It is inserted into that buffer before its point.
5200 When calling from a program, give three arguments:
5201 BUFFER (or buffer name), START and END.
5202 START and END specify the portion of the current buffer to be copied."
5204 (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t))
5205 (region-beginning) (region-end)))
5206 (let ((oldbuf (current-buffer)))
5208 (let* ((append-to (get-buffer-create buffer))
5209 (windows (get-buffer-window-list append-to t t))
5211 (set-buffer append-to)
5212 (setq point (point))
5213 (barf-if-buffer-read-only)
5214 (insert-buffer-substring oldbuf start end)
5215 (dolist (window windows)
5216 (when (= (window-point window) point)
5217 (set-window-point window (point))))))))
5220 The body of the @code{append-to-buffer} function begins with @code{let}.
5222 As we have seen before (@pxref{let, , @code{let}}), the purpose of a
5223 @code{let} expression is to create and give initial values to one or
5224 more variables that will only be used within the body of the
5225 @code{let}. This means that such a variable will not be confused with
5226 any variable of the same name outside the @code{let} expression.
5228 We can see how the @code{let} expression fits into the function as a
5229 whole by showing a template for @code{append-to-buffer} with the
5230 @code{let} expression in outline:
5234 (defun append-to-buffer (buffer start end)
5235 "@var{documentation}@dots{}"
5236 (interactive @dots{})
5237 (let ((@var{variable} @var{value}))
5242 The @code{let} expression has three elements:
5246 The symbol @code{let};
5249 A varlist containing, in this case, a single two-element list,
5250 @code{(@var{variable} @var{value})};
5253 The body of the @code{let} expression.
5257 In the @code{append-to-buffer} function, the varlist looks like this:
5260 (oldbuf (current-buffer))
5264 In this part of the @code{let} expression, the one variable,
5265 @code{oldbuf}, is bound to the value returned by the
5266 @code{(current-buffer)} expression. The variable, @code{oldbuf}, is
5267 used to keep track of the buffer in which you are working and from
5268 which you will copy.
5270 The element or elements of a varlist are surrounded by a set of
5271 parentheses so the Lisp interpreter can distinguish the varlist from
5272 the body of the @code{let}. As a consequence, the two-element list
5273 within the varlist is surrounded by a circumscribing set of parentheses.
5274 The line looks like this:
5278 (let ((oldbuf (current-buffer)))
5284 The two parentheses before @code{oldbuf} might surprise you if you did
5285 not realize that the first parenthesis before @code{oldbuf} marks the
5286 boundary of the varlist and the second parenthesis marks the beginning
5287 of the two-element list, @code{(oldbuf (current-buffer))}.
5289 @node append save-excursion, , append-to-buffer body, append-to-buffer
5290 @comment node-name, next, previous, up
5291 @subsection @code{save-excursion} in @code{append-to-buffer}
5293 The body of the @code{let} expression in @code{append-to-buffer}
5294 consists of a @code{save-excursion} expression.
5296 The @code{save-excursion} function saves the locations of point and
5297 mark, and restores them to those positions after the expressions in the
5298 body of the @code{save-excursion} complete execution. In addition,
5299 @code{save-excursion} keeps track of the original buffer, and
5300 restores it. This is how @code{save-excursion} is used in
5301 @code{append-to-buffer}.
5304 @cindex Indentation for formatting
5305 @cindex Formatting convention
5306 Incidentally, it is worth noting here that a Lisp function is normally
5307 formatted so that everything that is enclosed in a multi-line spread is
5308 indented more to the right than the first symbol. In this function
5309 definition, the @code{let} is indented more than the @code{defun}, and
5310 the @code{save-excursion} is indented more than the @code{let}, like
5326 This formatting convention makes it easy to see that the lines in
5327 the body of the @code{save-excursion} are enclosed by the parentheses
5328 associated with @code{save-excursion}, just as the
5329 @code{save-excursion} itself is enclosed by the parentheses associated
5330 with the @code{let}:
5334 (let ((oldbuf (current-buffer)))
5337 (set-buffer @dots{})
5338 (insert-buffer-substring oldbuf start end)
5344 The use of the @code{save-excursion} function can be viewed as a process
5345 of filling in the slots of a template:
5350 @var{first-expression-in-body}
5351 @var{second-expression-in-body}
5353 @var{last-expression-in-body})
5359 In this function, the body of the @code{save-excursion} contains only
5360 one expression, the @code{let*} expression. You know about a
5361 @code{let} function. The @code{let*} function is different. It has a
5362 @samp{*} in its name. It enables Emacs to set each variable in its
5363 varlist in sequence, one after another.
5365 Its critical feature is that variables later in the varlist can make
5366 use of the values to which Emacs set variables earlier in the varlist.
5367 @xref{fwd-para let, , The @code{let*} expression}.
5369 We will skip functions like @code{let*} and focus on two: the
5370 @code{set-buffer} function and the @code{insert-buffer-substring}
5374 In the old days, the @code{set-buffer} expression was simply
5377 (set-buffer (get-buffer-create buffer))
5385 (set-buffer append-to)
5389 @code{append-to} is bound to @code{(get-buffer-create buffer)} earlier
5390 on in the @code{let*} expression. That extra binding would not be
5391 necessary except for that @code{append-to} is used later in the
5392 varlist as an argument to @code{get-buffer-window-list}.
5397 (let ((oldbuf (current-buffer)))
5399 (let* ((append-to (get-buffer-create buffer))
5400 (windows (get-buffer-window-list append-to t t))
5402 (set-buffer append-to)
5403 (setq point (point))
5404 (barf-if-buffer-read-only)
5405 (insert-buffer-substring oldbuf start end)
5406 (dolist (window windows)
5407 (when (= (window-point window) point)
5408 (set-window-point window (point))))))))
5411 The @code{append-to-buffer} function definition inserts text from the
5412 buffer in which you are currently to a named buffer. It happens that
5413 @code{insert-buffer-substring} copies text from another buffer to the
5414 current buffer, just the reverse---that is why the
5415 @code{append-to-buffer} definition starts out with a @code{let} that
5416 binds the local symbol @code{oldbuf} to the value returned by
5417 @code{current-buffer}.
5420 The @code{insert-buffer-substring} expression looks like this:
5423 (insert-buffer-substring oldbuf start end)
5427 The @code{insert-buffer-substring} function copies a string
5428 @emph{from} the buffer specified as its first argument and inserts the
5429 string into the present buffer. In this case, the argument to
5430 @code{insert-buffer-substring} is the value of the variable created
5431 and bound by the @code{let}, namely the value of @code{oldbuf}, which
5432 was the current buffer when you gave the @code{append-to-buffer}
5435 After @code{insert-buffer-substring} has done its work,
5436 @code{save-excursion} will restore the action to the original buffer
5437 and @code{append-to-buffer} will have done its job.
5440 Written in skeletal form, the workings of the body look like this:
5444 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5445 (save-excursion ; @r{Keep track of buffer.}
5447 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})
5449 @var{change-back-to-original-buffer-when-finished}
5450 @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished}
5454 In summary, @code{append-to-buffer} works as follows: it saves the
5455 value of the current buffer in the variable called @code{oldbuf}. It
5456 gets the new buffer (creating one if need be) and switches Emacs'
5457 attention to it. Using the value of @code{oldbuf}, it inserts the
5458 region of text from the old buffer into the new buffer; and then using
5459 @code{save-excursion}, it brings you back to your original buffer.
5461 In looking at @code{append-to-buffer}, you have explored a fairly
5462 complex function. It shows how to use @code{let} and
5463 @code{save-excursion}, and how to change to and come back from another
5464 buffer. Many function definitions use @code{let},
5465 @code{save-excursion}, and @code{set-buffer} this way.
5467 @node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through
5468 @comment node-name, next, previous, up
5471 Here is a brief summary of the various functions discussed in this chapter.
5474 @item describe-function
5475 @itemx describe-variable
5476 Print the documentation for a function or variable.
5477 Conventionally bound to @kbd{C-h f} and @kbd{C-h v}.
5480 Find the file containing the source for a function or variable and
5481 switch buffers to it, positioning point at the beginning of the item.
5482 Conventionally bound to @kbd{M-.} (that's a period following the
5485 @item save-excursion
5486 Save the location of point and mark and restore their values after the
5487 arguments to @code{save-excursion} have been evaluated. Also, remember
5488 the current buffer and return to it.
5491 Set mark at a location and record the value of the previous mark on the
5492 mark ring. The mark is a location in the buffer that will keep its
5493 relative position even if text is added to or removed from the buffer.
5496 Set point to the location specified by the value of the argument, which
5497 can be a number, a marker, or an expression that returns the number of
5498 a position, such as @code{(point-min)}.
5500 @item insert-buffer-substring
5501 Copy a region of text from a buffer that is passed to the function as
5502 an argument and insert the region into the current buffer.
5504 @item mark-whole-buffer
5505 Mark the whole buffer as a region. Normally bound to @kbd{C-x h}.
5508 Switch the attention of Emacs to another buffer, but do not change the
5509 window being displayed. Used when the program rather than a human is
5510 to work on a different buffer.
5512 @item get-buffer-create
5514 Find a named buffer or create one if a buffer of that name does not
5515 exist. The @code{get-buffer} function returns @code{nil} if the named
5516 buffer does not exist.
5520 @node Buffer Exercises, , Buffer Related Review, Buffer Walk Through
5525 Write your own @code{simplified-end-of-buffer} function definition;
5526 then test it to see whether it works.
5529 Use @code{if} and @code{get-buffer} to write a function that prints a
5530 message telling you whether a buffer exists.
5533 Using @code{find-tag}, find the source for the @code{copy-to-buffer}
5537 @node More Complex, Narrowing & Widening, Buffer Walk Through, Top
5538 @comment node-name, next, previous, up
5539 @chapter A Few More Complex Functions
5541 In this chapter, we build on what we have learned in previous chapters
5542 by looking at more complex functions. The @code{copy-to-buffer}
5543 function illustrates use of two @code{save-excursion} expressions in
5544 one definition, while the @code{insert-buffer} function illustrates
5545 use of an asterisk in an @code{interactive} expression, use of
5546 @code{or}, and the important distinction between a name and the object
5547 to which the name refers.
5552 * beginning-of-buffer::
5553 * Second Buffer Related Review::
5554 * optional Exercise::
5557 @node copy-to-buffer, insert-buffer, More Complex, More Complex
5558 @comment node-name, next, previous, up
5559 @section The Definition of @code{copy-to-buffer}
5560 @findex copy-to-buffer
5562 After understanding how @code{append-to-buffer} works, it is easy to
5563 understand @code{copy-to-buffer}. This function copies text into a
5564 buffer, but instead of adding to the second buffer, it replaces all the
5565 previous text in the second buffer.
5568 The body of @code{copy-to-buffer} looks like this,
5573 (interactive "BCopy to buffer: \nr")
5574 (let ((oldbuf (current-buffer)))
5575 (with-current-buffer (get-buffer-create buffer)
5576 (barf-if-buffer-read-only)
5579 (insert-buffer-substring oldbuf start end)))))
5583 The @code{copy-to-buffer} function has a simpler @code{interactive}
5584 expression than @code{append-to-buffer}.
5587 The definition then says
5590 (with-current-buffer (get-buffer-create buffer) @dots{}
5593 First, look at the earliest inner expression; that is evaluated first.
5594 That expression starts with @code{get-buffer-create buffer}. The
5595 function tells the computer to use the buffer with the name specified
5596 as the one to which you are copying, or if such a buffer does not
5597 exist, to create it. Then, the @code{with-current-buffer} function
5598 evaluates its body with that buffer temporarily current.
5600 (This demonstrates another way to shift the computer's attention but
5601 not the user's. The @code{append-to-buffer} function showed how to do
5602 the same with @code{save-excursion} and @code{set-buffer}.
5603 @code{with-current-buffer} is a newer, and arguably easier,
5606 The @code{barf-if-buffer-read-only} function sends you an error
5607 message saying the buffer is read-only if you cannot modify it.
5609 The next line has the @code{erase-buffer} function as its sole
5610 contents. That function erases the buffer.
5612 Finally, the last two lines contain the @code{save-excursion}
5613 expression with @code{insert-buffer-substring} as its body.
5614 The @code{insert-buffer-substring} expression copies the text from
5615 the buffer you are in (and you have not seen the computer shift its
5616 attention, so you don't know that that buffer is now called
5619 Incidentally, this is what is meant by `replacement'. To replace text,
5620 Emacs erases the previous text and then inserts new text.
5623 In outline, the body of @code{copy-to-buffer} looks like this:
5627 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5628 (@var{with-the-buffer-you-are-copying-to}
5629 (@var{but-do-not-erase-or-copy-to-a-read-only-buffer})
5632 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})))
5636 @node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex
5637 @comment node-name, next, previous, up
5638 @section The Definition of @code{insert-buffer}
5639 @findex insert-buffer
5641 @code{insert-buffer} is yet another buffer-related function. This
5642 command copies another buffer @emph{into} the current buffer. It is the
5643 reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they
5644 copy a region of text @emph{from} the current buffer to another buffer.
5646 Here is a discussion based on the original code. The code was
5647 simplified in 2003 and is harder to understand.
5649 (@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see
5650 a discussion of the new body.)
5652 In addition, this code illustrates the use of @code{interactive} with a
5653 buffer that might be @dfn{read-only} and the important distinction
5654 between the name of an object and the object actually referred to.
5657 * insert-buffer code::
5658 * insert-buffer interactive::
5659 * insert-buffer body::
5663 * New insert-buffer ::
5666 @node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer
5668 @unnumberedsubsec The Code for @code{insert-buffer}
5672 Here is the earlier code:
5676 (defun insert-buffer (buffer)
5677 "Insert after point the contents of BUFFER.
5678 Puts mark after the inserted text.
5679 BUFFER may be a buffer or a buffer name."
5680 (interactive "*bInsert buffer:@: ")
5683 (or (bufferp buffer)
5684 (setq buffer (get-buffer buffer)))
5685 (let (start end newmark)
5689 (setq start (point-min) end (point-max)))
5692 (insert-buffer-substring buffer start end)
5693 (setq newmark (point)))
5694 (push-mark newmark)))
5699 As with other function definitions, you can use a template to see an
5700 outline of the function:
5704 (defun insert-buffer (buffer)
5705 "@var{documentation}@dots{}"
5706 (interactive "*bInsert buffer:@: ")
5711 @node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer
5712 @comment node-name, next, previous, up
5713 @subsection The Interactive Expression in @code{insert-buffer}
5714 @findex interactive, @r{example use of}
5716 In @code{insert-buffer}, the argument to the @code{interactive}
5717 declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert
5721 * Read-only buffer::
5722 * b for interactive::
5725 @node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive
5726 @comment node-name, next, previous, up
5727 @unnumberedsubsubsec A Read-only Buffer
5728 @cindex Read-only buffer
5729 @cindex Asterisk for read-only buffer
5730 @findex * @r{for read-only buffer}
5732 The asterisk is for the situation when the current buffer is a
5733 read-only buffer---a buffer that cannot be modified. If
5734 @code{insert-buffer} is called when the current buffer is read-only, a
5735 message to this effect is printed in the echo area and the terminal
5736 may beep or blink at you; you will not be permitted to insert anything
5737 into current buffer. The asterisk does not need to be followed by a
5738 newline to separate it from the next argument.
5740 @node b for interactive, , Read-only buffer, insert-buffer interactive
5741 @comment node-name, next, previous, up
5742 @unnumberedsubsubsec @samp{b} in an Interactive Expression
5744 The next argument in the interactive expression starts with a lower
5745 case @samp{b}. (This is different from the code for
5746 @code{append-to-buffer}, which uses an upper-case @samp{B}.
5747 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
5748 The lower-case @samp{b} tells the Lisp interpreter that the argument
5749 for @code{insert-buffer} should be an existing buffer or else its
5750 name. (The upper-case @samp{B} option provides for the possibility
5751 that the buffer does not exist.) Emacs will prompt you for the name
5752 of the buffer, offering you a default buffer, with name completion
5753 enabled. If the buffer does not exist, you receive a message that
5754 says ``No match''; your terminal may beep at you as well.
5756 The new and simplified code generates a list for @code{interactive}.
5757 It uses the @code{barf-if-buffer-read-only} and @code{read-buffer}
5758 functions with which we are already familiar and the @code{progn}
5759 special form with which we are not. (It will be described later.)
5761 @node insert-buffer body, if & or, insert-buffer interactive, insert-buffer
5762 @comment node-name, next, previous, up
5763 @subsection The Body of the @code{insert-buffer} Function
5765 The body of the @code{insert-buffer} function has two major parts: an
5766 @code{or} expression and a @code{let} expression. The purpose of the
5767 @code{or} expression is to ensure that the argument @code{buffer} is
5768 bound to a buffer and not just the name of a buffer. The body of the
5769 @code{let} expression contains the code which copies the other buffer
5770 into the current buffer.
5773 In outline, the two expressions fit into the @code{insert-buffer}
5778 (defun insert-buffer (buffer)
5779 "@var{documentation}@dots{}"
5780 (interactive "*bInsert buffer:@: ")
5785 (let (@var{varlist})
5786 @var{body-of-}@code{let}@dots{} )
5790 To understand how the @code{or} expression ensures that the argument
5791 @code{buffer} is bound to a buffer and not to the name of a buffer, it
5792 is first necessary to understand the @code{or} function.
5794 Before doing this, let me rewrite this part of the function using
5795 @code{if} so that you can see what is done in a manner that will be familiar.
5797 @node if & or, Insert or, insert-buffer body, insert-buffer
5798 @comment node-name, next, previous, up
5799 @subsection @code{insert-buffer} With an @code{if} Instead of an @code{or}
5801 The job to be done is to make sure the value of @code{buffer} is a
5802 buffer itself and not the name of a buffer. If the value is the name,
5803 then the buffer itself must be got.
5805 You can imagine yourself at a conference where an usher is wandering
5806 around holding a list with your name on it and looking for you: the
5807 usher is ``bound'' to your name, not to you; but when the usher finds
5808 you and takes your arm, the usher becomes ``bound'' to you.
5811 In Lisp, you might describe this situation like this:
5815 (if (not (holding-on-to-guest))
5816 (find-and-take-arm-of-guest))
5820 We want to do the same thing with a buffer---if we do not have the
5821 buffer itself, we want to get it.
5824 Using a predicate called @code{bufferp} that tells us whether we have a
5825 buffer (rather than its name), we can write the code like this:
5829 (if (not (bufferp buffer)) ; @r{if-part}
5830 (setq buffer (get-buffer buffer))) ; @r{then-part}
5835 Here, the true-or-false-test of the @code{if} expression is
5836 @w{@code{(not (bufferp buffer))}}; and the then-part is the expression
5837 @w{@code{(setq buffer (get-buffer buffer))}}.
5839 In the test, the function @code{bufferp} returns true if its argument is
5840 a buffer---but false if its argument is the name of the buffer. (The
5841 last character of the function name @code{bufferp} is the character
5842 @samp{p}; as we saw earlier, such use of @samp{p} is a convention that
5843 indicates that the function is a predicate, which is a term that means
5844 that the function will determine whether some property is true or false.
5845 @xref{Wrong Type of Argument, , Using the Wrong Type Object as an
5849 The function @code{not} precedes the expression @code{(bufferp buffer)},
5850 so the true-or-false-test looks like this:
5853 (not (bufferp buffer))
5857 @code{not} is a function that returns true if its argument is false
5858 and false if its argument is true. So if @code{(bufferp buffer)}
5859 returns true, the @code{not} expression returns false and vice-verse:
5860 what is ``not true'' is false and what is ``not false'' is true.
5862 Using this test, the @code{if} expression works as follows: when the
5863 value of the variable @code{buffer} is actually a buffer rather than
5864 its name, the true-or-false-test returns false and the @code{if}
5865 expression does not evaluate the then-part. This is fine, since we do
5866 not need to do anything to the variable @code{buffer} if it really is
5869 On the other hand, when the value of @code{buffer} is not a buffer
5870 itself, but the name of a buffer, the true-or-false-test returns true
5871 and the then-part of the expression is evaluated. In this case, the
5872 then-part is @code{(setq buffer (get-buffer buffer))}. This
5873 expression uses the @code{get-buffer} function to return an actual
5874 buffer itself, given its name. The @code{setq} then sets the variable
5875 @code{buffer} to the value of the buffer itself, replacing its previous
5876 value (which was the name of the buffer).
5878 @node Insert or, Insert let, if & or, insert-buffer
5879 @comment node-name, next, previous, up
5880 @subsection The @code{or} in the Body
5882 The purpose of the @code{or} expression in the @code{insert-buffer}
5883 function is to ensure that the argument @code{buffer} is bound to a
5884 buffer and not just to the name of a buffer. The previous section shows
5885 how the job could have been done using an @code{if} expression.
5886 However, the @code{insert-buffer} function actually uses @code{or}.
5887 To understand this, it is necessary to understand how @code{or} works.
5890 An @code{or} function can have any number of arguments. It evaluates
5891 each argument in turn and returns the value of the first of its
5892 arguments that is not @code{nil}. Also, and this is a crucial feature
5893 of @code{or}, it does not evaluate any subsequent arguments after
5894 returning the first non-@code{nil} value.
5897 The @code{or} expression looks like this:
5901 (or (bufferp buffer)
5902 (setq buffer (get-buffer buffer)))
5907 The first argument to @code{or} is the expression @code{(bufferp buffer)}.
5908 This expression returns true (a non-@code{nil} value) if the buffer is
5909 actually a buffer, and not just the name of a buffer. In the @code{or}
5910 expression, if this is the case, the @code{or} expression returns this
5911 true value and does not evaluate the next expression---and this is fine
5912 with us, since we do not want to do anything to the value of
5913 @code{buffer} if it really is a buffer.
5915 On the other hand, if the value of @code{(bufferp buffer)} is @code{nil},
5916 which it will be if the value of @code{buffer} is the name of a buffer,
5917 the Lisp interpreter evaluates the next element of the @code{or}
5918 expression. This is the expression @code{(setq buffer (get-buffer
5919 buffer))}. This expression returns a non-@code{nil} value, which
5920 is the value to which it sets the variable @code{buffer}---and this
5921 value is a buffer itself, not the name of a buffer.
5923 The result of all this is that the symbol @code{buffer} is always
5924 bound to a buffer itself rather than to the name of a buffer. All
5925 this is necessary because the @code{set-buffer} function in a
5926 following line only works with a buffer itself, not with the name to a
5930 Incidentally, using @code{or}, the situation with the usher would be
5934 (or (holding-on-to-guest) (find-and-take-arm-of-guest))
5937 @node Insert let, New insert-buffer , Insert or, insert-buffer
5938 @comment node-name, next, previous, up
5939 @subsection The @code{let} Expression in @code{insert-buffer}
5941 After ensuring that the variable @code{buffer} refers to a buffer itself
5942 and not just to the name of a buffer, the @code{insert-buffer function}
5943 continues with a @code{let} expression. This specifies three local
5944 variables, @code{start}, @code{end}, and @code{newmark} and binds them
5945 to the initial value @code{nil}. These variables are used inside the
5946 remainder of the @code{let} and temporarily hide any other occurrence of
5947 variables of the same name in Emacs until the end of the @code{let}.
5950 The body of the @code{let} contains two @code{save-excursion}
5951 expressions. First, we will look at the inner @code{save-excursion}
5952 expression in detail. The expression looks like this:
5958 (setq start (point-min) end (point-max)))
5963 The expression @code{(set-buffer buffer)} changes Emacs' attention
5964 from the current buffer to the one from which the text will copied.
5965 In that buffer, the variables @code{start} and @code{end} are set to
5966 the beginning and end of the buffer, using the commands
5967 @code{point-min} and @code{point-max}. Note that we have here an
5968 illustration of how @code{setq} is able to set two variables in the
5969 same expression. The first argument of @code{setq} is set to the
5970 value of its second, and its third argument is set to the value of its
5973 After the body of the inner @code{save-excursion} is evaluated, the
5974 @code{save-excursion} restores the original buffer, but @code{start} and
5975 @code{end} remain set to the values of the beginning and end of the
5976 buffer from which the text will be copied.
5979 The outer @code{save-excursion} expression looks like this:
5984 (@var{inner-}@code{save-excursion}@var{-expression}
5985 (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end})
5986 (insert-buffer-substring buffer start end)
5987 (setq newmark (point)))
5992 The @code{insert-buffer-substring} function copies the text
5993 @emph{into} the current buffer @emph{from} the region indicated by
5994 @code{start} and @code{end} in @code{buffer}. Since the whole of the
5995 second buffer lies between @code{start} and @code{end}, the whole of
5996 the second buffer is copied into the buffer you are editing. Next,
5997 the value of point, which will be at the end of the inserted text, is
5998 recorded in the variable @code{newmark}.
6000 After the body of the outer @code{save-excursion} is evaluated, point
6001 and mark are relocated to their original places.
6003 However, it is convenient to locate a mark at the end of the newly
6004 inserted text and locate point at its beginning. The @code{newmark}
6005 variable records the end of the inserted text. In the last line of
6006 the @code{let} expression, the @code{(push-mark newmark)} expression
6007 function sets a mark to this location. (The previous location of the
6008 mark is still accessible; it is recorded on the mark ring and you can
6009 go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is
6010 located at the beginning of the inserted text, which is where it was
6011 before you called the insert function, the position of which was saved
6012 by the first @code{save-excursion}.
6015 The whole @code{let} expression looks like this:
6019 (let (start end newmark)
6023 (setq start (point-min) end (point-max)))
6024 (insert-buffer-substring buffer start end)
6025 (setq newmark (point)))
6026 (push-mark newmark))
6030 Like the @code{append-to-buffer} function, the @code{insert-buffer}
6031 function uses @code{let}, @code{save-excursion}, and
6032 @code{set-buffer}. In addition, the function illustrates one way to
6033 use @code{or}. All these functions are building blocks that we will
6034 find and use again and again.
6036 @node New insert-buffer , , Insert let, insert-buffer
6037 @comment node-name, next, previous, up
6038 @subsection New Body for @code{insert-buffer}
6039 @findex insert-buffer, new version body
6040 @findex new version body for insert-buffer
6042 The body in the GNU Emacs 22 version is more confusing than the original.
6045 It consists of two expressions,
6051 (insert-buffer-substring (get-buffer buffer))
6059 except, and this is what confuses novices, very important work is done
6060 inside the @code{push-mark} expression.
6062 The @code{get-buffer} function returns a buffer with the name
6063 provided. You will note that the function is @emph{not} called
6064 @code{get-buffer-create}; it does not create a buffer if one does not
6065 already exist. The buffer returned by @code{get-buffer}, an existing
6066 buffer, is passed to @code{insert-buffer-substring}, which inserts the
6067 whole of the buffer (since you did not specify anything else).
6069 The location into which the buffer is inserted is recorded by
6070 @code{push-mark}. Then the function returns @code{nil}, the value of
6071 its last command. Put another way, the @code{insert-buffer} function
6072 exists only to produce a side effect, inserting another buffer, not to
6075 @node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex
6076 @comment node-name, next, previous, up
6077 @section Complete Definition of @code{beginning-of-buffer}
6078 @findex beginning-of-buffer
6080 The basic structure of the @code{beginning-of-buffer} function has
6081 already been discussed. (@xref{simplified-beginning-of-buffer, , A
6082 Simplified @code{beginning-of-buffer} Definition}.)
6083 This section describes the complex part of the definition.
6085 As previously described, when invoked without an argument,
6086 @code{beginning-of-buffer} moves the cursor to the beginning of the
6087 buffer (in truth, the beginning of the accessible portion of the
6088 buffer), leaving the mark at the previous position. However, when the
6089 command is invoked with a number between one and ten, the function
6090 considers that number to be a fraction of the length of the buffer,
6091 measured in tenths, and Emacs moves the cursor that fraction of the
6092 way from the beginning of the buffer. Thus, you can either call this
6093 function with the key command @kbd{M-<}, which will move the cursor to
6094 the beginning of the buffer, or with a key command such as @kbd{C-u 7
6095 M-<} which will move the cursor to a point 70% of the way through the
6096 buffer. If a number bigger than ten is used for the argument, it
6097 moves to the end of the buffer.
6099 The @code{beginning-of-buffer} function can be called with or without an
6100 argument. The use of the argument is optional.
6103 * Optional Arguments::
6104 * beginning-of-buffer opt arg::
6105 * beginning-of-buffer complete::
6108 @node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer
6109 @subsection Optional Arguments
6111 Unless told otherwise, Lisp expects that a function with an argument in
6112 its function definition will be called with a value for that argument.
6113 If that does not happen, you get an error and a message that says
6114 @samp{Wrong number of arguments}.
6116 @cindex Optional arguments
6119 However, optional arguments are a feature of Lisp: a particular
6120 @dfn{keyword} is used to tell the Lisp interpreter that an argument is
6121 optional. The keyword is @code{&optional}. (The @samp{&} in front of
6122 @samp{optional} is part of the keyword.) In a function definition, if
6123 an argument follows the keyword @code{&optional}, no value need be
6124 passed to that argument when the function is called.
6127 The first line of the function definition of @code{beginning-of-buffer}
6128 therefore looks like this:
6131 (defun beginning-of-buffer (&optional arg)
6135 In outline, the whole function looks like this:
6139 (defun beginning-of-buffer (&optional arg)
6140 "@var{documentation}@dots{}"
6142 (or (@var{is-the-argument-a-cons-cell} arg)
6143 (and @var{are-both-transient-mark-mode-and-mark-active-true})
6145 (let (@var{determine-size-and-set-it})
6147 (@var{if-there-is-an-argument}
6148 @var{figure-out-where-to-go}
6155 The function is similar to the @code{simplified-beginning-of-buffer}
6156 function except that the @code{interactive} expression has @code{"P"}
6157 as an argument and the @code{goto-char} function is followed by an
6158 if-then-else expression that figures out where to put the cursor if
6159 there is an argument that is not a cons cell.
6161 (Since I do not explain a cons cell for many more chapters, please
6162 consider ignoring the function @code{consp}. @xref{List
6163 Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type,
6164 , Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference
6167 The @code{"P"} in the @code{interactive} expression tells Emacs to
6168 pass a prefix argument, if there is one, to the function in raw form.
6169 A prefix argument is made by typing the @key{META} key followed by a
6170 number, or by typing @kbd{C-u} and then a number. (If you don't type
6171 a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase
6172 @code{"p"} in the @code{interactive} expression causes the function to
6173 convert a prefix arg to a number.)
6175 The true-or-false-test of the @code{if} expression looks complex, but
6176 it is not: it checks whether @code{arg} has a value that is not
6177 @code{nil} and whether it is a cons cell. (That is what @code{consp}
6178 does; it checks whether its argument is a cons cell.) If @code{arg}
6179 has a value that is not @code{nil} (and is not a cons cell), which
6180 will be the case if @code{beginning-of-buffer} is called with a
6181 numeric argument, then this true-or-false-test will return true and
6182 the then-part of the @code{if} expression will be evaluated. On the
6183 other hand, if @code{beginning-of-buffer} is not called with an
6184 argument, the value of @code{arg} will be @code{nil} and the else-part
6185 of the @code{if} expression will be evaluated. The else-part is
6186 simply @code{point-min}, and when this is the outcome, the whole
6187 @code{goto-char} expression is @code{(goto-char (point-min))}, which
6188 is how we saw the @code{beginning-of-buffer} function in its
6191 @node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer
6192 @subsection @code{beginning-of-buffer} with an Argument
6194 When @code{beginning-of-buffer} is called with an argument, an
6195 expression is evaluated which calculates what value to pass to
6196 @code{goto-char}. This expression is rather complicated at first sight.
6197 It includes an inner @code{if} expression and much arithmetic. It looks
6202 (if (> (buffer-size) 10000)
6203 ;; @r{Avoid overflow for large buffer sizes!}
6204 (* (prefix-numeric-value arg)
6209 size (prefix-numeric-value arg))) 10)))
6214 * Disentangle beginning-of-buffer::
6215 * Large buffer case::
6216 * Small buffer case::
6219 @node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg
6221 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer}
6224 Like other complex-looking expressions, the conditional expression
6225 within @code{beginning-of-buffer} can be disentangled by looking at it
6226 as parts of a template, in this case, the template for an if-then-else
6227 expression. In skeletal form, the expression looks like this:
6231 (if (@var{buffer-is-large}
6232 @var{divide-buffer-size-by-10-and-multiply-by-arg}
6233 @var{else-use-alternate-calculation}
6237 The true-or-false-test of this inner @code{if} expression checks the
6238 size of the buffer. The reason for this is that the old Version 18
6239 Emacs used numbers that are no bigger than eight million or so
6240 and in the computation that followed, the programmer feared that Emacs
6241 might try to use over-large numbers if the buffer were large. The
6242 term `overflow', mentioned in the comment, means numbers that are over
6243 large. Version 21 Emacs uses larger numbers, but this code has not
6244 been touched, if only because people now look at buffers that are far,
6245 far larger than ever before.
6247 There are two cases: if the buffer is large and if it is not.
6249 @node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg
6250 @comment node-name, next, previous, up
6251 @unnumberedsubsubsec What happens in a large buffer
6253 In @code{beginning-of-buffer}, the inner @code{if} expression tests
6254 whether the size of the buffer is greater than 10,000 characters. To do
6255 this, it uses the @code{>} function and the computation of @code{size}
6256 that comes from the let expression.
6258 In the old days, the function @code{buffer-size} was used. Not only
6259 was that function called several times, it gave the size of the whole
6260 buffer, not the accessible part. The computation makes much more
6261 sense when it handles just the accessible part. (@xref{Narrowing &
6262 Widening, , Narrowing and Widening}, for more information on focusing
6263 attention to an `accessible' part.)
6266 The line looks like this:
6274 When the buffer is large, the then-part of the @code{if} expression is
6275 evaluated. It reads like this (after formatting for easy reading):
6280 (prefix-numeric-value arg)
6286 This expression is a multiplication, with two arguments to the function
6289 The first argument is @code{(prefix-numeric-value arg)}. When
6290 @code{"P"} is used as the argument for @code{interactive}, the value
6291 passed to the function as its argument is passed a ``raw prefix
6292 argument'', and not a number. (It is a number in a list.) To perform
6293 the arithmetic, a conversion is necessary, and
6294 @code{prefix-numeric-value} does the job.
6296 @findex / @r{(division)}
6298 The second argument is @code{(/ size 10)}. This expression divides
6299 the numeric value by ten --- the numeric value of the size of the
6300 accessible portion of the buffer. This produces a number that tells
6301 how many characters make up one tenth of the buffer size. (In Lisp,
6302 @code{/} is used for division, just as @code{*} is used for
6306 In the multiplication expression as a whole, this amount is multiplied
6307 by the value of the prefix argument---the multiplication looks like this:
6311 (* @var{numeric-value-of-prefix-arg}
6312 @var{number-of-characters-in-one-tenth-of-the-accessible-buffer})
6317 If, for example, the prefix argument is @samp{7}, the one-tenth value
6318 will be multiplied by 7 to give a position 70% of the way through.
6321 The result of all this is that if the accessible portion of the buffer
6322 is large, the @code{goto-char} expression reads like this:
6326 (goto-char (* (prefix-numeric-value arg)
6331 This puts the cursor where we want it.
6333 @node Small buffer case, , Large buffer case, beginning-of-buffer opt arg
6334 @comment node-name, next, previous, up
6335 @unnumberedsubsubsec What happens in a small buffer
6337 If the buffer contains fewer than 10,000 characters, a slightly
6338 different computation is performed. You might think this is not
6339 necessary, since the first computation could do the job. However, in
6340 a small buffer, the first method may not put the cursor on exactly the
6341 desired line; the second method does a better job.
6344 The code looks like this:
6346 @c Keep this on one line.
6348 (/ (+ 10 (* size (prefix-numeric-value arg))) 10))
6353 This is code in which you figure out what happens by discovering how the
6354 functions are embedded in parentheses. It is easier to read if you
6355 reformat it with each expression indented more deeply than its
6356 enclosing expression:
6364 (prefix-numeric-value arg)))
6371 Looking at parentheses, we see that the innermost operation is
6372 @code{(prefix-numeric-value arg)}, which converts the raw argument to
6373 a number. In the following expression, this number is multiplied by
6374 the size of the accessible portion of the buffer:
6377 (* size (prefix-numeric-value arg))
6381 This multiplication creates a number that may be larger than the size of
6382 the buffer---seven times larger if the argument is 7, for example. Ten
6383 is then added to this number and finally the large number is divided by
6384 ten to provide a value that is one character larger than the percentage
6385 position in the buffer.
6387 The number that results from all this is passed to @code{goto-char} and
6388 the cursor is moved to that point.
6391 @node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer
6392 @comment node-name, next, previous, up
6393 @subsection The Complete @code{beginning-of-buffer}
6396 Here is the complete text of the @code{beginning-of-buffer} function:
6402 (defun beginning-of-buffer (&optional arg)
6403 "Move point to the beginning of the buffer;
6404 leave mark at previous position.
6405 With \\[universal-argument] prefix,
6406 do not set mark at previous position.
6408 put point N/10 of the way from the beginning.
6410 If the buffer is narrowed,
6411 this command uses the beginning and size
6412 of the accessible part of the buffer.
6416 Don't use this command in Lisp programs!
6417 \(goto-char (point-min)) is faster
6418 and avoids clobbering the mark."
6421 (and transient-mark-mode mark-active)
6425 (let ((size (- (point-max) (point-min))))
6426 (goto-char (if (and arg (not (consp arg)))
6429 ;; Avoid overflow for large buffer sizes!
6430 (* (prefix-numeric-value arg)
6432 (/ (+ 10 (* size (prefix-numeric-value arg))) 10)))
6434 (if arg (forward-line 1)))
6439 From before GNU Emacs 22
6442 (defun beginning-of-buffer (&optional arg)
6443 "Move point to the beginning of the buffer;
6444 leave mark at previous position.
6445 With arg N, put point N/10 of the way
6446 from the true beginning.
6449 Don't use this in Lisp programs!
6450 \(goto-char (point-min)) is faster
6451 and does not set the mark."
6458 (if (> (buffer-size) 10000)
6459 ;; @r{Avoid overflow for large buffer sizes!}
6460 (* (prefix-numeric-value arg)
6461 (/ (buffer-size) 10))
6464 (/ (+ 10 (* (buffer-size)
6465 (prefix-numeric-value arg)))
6468 (if arg (forward-line 1)))
6474 Except for two small points, the previous discussion shows how this
6475 function works. The first point deals with a detail in the
6476 documentation string, and the second point concerns the last line of
6480 In the documentation string, there is reference to an expression:
6483 \\[universal-argument]
6487 A @samp{\\} is used before the first square bracket of this
6488 expression. This @samp{\\} tells the Lisp interpreter to substitute
6489 whatever key is currently bound to the @samp{[@dots{}]}. In the case
6490 of @code{universal-argument}, that is usually @kbd{C-u}, but it might
6491 be different. (@xref{Documentation Tips, , Tips for Documentation
6492 Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more
6496 Finally, the last line of the @code{beginning-of-buffer} command says
6497 to move point to the beginning of the next line if the command is
6498 invoked with an argument:
6501 (if arg (forward-line 1)))
6505 This puts the cursor at the beginning of the first line after the
6506 appropriate tenths position in the buffer. This is a flourish that
6507 means that the cursor is always located @emph{at least} the requested
6508 tenths of the way through the buffer, which is a nicety that is,
6509 perhaps, not necessary, but which, if it did not occur, would be sure
6512 On the other hand, it also means that if you specify the command with
6513 a @kbd{C-u}, but without a number, that is to say, if the `raw prefix
6514 argument' is simply a cons cell, then the command puts you at the
6515 beginning of the second line @dots{} I don't know whether this is
6516 intended or whether no one has dealt with the code to avoid this
6519 @node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex
6520 @comment node-name, next, previous, up
6523 Here is a brief summary of some of the topics covered in this chapter.
6527 Evaluate each argument in sequence, and return the value of the first
6528 argument that is not @code{nil}; if none return a value that is not
6529 @code{nil}, return @code{nil}. In brief, return the first true value
6530 of the arguments; return a true value if one @emph{or} any of the
6534 Evaluate each argument in sequence, and if any are @code{nil}, return
6535 @code{nil}; if none are @code{nil}, return the value of the last
6536 argument. In brief, return a true value only if all the arguments are
6537 true; return a true value if one @emph{and} each of the others is
6541 A keyword used to indicate that an argument to a function definition
6542 is optional; this means that the function can be evaluated without the
6543 argument, if desired.
6545 @item prefix-numeric-value
6546 Convert the `raw prefix argument' produced by @code{(interactive
6547 "P")} to a numeric value.
6550 Move point forward to the beginning of the next line, or if the argument
6551 is greater than one, forward that many lines. If it can't move as far
6552 forward as it is supposed to, @code{forward-line} goes forward as far as
6553 it can and then returns a count of the number of additional lines it was
6554 supposed to move but couldn't.
6557 Delete the entire contents of the current buffer.
6560 Return @code{t} if its argument is a buffer; otherwise return @code{nil}.
6563 @node optional Exercise, , Second Buffer Related Review, More Complex
6564 @section @code{optional} Argument Exercise
6566 Write an interactive function with an optional argument that tests
6567 whether its argument, a number, is greater than or equal to, or else,
6568 less than the value of @code{fill-column}, and tells you which, in a
6569 message. However, if you do not pass an argument to the function, use
6570 56 as a default value.
6572 @node Narrowing & Widening, car cdr & cons, More Complex, Top
6573 @comment node-name, next, previous, up
6574 @chapter Narrowing and Widening
6575 @cindex Focusing attention (narrowing)
6579 Narrowing is a feature of Emacs that makes it possible for you to focus
6580 on a specific part of a buffer, and work without accidentally changing
6581 other parts. Narrowing is normally disabled since it can confuse
6585 * Narrowing advantages::
6586 * save-restriction::
6591 @node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening
6593 @unnumberedsec The Advantages of Narrowing
6596 With narrowing, the rest of a buffer is made invisible, as if it weren't
6597 there. This is an advantage if, for example, you want to replace a word
6598 in one part of a buffer but not in another: you narrow to the part you want
6599 and the replacement is carried out only in that section, not in the rest
6600 of the buffer. Searches will only work within a narrowed region, not
6601 outside of one, so if you are fixing a part of a document, you can keep
6602 yourself from accidentally finding parts you do not need to fix by
6603 narrowing just to the region you want.
6604 (The key binding for @code{narrow-to-region} is @kbd{C-x n n}.)
6606 However, narrowing does make the rest of the buffer invisible, which
6607 can scare people who inadvertently invoke narrowing and think they
6608 have deleted a part of their file. Moreover, the @code{undo} command
6609 (which is usually bound to @kbd{C-x u}) does not turn off narrowing
6610 (nor should it), so people can become quite desperate if they do not
6611 know that they can return the rest of a buffer to visibility with the
6612 @code{widen} command.
6613 (The key binding for @code{widen} is @kbd{C-x n w}.)
6615 Narrowing is just as useful to the Lisp interpreter as to a human.
6616 Often, an Emacs Lisp function is designed to work on just part of a
6617 buffer; or conversely, an Emacs Lisp function needs to work on all of a
6618 buffer that has been narrowed. The @code{what-line} function, for
6619 example, removes the narrowing from a buffer, if it has any narrowing
6620 and when it has finished its job, restores the narrowing to what it was.
6621 On the other hand, the @code{count-lines} function, which is called by
6622 @code{what-line}, uses narrowing to restrict itself to just that portion
6623 of the buffer in which it is interested and then restores the previous
6626 @node save-restriction, what-line, Narrowing advantages, Narrowing & Widening
6627 @comment node-name, next, previous, up
6628 @section The @code{save-restriction} Special Form
6629 @findex save-restriction
6631 In Emacs Lisp, you can use the @code{save-restriction} special form to
6632 keep track of whatever narrowing is in effect, if any. When the Lisp
6633 interpreter meets with @code{save-restriction}, it executes the code
6634 in the body of the @code{save-restriction} expression, and then undoes
6635 any changes to narrowing that the code caused. If, for example, the
6636 buffer is narrowed and the code that follows @code{save-restriction}
6637 gets rid of the narrowing, @code{save-restriction} returns the buffer
6638 to its narrowed region afterwards. In the @code{what-line} command,
6639 any narrowing the buffer may have is undone by the @code{widen}
6640 command that immediately follows the @code{save-restriction} command.
6641 Any original narrowing is restored just before the completion of the
6645 The template for a @code{save-restriction} expression is simple:
6655 The body of the @code{save-restriction} is one or more expressions that
6656 will be evaluated in sequence by the Lisp interpreter.
6658 Finally, a point to note: when you use both @code{save-excursion} and
6659 @code{save-restriction}, one right after the other, you should use
6660 @code{save-excursion} outermost. If you write them in reverse order,
6661 you may fail to record narrowing in the buffer to which Emacs switches
6662 after calling @code{save-excursion}. Thus, when written together,
6663 @code{save-excursion} and @code{save-restriction} should be written
6674 In other circumstances, when not written together, the
6675 @code{save-excursion} and @code{save-restriction} special forms must
6676 be written in the order appropriate to the function.
6692 /usr/local/src/emacs/lisp/simple.el
6695 "Print the current buffer line number and narrowed line number of point."
6697 (let ((start (point-min))
6698 (n (line-number-at-pos)))
6700 (message "Line %d" n)
6704 (message "line %d (narrowed line %d)"
6705 (+ n (line-number-at-pos start) -1) n))))))
6707 (defun line-number-at-pos (&optional pos)
6708 "Return (narrowed) buffer line number at position POS.
6709 If POS is nil, use current buffer location.
6710 Counting starts at (point-min), so the value refers
6711 to the contents of the accessible portion of the buffer."
6712 (let ((opoint (or pos (point))) start)
6714 (goto-char (point-min))
6715 (setq start (point))
6718 (1+ (count-lines start (point))))))
6720 (defun count-lines (start end)
6721 "Return number of lines between START and END.
6722 This is usually the number of newlines between them,
6723 but can be one more if START is not equal to END
6724 and the greater of them is not at the start of a line."
6727 (narrow-to-region start end)
6728 (goto-char (point-min))
6729 (if (eq selective-display t)
6732 (while (re-search-forward "[\n\C-m]" nil t 40)
6733 (setq done (+ 40 done)))
6734 (while (re-search-forward "[\n\C-m]" nil t 1)
6735 (setq done (+ 1 done)))
6736 (goto-char (point-max))
6737 (if (and (/= start end)
6741 (- (buffer-size) (forward-line (buffer-size)))))))
6744 @node what-line, narrow Exercise, save-restriction, Narrowing & Widening
6745 @comment node-name, next, previous, up
6746 @section @code{what-line}
6748 @cindex Widening, example of
6750 The @code{what-line} command tells you the number of the line in which
6751 the cursor is located. The function illustrates the use of the
6752 @code{save-restriction} and @code{save-excursion} commands. Here is the
6753 original text of the function:
6758 "Print the current line number (in the buffer) of point."
6765 (1+ (count-lines 1 (point)))))))
6769 (In recent versions of GNU Emacs, the @code{what-line} function has
6770 been expanded to tell you your line number in a narrowed buffer as
6771 well as your line number in a widened buffer. The recent version is
6772 more complex than the version shown here. If you feel adventurous,
6773 you might want to look at it after figuring out how this version
6774 works. You will probably need to use @kbd{C-h f}
6775 (@code{describe-function}). The newer version uses a conditional to
6776 determine whether the buffer has been narrowed.
6778 (Also, it uses @code{line-number-at-pos}, which among other simple
6779 expressions, such as @code{(goto-char (point-min))}, moves point to
6780 the beginning of the current line with @code{(forward-line 0)} rather
6781 than @code{beginning-of-line}.)
6783 The @code{what-line} function as shown here has a documentation line
6784 and is interactive, as you would expect. The next two lines use the
6785 functions @code{save-restriction} and @code{widen}.
6787 The @code{save-restriction} special form notes whatever narrowing is in
6788 effect, if any, in the current buffer and restores that narrowing after
6789 the code in the body of the @code{save-restriction} has been evaluated.
6791 The @code{save-restriction} special form is followed by @code{widen}.
6792 This function undoes any narrowing the current buffer may have had
6793 when @code{what-line} was called. (The narrowing that was there is
6794 the narrowing that @code{save-restriction} remembers.) This widening
6795 makes it possible for the line counting commands to count from the
6796 beginning of the buffer. Otherwise, they would have been limited to
6797 counting within the accessible region. Any original narrowing is
6798 restored just before the completion of the function by the
6799 @code{save-restriction} special form.
6801 The call to @code{widen} is followed by @code{save-excursion}, which
6802 saves the location of the cursor (i.e., of point) and of the mark, and
6803 restores them after the code in the body of the @code{save-excursion}
6804 uses the @code{beginning-of-line} function to move point.
6806 (Note that the @code{(widen)} expression comes between the
6807 @code{save-restriction} and @code{save-excursion} special forms. When
6808 you write the two @code{save- @dots{}} expressions in sequence, write
6809 @code{save-excursion} outermost.)
6812 The last two lines of the @code{what-line} function are functions to
6813 count the number of lines in the buffer and then print the number in the
6819 (1+ (count-lines 1 (point)))))))
6823 The @code{message} function prints a one-line message at the bottom of
6824 the Emacs screen. The first argument is inside of quotation marks and
6825 is printed as a string of characters. However, it may contain a
6826 @samp{%d} expression to print a following argument. @samp{%d} prints
6827 the argument as a decimal, so the message will say something such as
6831 The number that is printed in place of the @samp{%d} is computed by the
6832 last line of the function:
6835 (1+ (count-lines 1 (point)))
6841 (defun count-lines (start end)
6842 "Return number of lines between START and END.
6843 This is usually the number of newlines between them,
6844 but can be one more if START is not equal to END
6845 and the greater of them is not at the start of a line."
6848 (narrow-to-region start end)
6849 (goto-char (point-min))
6850 (if (eq selective-display t)
6853 (while (re-search-forward "[\n\C-m]" nil t 40)
6854 (setq done (+ 40 done)))
6855 (while (re-search-forward "[\n\C-m]" nil t 1)
6856 (setq done (+ 1 done)))
6857 (goto-char (point-max))
6858 (if (and (/= start end)
6862 (- (buffer-size) (forward-line (buffer-size)))))))
6866 What this does is count the lines from the first position of the
6867 buffer, indicated by the @code{1}, up to @code{(point)}, and then add
6868 one to that number. (The @code{1+} function adds one to its
6869 argument.) We add one to it because line 2 has only one line before
6870 it, and @code{count-lines} counts only the lines @emph{before} the
6873 After @code{count-lines} has done its job, and the message has been
6874 printed in the echo area, the @code{save-excursion} restores point and
6875 mark to their original positions; and @code{save-restriction} restores
6876 the original narrowing, if any.
6878 @node narrow Exercise, , what-line, Narrowing & Widening
6879 @section Exercise with Narrowing
6881 Write a function that will display the first 60 characters of the
6882 current buffer, even if you have narrowed the buffer to its latter
6883 half so that the first line is inaccessible. Restore point, mark, and
6884 narrowing. For this exercise, you need to use a whole potpourri of
6885 functions, including @code{save-restriction}, @code{widen},
6886 @code{goto-char}, @code{point-min}, @code{message}, and
6887 @code{buffer-substring}.
6889 @cindex Properties, mention of @code{buffer-substring-no-properties}
6890 (@code{buffer-substring} is a previously unmentioned function you will
6891 have to investigate yourself; or perhaps you will have to use
6892 @code{buffer-substring-no-properties} or
6893 @code{filter-buffer-substring} @dots{}, yet other functions. Text
6894 properties are a feature otherwise not discussed here. @xref{Text
6895 Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference
6898 Additionally, do you really need @code{goto-char} or @code{point-min}?
6899 Or can you write the function without them?
6901 @node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top
6902 @comment node-name, next, previous, up
6903 @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
6904 @findex car, @r{introduced}
6905 @findex cdr, @r{introduced}
6907 In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental
6908 functions. The @code{cons} function is used to construct lists, and
6909 the @code{car} and @code{cdr} functions are used to take them apart.
6911 In the walk through of the @code{copy-region-as-kill} function, we
6912 will see @code{cons} as well as two variants on @code{cdr},
6913 namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.)
6926 @node Strange Names, car & cdr, car cdr & cons, car cdr & cons
6928 @unnumberedsec Strange Names
6931 The name of the @code{cons} function is not unreasonable: it is an
6932 abbreviation of the word `construct'. The origins of the names for
6933 @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car}
6934 is an acronym from the phrase `Contents of the Address part of the
6935 Register'; and @code{cdr} (pronounced `could-er') is an acronym from
6936 the phrase `Contents of the Decrement part of the Register'. These
6937 phrases refer to specific pieces of hardware on the very early
6938 computer on which the original Lisp was developed. Besides being
6939 obsolete, the phrases have been completely irrelevant for more than 25
6940 years to anyone thinking about Lisp. Nonetheless, although a few
6941 brave scholars have begun to use more reasonable names for these
6942 functions, the old terms are still in use. In particular, since the
6943 terms are used in the Emacs Lisp source code, we will use them in this
6946 @node car & cdr, cons, Strange Names, car cdr & cons
6947 @comment node-name, next, previous, up
6948 @section @code{car} and @code{cdr}
6950 The @sc{car} of a list is, quite simply, the first item in the list.
6951 Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is
6955 If you are reading this in Info in GNU Emacs, you can see this by
6956 evaluating the following:
6959 (car '(rose violet daisy buttercup))
6963 After evaluating the expression, @code{rose} will appear in the echo
6966 Clearly, a more reasonable name for the @code{car} function would be
6967 @code{first} and this is often suggested.
6969 @code{car} does not remove the first item from the list; it only reports
6970 what it is. After @code{car} has been applied to a list, the list is
6971 still the same as it was. In the jargon, @code{car} is
6972 `non-destructive'. This feature turns out to be important.
6974 The @sc{cdr} of a list is the rest of the list, that is, the
6975 @code{cdr} function returns the part of the list that follows the
6976 first item. Thus, while the @sc{car} of the list @code{'(rose violet
6977 daisy buttercup)} is @code{rose}, the rest of the list, the value
6978 returned by the @code{cdr} function, is @code{(violet daisy
6982 You can see this by evaluating the following in the usual way:
6985 (cdr '(rose violet daisy buttercup))
6989 When you evaluate this, @code{(violet daisy buttercup)} will appear in
6992 Like @code{car}, @code{cdr} does not remove any elements from the
6993 list---it just returns a report of what the second and subsequent
6996 Incidentally, in the example, the list of flowers is quoted. If it were
6997 not, the Lisp interpreter would try to evaluate the list by calling
6998 @code{rose} as a function. In this example, we do not want to do that.
7000 Clearly, a more reasonable name for @code{cdr} would be @code{rest}.
7002 (There is a lesson here: when you name new functions, consider very
7003 carefully what you are doing, since you may be stuck with the names
7004 for far longer than you expect. The reason this document perpetuates
7005 these names is that the Emacs Lisp source code uses them, and if I did
7006 not use them, you would have a hard time reading the code; but do,
7007 please, try to avoid using these terms yourself. The people who come
7008 after you will be grateful to you.)
7010 When @code{car} and @code{cdr} are applied to a list made up of symbols,
7011 such as the list @code{(pine fir oak maple)}, the element of the list
7012 returned by the function @code{car} is the symbol @code{pine} without
7013 any parentheses around it. @code{pine} is the first element in the
7014 list. However, the @sc{cdr} of the list is a list itself, @code{(fir
7015 oak maple)}, as you can see by evaluating the following expressions in
7020 (car '(pine fir oak maple))
7022 (cdr '(pine fir oak maple))
7026 On the other hand, in a list of lists, the first element is itself a
7027 list. @code{car} returns this first element as a list. For example,
7028 the following list contains three sub-lists, a list of carnivores, a
7029 list of herbivores and a list of sea mammals:
7033 (car '((lion tiger cheetah)
7034 (gazelle antelope zebra)
7035 (whale dolphin seal)))
7040 In this example, the first element or @sc{car} of the list is the list of
7041 carnivores, @code{(lion tiger cheetah)}, and the rest of the list is
7042 @code{((gazelle antelope zebra) (whale dolphin seal))}.
7046 (cdr '((lion tiger cheetah)
7047 (gazelle antelope zebra)
7048 (whale dolphin seal)))
7052 It is worth saying again that @code{car} and @code{cdr} are
7053 non-destructive---that is, they do not modify or change lists to which
7054 they are applied. This is very important for how they are used.
7056 Also, in the first chapter, in the discussion about atoms, I said that
7057 in Lisp, ``certain kinds of atom, such as an array, can be separated
7058 into parts; but the mechanism for doing this is different from the
7059 mechanism for splitting a list. As far as Lisp is concerned, the
7060 atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The
7061 @code{car} and @code{cdr} functions are used for splitting lists and
7062 are considered fundamental to Lisp. Since they cannot split or gain
7063 access to the parts of an array, an array is considered an atom.
7064 Conversely, the other fundamental function, @code{cons}, can put
7065 together or construct a list, but not an array. (Arrays are handled
7066 by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU
7067 Emacs Lisp Reference Manual}.)
7069 @node cons, nthcdr, car & cdr, car cdr & cons
7070 @comment node-name, next, previous, up
7071 @section @code{cons}
7072 @findex cons, @r{introduced}
7074 The @code{cons} function constructs lists; it is the inverse of
7075 @code{car} and @code{cdr}. For example, @code{cons} can be used to make
7076 a four element list from the three element list, @code{(fir oak maple)}:
7079 (cons 'pine '(fir oak maple))
7084 After evaluating this list, you will see
7087 (pine fir oak maple)
7091 appear in the echo area. @code{cons} causes the creation of a new
7092 list in which the element is followed by the elements of the original
7095 We often say that `@code{cons} puts a new element at the beginning of
7096 a list; it attaches or pushes elements onto the list', but this
7097 phrasing can be misleading, since @code{cons} does not change an
7098 existing list, but creates a new one.
7100 Like @code{car} and @code{cdr}, @code{cons} is non-destructive.
7107 @node Build a list, length, cons, cons
7109 @unnumberedsubsec Build a list
7112 @code{cons} must have a list to attach to.@footnote{Actually, you can
7113 @code{cons} an element to an atom to produce a dotted pair. Dotted
7114 pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted
7115 Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You
7116 cannot start from absolutely nothing. If you are building a list, you
7117 need to provide at least an empty list at the beginning. Here is a
7118 series of @code{cons} expressions that build up a list of flowers. If
7119 you are reading this in Info in GNU Emacs, you can evaluate each of
7120 the expressions in the usual way; the value is printed in this text
7121 after @samp{@result{}}, which you may read as `evaluates to'.
7125 (cons 'buttercup ())
7126 @result{} (buttercup)
7130 (cons 'daisy '(buttercup))
7131 @result{} (daisy buttercup)
7135 (cons 'violet '(daisy buttercup))
7136 @result{} (violet daisy buttercup)
7140 (cons 'rose '(violet daisy buttercup))
7141 @result{} (rose violet daisy buttercup)
7146 In the first example, the empty list is shown as @code{()} and a list
7147 made up of @code{buttercup} followed by the empty list is constructed.
7148 As you can see, the empty list is not shown in the list that was
7149 constructed. All that you see is @code{(buttercup)}. The empty list is
7150 not counted as an element of a list because there is nothing in an empty
7151 list. Generally speaking, an empty list is invisible.
7153 The second example, @code{(cons 'daisy '(buttercup))} constructs a new,
7154 two element list by putting @code{daisy} in front of @code{buttercup};
7155 and the third example constructs a three element list by putting
7156 @code{violet} in front of @code{daisy} and @code{buttercup}.
7158 @node length, , Build a list, cons
7159 @comment node-name, next, previous, up
7160 @subsection Find the Length of a List: @code{length}
7163 You can find out how many elements there are in a list by using the Lisp
7164 function @code{length}, as in the following examples:
7168 (length '(buttercup))
7173 (length '(daisy buttercup))
7178 (length (cons 'violet '(daisy buttercup)))
7184 In the third example, the @code{cons} function is used to construct a
7185 three element list which is then passed to the @code{length} function as
7189 We can also use @code{length} to count the number of elements in an
7200 As you would expect, the number of elements in an empty list is zero.
7202 An interesting experiment is to find out what happens if you try to find
7203 the length of no list at all; that is, if you try to call @code{length}
7204 without giving it an argument, not even an empty list:
7212 What you see, if you evaluate this, is the error message
7215 Lisp error: (wrong-number-of-arguments length 0)
7219 This means that the function receives the wrong number of
7220 arguments, zero, when it expects some other number of arguments. In
7221 this case, one argument is expected, the argument being a list whose
7222 length the function is measuring. (Note that @emph{one} list is
7223 @emph{one} argument, even if the list has many elements inside it.)
7225 The part of the error message that says @samp{length} is the name of
7229 @code{length} is still a subroutine, but you need C-h f to discover that.
7231 In an earlier version:
7232 This is written with a special notation, @samp{#<subr},
7233 that indicates that the function @code{length} is one of the primitive
7234 functions written in C rather than in Emacs Lisp. (@samp{subr} is an
7235 abbreviation for `subroutine'.) @xref{What Is a Function, , What Is a
7236 Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more
7240 @node nthcdr, nth, cons, car cdr & cons
7241 @comment node-name, next, previous, up
7242 @section @code{nthcdr}
7245 The @code{nthcdr} function is associated with the @code{cdr} function.
7246 What it does is take the @sc{cdr} of a list repeatedly.
7248 If you take the @sc{cdr} of the list @code{(pine fir
7249 oak maple)}, you will be returned the list @code{(fir oak maple)}. If you
7250 repeat this on what was returned, you will be returned the list
7251 @code{(oak maple)}. (Of course, repeated @sc{cdr}ing on the original
7252 list will just give you the original @sc{cdr} since the function does
7253 not change the list. You need to evaluate the @sc{cdr} of the
7254 @sc{cdr} and so on.) If you continue this, eventually you will be
7255 returned an empty list, which in this case, instead of being shown as
7256 @code{()} is shown as @code{nil}.
7259 For review, here is a series of repeated @sc{cdr}s, the text following
7260 the @samp{@result{}} shows what is returned.
7264 (cdr '(pine fir oak maple))
7265 @result{}(fir oak maple)
7269 (cdr '(fir oak maple))
7270 @result{} (oak maple)
7295 You can also do several @sc{cdr}s without printing the values in
7300 (cdr (cdr '(pine fir oak maple)))
7301 @result{} (oak maple)
7306 In this example, the Lisp interpreter evaluates the innermost list first.
7307 The innermost list is quoted, so it just passes the list as it is to the
7308 innermost @code{cdr}. This @code{cdr} passes a list made up of the
7309 second and subsequent elements of the list to the outermost @code{cdr},
7310 which produces a list composed of the third and subsequent elements of
7311 the original list. In this example, the @code{cdr} function is repeated
7312 and returns a list that consists of the original list without its
7315 The @code{nthcdr} function does the same as repeating the call to
7316 @code{cdr}. In the following example, the argument 2 is passed to the
7317 function @code{nthcdr}, along with the list, and the value returned is
7318 the list without its first two items, which is exactly the same
7319 as repeating @code{cdr} twice on the list:
7323 (nthcdr 2 '(pine fir oak maple))
7324 @result{} (oak maple)
7329 Using the original four element list, we can see what happens when
7330 various numeric arguments are passed to @code{nthcdr}, including 0, 1,
7335 ;; @r{Leave the list as it was.}
7336 (nthcdr 0 '(pine fir oak maple))
7337 @result{} (pine fir oak maple)
7341 ;; @r{Return a copy without the first element.}
7342 (nthcdr 1 '(pine fir oak maple))
7343 @result{} (fir oak maple)
7347 ;; @r{Return a copy of the list without three elements.}
7348 (nthcdr 3 '(pine fir oak maple))
7353 ;; @r{Return a copy lacking all four elements.}
7354 (nthcdr 4 '(pine fir oak maple))
7359 ;; @r{Return a copy lacking all elements.}
7360 (nthcdr 5 '(pine fir oak maple))
7365 @node nth, setcar, nthcdr, car cdr & cons
7366 @comment node-name, next, previous, up
7370 The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly.
7371 The @code{nth} function takes the @sc{car} of the result returned by
7372 @code{nthcdr}. It returns the Nth element of the list.
7375 Thus, if it were not defined in C for speed, the definition of
7376 @code{nth} would be:
7381 "Returns the Nth element of LIST.
7382 N counts from zero. If LIST is not that long, nil is returned."
7383 (car (nthcdr n list)))
7388 (Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el},
7389 but its definition was redone in C in the 1980s.)
7391 The @code{nth} function returns a single element of a list.
7392 This can be very convenient.
7394 Note that the elements are numbered from zero, not one. That is to
7395 say, the first element of a list, its @sc{car} is the zeroth element.
7396 This is called `zero-based' counting and often bothers people who
7397 are accustomed to the first element in a list being number one, which
7405 (nth 0 '("one" "two" "three"))
7408 (nth 1 '("one" "two" "three"))
7413 It is worth mentioning that @code{nth}, like @code{nthcdr} and
7414 @code{cdr}, does not change the original list---the function is
7415 non-destructive. This is in sharp contrast to the @code{setcar} and
7416 @code{setcdr} functions.
7418 @node setcar, setcdr, nth, car cdr & cons
7419 @comment node-name, next, previous, up
7420 @section @code{setcar}
7423 As you might guess from their names, the @code{setcar} and @code{setcdr}
7424 functions set the @sc{car} or the @sc{cdr} of a list to a new value.
7425 They actually change the original list, unlike @code{car} and @code{cdr}
7426 which leave the original list as it was. One way to find out how this
7427 works is to experiment. We will start with the @code{setcar} function.
7430 First, we can make a list and then set the value of a variable to the
7431 list, using the @code{setq} function. Here is a list of animals:
7434 (setq animals '(antelope giraffe lion tiger))
7438 If you are reading this in Info inside of GNU Emacs, you can evaluate
7439 this expression in the usual fashion, by positioning the cursor after
7440 the expression and typing @kbd{C-x C-e}. (I'm doing this right here
7441 as I write this. This is one of the advantages of having the
7442 interpreter built into the computing environment. Incidentally, when
7443 there is nothing on the line after the final parentheses, such as a
7444 comment, point can be on the next line. Thus, if your cursor is in
7445 the first column of the next line, you do not need to move it.
7446 Indeed, Emacs permits any amount of white space after the final
7450 When we evaluate the variable @code{animals}, we see that it is bound to
7451 the list @code{(antelope giraffe lion tiger)}:
7456 @result{} (antelope giraffe lion tiger)
7461 Put another way, the variable @code{animals} points to the list
7462 @code{(antelope giraffe lion tiger)}.
7464 Next, evaluate the function @code{setcar} while passing it two
7465 arguments, the variable @code{animals} and the quoted symbol
7466 @code{hippopotamus}; this is done by writing the three element list
7467 @code{(setcar animals 'hippopotamus)} and then evaluating it in the
7471 (setcar animals 'hippopotamus)
7476 After evaluating this expression, evaluate the variable @code{animals}
7477 again. You will see that the list of animals has changed:
7482 @result{} (hippopotamus giraffe lion tiger)
7487 The first element on the list, @code{antelope} is replaced by
7488 @code{hippopotamus}.
7490 So we can see that @code{setcar} did not add a new element to the list
7491 as @code{cons} would have; it replaced @code{antelope} with
7492 @code{hippopotamus}; it @emph{changed} the list.
7494 @node setcdr, cons Exercise, setcar, car cdr & cons
7495 @comment node-name, next, previous, up
7496 @section @code{setcdr}
7499 The @code{setcdr} function is similar to the @code{setcar} function,
7500 except that the function replaces the second and subsequent elements of
7501 a list rather than the first element.
7503 (To see how to change the last element of a list, look ahead to
7504 @ref{kill-new function, , The @code{kill-new} function}, which uses
7505 the @code{nthcdr} and @code{setcdr} functions.)
7508 To see how this works, set the value of the variable to a list of
7509 domesticated animals by evaluating the following expression:
7512 (setq domesticated-animals '(horse cow sheep goat))
7517 If you now evaluate the list, you will be returned the list
7518 @code{(horse cow sheep goat)}:
7522 domesticated-animals
7523 @result{} (horse cow sheep goat)
7528 Next, evaluate @code{setcdr} with two arguments, the name of the
7529 variable which has a list as its value, and the list to which the
7530 @sc{cdr} of the first list will be set;
7533 (setcdr domesticated-animals '(cat dog))
7537 If you evaluate this expression, the list @code{(cat dog)} will appear
7538 in the echo area. This is the value returned by the function. The
7539 result we are interested in is the ``side effect'', which we can see by
7540 evaluating the variable @code{domesticated-animals}:
7544 domesticated-animals
7545 @result{} (horse cat dog)
7550 Indeed, the list is changed from @code{(horse cow sheep goat)} to
7551 @code{(horse cat dog)}. The @sc{cdr} of the list is changed from
7552 @code{(cow sheep goat)} to @code{(cat dog)}.
7554 @node cons Exercise, , setcdr, car cdr & cons
7557 Construct a list of four birds by evaluating several expressions with
7558 @code{cons}. Find out what happens when you @code{cons} a list onto
7559 itself. Replace the first element of the list of four birds with a
7560 fish. Replace the rest of that list with a list of other fish.
7562 @node Cutting & Storing Text, List Implementation, car cdr & cons, Top
7563 @comment node-name, next, previous, up
7564 @chapter Cutting and Storing Text
7565 @cindex Cutting and storing text
7566 @cindex Storing and cutting text
7567 @cindex Killing text
7568 @cindex Clipping text
7569 @cindex Erasing text
7570 @cindex Deleting text
7572 Whenever you cut or clip text out of a buffer with a `kill' command in
7573 GNU Emacs, it is stored in a list and you can bring it back with a
7576 (The use of the word `kill' in Emacs for processes which specifically
7577 @emph{do not} destroy the values of the entities is an unfortunate
7578 historical accident. A much more appropriate word would be `clip' since
7579 that is what the kill commands do; they clip text out of a buffer and
7580 put it into storage from which it can be brought back. I have often
7581 been tempted to replace globally all occurrences of `kill' in the Emacs
7582 sources with `clip' and all occurrences of `killed' with `clipped'.)
7588 * copy-region-as-kill::
7589 * Digression into C::
7591 * cons & search-fwd Review::
7592 * search Exercises::
7595 @node Storing Text, zap-to-char, Cutting & Storing Text, Cutting & Storing Text
7597 @unnumberedsec Storing Text in a List
7600 When text is cut out of a buffer, it is stored on a list. Successive
7601 pieces of text are stored on the list successively, so the list might
7605 ("a piece of text" "previous piece")
7610 The function @code{cons} can be used to create a new list from a piece
7611 of text (an `atom', to use the jargon) and an existing list, like
7616 (cons "another piece"
7617 '("a piece of text" "previous piece"))
7623 If you evaluate this expression, a list of three elements will appear in
7627 ("another piece" "a piece of text" "previous piece")
7630 With the @code{car} and @code{nthcdr} functions, you can retrieve
7631 whichever piece of text you want. For example, in the following code,
7632 @code{nthcdr 1 @dots{}} returns the list with the first item removed;
7633 and the @code{car} returns the first element of that remainder---the
7634 second element of the original list:
7638 (car (nthcdr 1 '("another piece"
7641 @result{} "a piece of text"
7645 The actual functions in Emacs are more complex than this, of course.
7646 The code for cutting and retrieving text has to be written so that
7647 Emacs can figure out which element in the list you want---the first,
7648 second, third, or whatever. In addition, when you get to the end of
7649 the list, Emacs should give you the first element of the list, rather
7650 than nothing at all.
7652 The list that holds the pieces of text is called the @dfn{kill ring}.
7653 This chapter leads up to a description of the kill ring and how it is
7654 used by first tracing how the @code{zap-to-char} function works. This
7655 function uses (or `calls') a function that invokes a function that
7656 manipulates the kill ring. Thus, before reaching the mountains, we
7657 climb the foothills.
7659 A subsequent chapter describes how text that is cut from the buffer is
7660 retrieved. @xref{Yanking, , Yanking Text Back}.
7662 @node zap-to-char, kill-region, Storing Text, Cutting & Storing Text
7663 @comment node-name, next, previous, up
7664 @section @code{zap-to-char}
7667 The @code{zap-to-char} function changed little between GNU Emacs
7668 version 19 and GNU Emacs version 22. However, @code{zap-to-char}
7669 calls another function, @code{kill-region}, which enjoyed a major
7672 The @code{kill-region} function in Emacs 19 is complex, but does not
7673 use code that is important at this time. We will skip it.
7675 The @code{kill-region} function in Emacs 22 is easier to read than the
7676 same function in Emacs 19 and introduces a very important concept,
7677 that of error handling. We will walk through the function.
7679 But first, let us look at the interactive @code{zap-to-char} function.
7682 * Complete zap-to-char::
7683 * zap-to-char interactive::
7684 * zap-to-char body::
7687 * Summing up zap-to-char::
7690 @node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char
7692 @unnumberedsubsec The Complete @code{zap-to-char} Implementation
7695 The @code{zap-to-char} function removes the text in the region between
7696 the location of the cursor (i.e., of point) up to and including the
7697 next occurrence of a specified character. The text that
7698 @code{zap-to-char} removes is put in the kill ring; and it can be
7699 retrieved from the kill ring by typing @kbd{C-y} (@code{yank}). If
7700 the command is given an argument, it removes text through that number
7701 of occurrences. Thus, if the cursor were at the beginning of this
7702 sentence and the character were @samp{s}, @samp{Thus} would be
7703 removed. If the argument were two, @samp{Thus, if the curs} would be
7704 removed, up to and including the @samp{s} in @samp{cursor}.
7706 If the specified character is not found, @code{zap-to-char} will say
7707 ``Search failed'', tell you the character you typed, and not remove
7710 In order to determine how much text to remove, @code{zap-to-char} uses
7711 a search function. Searches are used extensively in code that
7712 manipulates text, and we will focus attention on them as well as on the
7716 @c GNU Emacs version 19
7717 (defun zap-to-char (arg char) ; version 19 implementation
7718 "Kill up to and including ARG'th occurrence of CHAR.
7719 Goes backward if ARG is negative; error if CHAR not found."
7720 (interactive "*p\ncZap to char: ")
7721 (kill-region (point)
7724 (char-to-string char) nil nil arg)
7729 Here is the complete text of the version 22 implementation of the function:
7734 (defun zap-to-char (arg char)
7735 "Kill up to and including ARG'th occurrence of CHAR.
7736 Case is ignored if `case-fold-search' is non-nil in the current buffer.
7737 Goes backward if ARG is negative; error if CHAR not found."
7738 (interactive "p\ncZap to char: ")
7739 (if (char-table-p translation-table-for-input)
7740 (setq char (or (aref translation-table-for-input char) char)))
7741 (kill-region (point) (progn
7742 (search-forward (char-to-string char) nil nil arg)
7747 The documentation is thorough. You do need to know the jargon meaning
7750 @node zap-to-char interactive, zap-to-char body, Complete zap-to-char, zap-to-char
7751 @comment node-name, next, previous, up
7752 @subsection The @code{interactive} Expression
7755 The interactive expression in the @code{zap-to-char} command looks like
7759 (interactive "p\ncZap to char: ")
7762 The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies
7763 two different things. First, and most simply, is the @samp{p}.
7764 This part is separated from the next part by a newline, @samp{\n}.
7765 The @samp{p} means that the first argument to the function will be
7766 passed the value of a `processed prefix'. The prefix argument is
7767 passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If
7768 the function is called interactively without a prefix, 1 is passed to
7771 The second part of @code{"p\ncZap to char:@: "} is
7772 @samp{cZap to char:@: }. In this part, the lower case @samp{c}
7773 indicates that @code{interactive} expects a prompt and that the
7774 argument will be a character. The prompt follows the @samp{c} and is
7775 the string @samp{Zap to char:@: } (with a space after the colon to
7778 What all this does is prepare the arguments to @code{zap-to-char} so they
7779 are of the right type, and give the user a prompt.
7781 In a read-only buffer, the @code{zap-to-char} function copies the text
7782 to the kill ring, but does not remove it. The echo area displays a
7783 message saying that the buffer is read-only. Also, the terminal may
7784 beep or blink at you.
7786 @node zap-to-char body, search-forward, zap-to-char interactive, zap-to-char
7787 @comment node-name, next, previous, up
7788 @subsection The Body of @code{zap-to-char}
7790 The body of the @code{zap-to-char} function contains the code that
7791 kills (that is, removes) the text in the region from the current
7792 position of the cursor up to and including the specified character.
7794 The first part of the code looks like this:
7797 (if (char-table-p translation-table-for-input)
7798 (setq char (or (aref translation-table-for-input char) char)))
7799 (kill-region (point) (progn
7800 (search-forward (char-to-string char) nil nil arg)
7805 @code{char-table-p} is an hitherto unseen function. It determines
7806 whether its argument is a character table. When it is, it sets the
7807 character passed to @code{zap-to-char} to one of them, if that
7808 character exists, or to the character itself. (This becomes important
7809 for certain characters in non-European languages. The @code{aref}
7810 function extracts an element from an array. It is an array-specific
7811 function that is not described in this document. @xref{Arrays, ,
7812 Arrays, elisp, The GNU Emacs Lisp Reference Manual}.)
7815 @code{(point)} is the current position of the cursor.
7817 The next part of the code is an expression using @code{progn}. The body
7818 of the @code{progn} consists of calls to @code{search-forward} and
7821 It is easier to understand how @code{progn} works after learning about
7822 @code{search-forward}, so we will look at @code{search-forward} and
7823 then at @code{progn}.
7825 @node search-forward, progn, zap-to-char body, zap-to-char
7826 @comment node-name, next, previous, up
7827 @subsection The @code{search-forward} Function
7828 @findex search-forward
7830 The @code{search-forward} function is used to locate the
7831 zapped-for-character in @code{zap-to-char}. If the search is
7832 successful, @code{search-forward} leaves point immediately after the
7833 last character in the target string. (In @code{zap-to-char}, the
7834 target string is just one character long. @code{zap-to-char} uses the
7835 function @code{char-to-string} to ensure that the computer treats that
7836 character as a string.) If the search is backwards,
7837 @code{search-forward} leaves point just before the first character in
7838 the target. Also, @code{search-forward} returns @code{t} for true.
7839 (Moving point is therefore a `side effect'.)
7842 In @code{zap-to-char}, the @code{search-forward} function looks like this:
7845 (search-forward (char-to-string char) nil nil arg)
7848 The @code{search-forward} function takes four arguments:
7852 The first argument is the target, what is searched for. This must be a
7853 string, such as @samp{"z"}.
7855 As it happens, the argument passed to @code{zap-to-char} is a single
7856 character. Because of the way computers are built, the Lisp
7857 interpreter may treat a single character as being different from a
7858 string of characters. Inside the computer, a single character has a
7859 different electronic format than a string of one character. (A single
7860 character can often be recorded in the computer using exactly one
7861 byte; but a string may be longer, and the computer needs to be ready
7862 for this.) Since the @code{search-forward} function searches for a
7863 string, the character that the @code{zap-to-char} function receives as
7864 its argument must be converted inside the computer from one format to
7865 the other; otherwise the @code{search-forward} function will fail.
7866 The @code{char-to-string} function is used to make this conversion.
7869 The second argument bounds the search; it is specified as a position in
7870 the buffer. In this case, the search can go to the end of the buffer,
7871 so no bound is set and the second argument is @code{nil}.
7874 The third argument tells the function what it should do if the search
7875 fails---it can signal an error (and print a message) or it can return
7876 @code{nil}. A @code{nil} as the third argument causes the function to
7877 signal an error when the search fails.
7880 The fourth argument to @code{search-forward} is the repeat count---how
7881 many occurrences of the string to look for. This argument is optional
7882 and if the function is called without a repeat count, this argument is
7883 passed the value 1. If this argument is negative, the search goes
7888 In template form, a @code{search-forward} expression looks like this:
7892 (search-forward "@var{target-string}"
7893 @var{limit-of-search}
7894 @var{what-to-do-if-search-fails}
7899 We will look at @code{progn} next.
7901 @node progn, Summing up zap-to-char, search-forward, zap-to-char
7902 @comment node-name, next, previous, up
7903 @subsection The @code{progn} Special Form
7906 @code{progn} is a special form that causes each of its arguments to be
7907 evaluated in sequence and then returns the value of the last one. The
7908 preceding expressions are evaluated only for the side effects they
7909 perform. The values produced by them are discarded.
7912 The template for a @code{progn} expression is very simple:
7921 In @code{zap-to-char}, the @code{progn} expression has to do two things:
7922 put point in exactly the right position; and return the location of
7923 point so that @code{kill-region} will know how far to kill to.
7925 The first argument to the @code{progn} is @code{search-forward}. When
7926 @code{search-forward} finds the string, the function leaves point
7927 immediately after the last character in the target string. (In this
7928 case the target string is just one character long.) If the search is
7929 backwards, @code{search-forward} leaves point just before the first
7930 character in the target. The movement of point is a side effect.
7932 The second and last argument to @code{progn} is the expression
7933 @code{(point)}. This expression returns the value of point, which in
7934 this case will be the location to which it has been moved by
7935 @code{search-forward}. (In the source, a line that tells the function
7936 to go to the previous character, if it is going forward, was commented
7937 out in 1999; I don't remember whether that feature or mis-feature was
7938 ever a part of the distributed source.) The value of @code{point} is
7939 returned by the @code{progn} expression and is passed to
7940 @code{kill-region} as @code{kill-region}'s second argument.
7942 @node Summing up zap-to-char, , progn, zap-to-char
7943 @comment node-name, next, previous, up
7944 @subsection Summing up @code{zap-to-char}
7946 Now that we have seen how @code{search-forward} and @code{progn} work,
7947 we can see how the @code{zap-to-char} function works as a whole.
7949 The first argument to @code{kill-region} is the position of the cursor
7950 when the @code{zap-to-char} command is given---the value of point at
7951 that time. Within the @code{progn}, the search function then moves
7952 point to just after the zapped-to-character and @code{point} returns the
7953 value of this location. The @code{kill-region} function puts together
7954 these two values of point, the first one as the beginning of the region
7955 and the second one as the end of the region, and removes the region.
7957 The @code{progn} special form is necessary because the
7958 @code{kill-region} command takes two arguments; and it would fail if
7959 @code{search-forward} and @code{point} expressions were written in
7960 sequence as two additional arguments. The @code{progn} expression is
7961 a single argument to @code{kill-region} and returns the one value that
7962 @code{kill-region} needs for its second argument.
7964 @node kill-region, copy-region-as-kill, zap-to-char, Cutting & Storing Text
7965 @comment node-name, next, previous, up
7966 @section @code{kill-region}
7969 The @code{zap-to-char} function uses the @code{kill-region} function.
7970 This function clips text from a region and copies that text to
7971 the kill ring, from which it may be retrieved.
7976 (defun kill-region (beg end &optional yank-handler)
7977 "Kill (\"cut\") text between point and mark.
7978 This deletes the text from the buffer and saves it in the kill ring.
7979 The command \\[yank] can retrieve it from there.
7980 \(If you want to kill and then yank immediately, use \\[kill-ring-save].)
7982 If you want to append the killed region to the last killed text,
7983 use \\[append-next-kill] before \\[kill-region].
7985 If the buffer is read-only, Emacs will beep and refrain from deleting
7986 the text, but put the text in the kill ring anyway. This means that
7987 you can use the killing commands to copy text from a read-only buffer.
7989 This is the primitive for programs to kill text (as opposed to deleting it).
7990 Supply two arguments, character positions indicating the stretch of text
7992 Any command that calls this function is a \"kill command\".
7993 If the previous command was also a kill command,
7994 the text killed this time appends to the text killed last time
7995 to make one entry in the kill ring.
7997 In Lisp code, optional third arg YANK-HANDLER, if non-nil,
7998 specifies the yank-handler text property to be set on the killed
7999 text. See `insert-for-yank'."
8000 ;; Pass point first, then mark, because the order matters
8001 ;; when calling kill-append.
8002 (interactive (list (point) (mark)))
8003 (unless (and beg end)
8004 (error "The mark is not set now, so there is no region"))
8006 (let ((string (filter-buffer-substring beg end t)))
8007 (when string ;STRING is nil if BEG = END
8008 ;; Add that string to the kill ring, one way or another.
8009 (if (eq last-command 'kill-region)
8010 (kill-append string (< end beg) yank-handler)
8011 (kill-new string nil yank-handler)))
8012 (when (or string (eq last-command 'kill-region))
8013 (setq this-command 'kill-region))
8015 ((buffer-read-only text-read-only)
8016 ;; The code above failed because the buffer, or some of the characters
8017 ;; in the region, are read-only.
8018 ;; We should beep, in case the user just isn't aware of this.
8019 ;; However, there's no harm in putting
8020 ;; the region's text in the kill ring, anyway.
8021 (copy-region-as-kill beg end)
8022 ;; Set this-command now, so it will be set even if we get an error.
8023 (setq this-command 'kill-region)
8024 ;; This should barf, if appropriate, and give us the correct error.
8025 (if kill-read-only-ok
8026 (progn (message "Read only text copied to kill ring") nil)
8027 ;; Signal an error if the buffer is read-only.
8028 (barf-if-buffer-read-only)
8029 ;; If the buffer isn't read-only, the text is.
8030 (signal 'text-read-only (list (current-buffer)))))))
8033 The Emacs 22 version of that function uses @code{condition-case} and
8034 @code{copy-region-as-kill}, both of which we will explain.
8035 @code{condition-case} is an important special form.
8037 In essence, the @code{kill-region} function calls
8038 @code{condition-case}, which takes three arguments. In this function,
8039 the first argument does nothing. The second argument contains the
8040 code that does the work when all goes well. The third argument
8041 contains the code that is called in the event of an error.
8044 * Complete kill-region::
8049 @node Complete kill-region, condition-case, kill-region, kill-region
8051 @unnumberedsubsec The Complete @code{kill-region} Definition
8055 We will go through the @code{condition-case} code in a moment. First,
8056 let us look at the definition of @code{kill-region}, with comments
8062 (defun kill-region (beg end)
8063 "Kill (\"cut\") text between point and mark.
8064 This deletes the text from the buffer and saves it in the kill ring.
8065 The command \\[yank] can retrieve it from there. @dots{} "
8069 ;; @bullet{} Since order matters, pass point first.
8070 (interactive (list (point) (mark)))
8071 ;; @bullet{} And tell us if we cannot cut the text.
8072 ;; `unless' is an `if' without a then-part.
8073 (unless (and beg end)
8074 (error "The mark is not set now, so there is no region"))
8078 ;; @bullet{} `condition-case' takes three arguments.
8079 ;; If the first argument is nil, as it is here,
8080 ;; information about the error signal is not
8081 ;; stored for use by another function.
8086 ;; @bullet{} The second argument to `condition-case' tells the
8087 ;; Lisp interpreter what to do when all goes well.
8091 ;; It starts with a `let' function that extracts the string
8092 ;; and tests whether it exists. If so (that is what the
8093 ;; `when' checks), it calls an `if' function that determines
8094 ;; whether the previous command was another call to
8095 ;; `kill-region'; if it was, then the new text is appended to
8096 ;; the previous text; if not, then a different function,
8097 ;; `kill-new', is called.
8101 ;; The `kill-append' function concatenates the new string and
8102 ;; the old. The `kill-new' function inserts text into a new
8103 ;; item in the kill ring.
8107 ;; `when' is an `if' without an else-part. The second `when'
8108 ;; again checks whether the current string exists; in
8109 ;; addition, it checks whether the previous command was
8110 ;; another call to `kill-region'. If one or the other
8111 ;; condition is true, then it sets the current command to
8112 ;; be `kill-region'.
8115 (let ((string (filter-buffer-substring beg end t)))
8116 (when string ;STRING is nil if BEG = END
8117 ;; Add that string to the kill ring, one way or another.
8118 (if (eq last-command 'kill-region)
8121 ;; @minus{} `yank-handler' is an optional argument to
8122 ;; `kill-region' that tells the `kill-append' and
8123 ;; `kill-new' functions how deal with properties
8124 ;; added to the text, such as `bold' or `italics'.
8125 (kill-append string (< end beg) yank-handler)
8126 (kill-new string nil yank-handler)))
8127 (when (or string (eq last-command 'kill-region))
8128 (setq this-command 'kill-region))
8133 ;; @bullet{} The third argument to `condition-case' tells the interpreter
8134 ;; what to do with an error.
8137 ;; The third argument has a conditions part and a body part.
8138 ;; If the conditions are met (in this case,
8139 ;; if text or buffer are read-only)
8140 ;; then the body is executed.
8143 ;; The first part of the third argument is the following:
8144 ((buffer-read-only text-read-only) ;; the if-part
8145 ;; @dots{} the then-part
8146 (copy-region-as-kill beg end)
8149 ;; Next, also as part of the then-part, set this-command, so
8150 ;; it will be set in an error
8151 (setq this-command 'kill-region)
8152 ;; Finally, in the then-part, send a message if you may copy
8153 ;; the text to the kill ring without signally an error, but
8154 ;; don't if you may not.
8157 (if kill-read-only-ok
8158 (progn (message "Read only text copied to kill ring") nil)
8159 (barf-if-buffer-read-only)
8160 ;; If the buffer isn't read-only, the text is.
8161 (signal 'text-read-only (list (current-buffer)))))
8169 (defun kill-region (beg end)
8170 "Kill between point and mark.
8171 The text is deleted but saved in the kill ring."
8176 ;; 1. `condition-case' takes three arguments.
8177 ;; If the first argument is nil, as it is here,
8178 ;; information about the error signal is not
8179 ;; stored for use by another function.
8184 ;; 2. The second argument to `condition-case'
8185 ;; tells the Lisp interpreter what to do when all goes well.
8189 ;; The `delete-and-extract-region' function usually does the
8190 ;; work. If the beginning and ending of the region are both
8191 ;; the same, then the variable `string' will be empty, or nil
8192 (let ((string (delete-and-extract-region beg end)))
8196 ;; `when' is an `if' clause that cannot take an `else-part'.
8197 ;; Emacs normally sets the value of `last-command' to the
8198 ;; previous command.
8201 ;; `kill-append' concatenates the new string and the old.
8202 ;; `kill-new' inserts text into a new item in the kill ring.
8204 (if (eq last-command 'kill-region)
8205 ;; if true, prepend string
8206 (kill-append string (< end beg))
8208 (setq this-command 'kill-region))
8212 ;; 3. The third argument to `condition-case' tells the interpreter
8213 ;; what to do with an error.
8216 ;; The third argument has a conditions part and a body part.
8217 ;; If the conditions are met (in this case,
8218 ;; if text or buffer are read-only)
8219 ;; then the body is executed.
8222 ((buffer-read-only text-read-only) ;; this is the if-part
8224 (copy-region-as-kill beg end)
8227 (if kill-read-only-ok ;; usually this variable is nil
8228 (message "Read only text copied to kill ring")
8229 ;; or else, signal an error if the buffer is read-only;
8230 (barf-if-buffer-read-only)
8231 ;; and, in any case, signal that the text is read-only.
8232 (signal 'text-read-only (list (current-buffer)))))))
8237 @node condition-case, Lisp macro, Complete kill-region, kill-region
8238 @comment node-name, next, previous, up
8239 @subsection @code{condition-case}
8240 @findex condition-case
8242 As we have seen earlier (@pxref{Making Errors, , Generate an Error
8243 Message}), when the Emacs Lisp interpreter has trouble evaluating an
8244 expression, it provides you with help; in the jargon, this is called
8245 ``signaling an error''. Usually, the computer stops the program and
8246 shows you a message.
8248 However, some programs undertake complicated actions. They should not
8249 simply stop on an error. In the @code{kill-region} function, the most
8250 likely error is that you will try to kill text that is read-only and
8251 cannot be removed. So the @code{kill-region} function contains code
8252 to handle this circumstance. This code, which makes up the body of
8253 the @code{kill-region} function, is inside of a @code{condition-case}
8257 The template for @code{condition-case} looks like this:
8264 @var{error-handler}@dots{})
8268 The second argument, @var{bodyform}, is straightforward. The
8269 @code{condition-case} special form causes the Lisp interpreter to
8270 evaluate the code in @var{bodyform}. If no error occurs, the special
8271 form returns the code's value and produces the side-effects, if any.
8273 In short, the @var{bodyform} part of a @code{condition-case}
8274 expression determines what should happen when everything works
8277 However, if an error occurs, among its other actions, the function
8278 generating the error signal will define one or more error condition
8281 An error handler is the third argument to @code{condition case}.
8282 An error handler has two parts, a @var{condition-name} and a
8283 @var{body}. If the @var{condition-name} part of an error handler
8284 matches a condition name generated by an error, then the @var{body}
8285 part of the error handler is run.
8287 As you will expect, the @var{condition-name} part of an error handler
8288 may be either a single condition name or a list of condition names.
8290 Also, a complete @code{condition-case} expression may contain more
8291 than one error handler. When an error occurs, the first applicable
8294 Lastly, the first argument to the @code{condition-case} expression,
8295 the @var{var} argument, is sometimes bound to a variable that
8296 contains information about the error. However, if that argument is
8297 nil, as is the case in @code{kill-region}, that information is
8301 In brief, in the @code{kill-region} function, the code
8302 @code{condition-case} works like this:
8306 @var{If no errors}, @var{run only this code}
8307 @var{but}, @var{if errors}, @var{run this other code}.
8314 copy-region-as-kill is short, 12 lines, and uses
8315 filter-buffer-substring, which is longer, 39 lines
8316 and has delete-and-extract-region in it.
8317 delete-and-extract-region is written in C.
8319 see Initializing a Variable with @code{defvar}
8321 Initializing a Variable with @code{defvar} includes line 8350
8324 @node Lisp macro, , condition-case, kill-region
8325 @comment node-name, next, previous, up
8326 @subsection Lisp macro
8330 The part of the @code{condition-case} expression that is evaluated in
8331 the expectation that all goes well has a @code{when}. The code uses
8332 @code{when} to determine whether the @code{string} variable points to
8335 A @code{when} expression is simply a programmers' convenience. It is
8336 an @code{if} without the possibility of an else clause. In your mind,
8337 you can replace @code{when} with @code{if} and understand what goes
8338 on. That is what the Lisp interpreter does.
8340 Technically speaking, @code{when} is a Lisp macro. A Lisp @dfn{macro}
8341 enables you to define new control constructs and other language
8342 features. It tells the interpreter how to compute another Lisp
8343 expression which will in turn compute the value. In this case, the
8344 `other expression' is an @code{if} expression.
8346 The @code{kill-region} function definition also has an @code{unless}
8347 macro; it is the converse of @code{when}. The @code{unless} macro is
8348 an @code{if} without a then clause
8350 For more about Lisp macros, see @ref{Macros, , Macros, elisp, The GNU
8351 Emacs Lisp Reference Manual}. The C programming language also
8352 provides macros. These are different, but also useful.
8355 We will briefly look at C macros in
8356 @ref{Digression into C}.
8360 Regarding the @code{when} macro, in the @code{condition-case}
8361 expression, when the string has content, then another conditional
8362 expression is executed. This is an @code{if} with both a then-part
8367 (if (eq last-command 'kill-region)
8368 (kill-append string (< end beg) yank-handler)
8369 (kill-new string nil yank-handler))
8373 The then-part is evaluated if the previous command was another call to
8374 @code{kill-region}; if not, the else-part is evaluated.
8376 @code{yank-handler} is an optional argument to @code{kill-region} that
8377 tells the @code{kill-append} and @code{kill-new} functions how deal
8378 with properties added to the text, such as `bold' or `italics'.
8380 @code{last-command} is a variable that comes with Emacs that we have
8381 not seen before. Normally, whenever a function is executed, Emacs
8382 sets the value of @code{last-command} to the previous command.
8385 In this segment of the definition, the @code{if} expression checks
8386 whether the previous command was @code{kill-region}. If it was,
8389 (kill-append string (< end beg) yank-handler)
8393 concatenates a copy of the newly clipped text to the just previously
8394 clipped text in the kill ring.
8396 @node copy-region-as-kill, Digression into C, kill-region, Cutting & Storing Text
8397 @comment node-name, next, previous, up
8398 @section @code{copy-region-as-kill}
8399 @findex copy-region-as-kill
8402 The @code{copy-region-as-kill} function copies a region of text from a
8403 buffer and (via either @code{kill-append} or @code{kill-new}) saves it
8404 in the @code{kill-ring}.
8406 If you call @code{copy-region-as-kill} immediately after a
8407 @code{kill-region} command, Emacs appends the newly copied text to the
8408 previously copied text. This means that if you yank back the text, you
8409 get it all, from both this and the previous operation. On the other
8410 hand, if some other command precedes the @code{copy-region-as-kill},
8411 the function copies the text into a separate entry in the kill ring.
8414 * Complete copy-region-as-kill::
8415 * copy-region-as-kill body::
8418 @node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
8420 @unnumberedsubsec The complete @code{copy-region-as-kill} function definition
8424 Here is the complete text of the version 22 @code{copy-region-as-kill}
8429 (defun copy-region-as-kill (beg end)
8430 "Save the region as if killed, but don't kill it.
8431 In Transient Mark mode, deactivate the mark.
8432 If `interprogram-cut-function' is non-nil, also save the text for a window
8433 system cut and paste."
8437 (if (eq last-command 'kill-region)
8438 (kill-append (filter-buffer-substring beg end) (< end beg))
8439 (kill-new (filter-buffer-substring beg end)))
8442 (if transient-mark-mode
8443 (setq deactivate-mark t))
8449 As usual, this function can be divided into its component parts:
8453 (defun copy-region-as-kill (@var{argument-list})
8454 "@var{documentation}@dots{}"
8460 The arguments are @code{beg} and @code{end} and the function is
8461 interactive with @code{"r"}, so the two arguments must refer to the
8462 beginning and end of the region. If you have been reading though this
8463 document from the beginning, understanding these parts of a function is
8464 almost becoming routine.
8466 The documentation is somewhat confusing unless you remember that the
8467 word `kill' has a meaning different from usual. The `Transient Mark'
8468 and @code{interprogram-cut-function} comments explain certain
8471 After you once set a mark, a buffer always contains a region. If you
8472 wish, you can use Transient Mark mode to highlight the region
8473 temporarily. (No one wants to highlight the region all the time, so
8474 Transient Mark mode highlights it only at appropriate times. Many
8475 people turn off Transient Mark mode, so the region is never
8478 Also, a windowing system allows you to copy, cut, and paste among
8479 different programs. In the X windowing system, for example, the
8480 @code{interprogram-cut-function} function is @code{x-select-text},
8481 which works with the windowing system's equivalent of the Emacs kill
8484 The body of the @code{copy-region-as-kill} function starts with an
8485 @code{if} clause. What this clause does is distinguish between two
8486 different situations: whether or not this command is executed
8487 immediately after a previous @code{kill-region} command. In the first
8488 case, the new region is appended to the previously copied text.
8489 Otherwise, it is inserted into the beginning of the kill ring as a
8490 separate piece of text from the previous piece.
8492 The last two lines of the function prevent the region from lighting up
8493 if Transient Mark mode is turned on.
8495 The body of @code{copy-region-as-kill} merits discussion in detail.
8497 @node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill
8498 @comment node-name, next, previous, up
8499 @subsection The Body of @code{copy-region-as-kill}
8501 The @code{copy-region-as-kill} function works in much the same way as
8502 the @code{kill-region} function. Both are written so that two or more
8503 kills in a row combine their text into a single entry. If you yank
8504 back the text from the kill ring, you get it all in one piece.
8505 Moreover, kills that kill forward from the current position of the
8506 cursor are added to the end of the previously copied text and commands
8507 that copy text backwards add it to the beginning of the previously
8508 copied text. This way, the words in the text stay in the proper
8511 Like @code{kill-region}, the @code{copy-region-as-kill} function makes
8512 use of the @code{last-command} variable that keeps track of the
8513 previous Emacs command.
8516 * last-command & this-command::
8517 * kill-append function::
8518 * kill-new function::
8521 @node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body
8523 @unnumberedsubsubsec @code{last-command} and @code{this-command}
8526 Normally, whenever a function is executed, Emacs sets the value of
8527 @code{this-command} to the function being executed (which in this case
8528 would be @code{copy-region-as-kill}). At the same time, Emacs sets
8529 the value of @code{last-command} to the previous value of
8530 @code{this-command}.
8532 In the first part of the body of the @code{copy-region-as-kill}
8533 function, an @code{if} expression determines whether the value of
8534 @code{last-command} is @code{kill-region}. If so, the then-part of
8535 the @code{if} expression is evaluated; it uses the @code{kill-append}
8536 function to concatenate the text copied at this call to the function
8537 with the text already in the first element (the @sc{car}) of the kill
8538 ring. On the other hand, if the value of @code{last-command} is not
8539 @code{kill-region}, then the @code{copy-region-as-kill} function
8540 attaches a new element to the kill ring using the @code{kill-new}
8544 The @code{if} expression reads as follows; it uses @code{eq}:
8548 (if (eq last-command 'kill-region)
8550 (kill-append (filter-buffer-substring beg end) (< end beg))
8552 (kill-new (filter-buffer-substring beg end)))
8556 @findex filter-buffer-substring
8557 (The @code{filter-buffer-substring} function returns a filtered
8558 substring of the buffer, if any. Optionally---the arguments are not
8559 here, so neither is done---the function may delete the initial text or
8560 return the text without its properties; this function is a replacement
8561 for the older @code{buffer-substring} function, which came before text
8562 properties were implemented.)
8564 @findex eq @r{(example of use)}
8566 The @code{eq} function tests whether its first argument is the same Lisp
8567 object as its second argument. The @code{eq} function is similar to the
8568 @code{equal} function in that it is used to test for equality, but
8569 differs in that it determines whether two representations are actually
8570 the same object inside the computer, but with different names.
8571 @code{equal} determines whether the structure and contents of two
8572 expressions are the same.
8574 If the previous command was @code{kill-region}, then the Emacs Lisp
8575 interpreter calls the @code{kill-append} function
8577 @node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body
8578 @unnumberedsubsubsec The @code{kill-append} function
8582 The @code{kill-append} function looks like this:
8587 (defun kill-append (string before-p &optional yank-handler)
8588 "Append STRING to the end of the latest kill in the kill ring.
8589 If BEFORE-P is non-nil, prepend STRING to the kill.
8591 (let* ((cur (car kill-ring)))
8592 (kill-new (if before-p (concat string cur) (concat cur string))
8593 (or (= (length cur) 0)
8595 (get-text-property 0 'yank-handler cur)))
8602 (defun kill-append (string before-p)
8603 "Append STRING to the end of the latest kill in the kill ring.
8604 If BEFORE-P is non-nil, prepend STRING to the kill.
8605 If `interprogram-cut-function' is set, pass the resulting kill to
8607 (kill-new (if before-p
8608 (concat string (car kill-ring))
8609 (concat (car kill-ring) string))
8614 The @code{kill-append} function is fairly straightforward. It uses
8615 the @code{kill-new} function, which we will discuss in more detail in
8618 (Also, the function provides an optional argument called
8619 @code{yank-handler}; when invoked, this argument tells the function
8620 how to deal with properties added to the text, such as `bold' or
8623 @c !!! bug in GNU Emacs 22 version of kill-append ?
8624 It has a @code{let*} function to set the value of the first element of
8625 the kill ring to @code{cur}. (I do not know why the function does not
8626 use @code{let} instead; only one value is set in the expression.
8627 Perhaps this is a bug that produces no problems?)
8629 Consider the conditional that is one of the two arguments to
8630 @code{kill-new}. It uses @code{concat} to concatenate the new text to
8631 the @sc{car} of the kill ring. Whether it prepends or appends the
8632 text depends on the results of an @code{if} expression:
8636 (if before-p ; @r{if-part}
8637 (concat string cur) ; @r{then-part}
8638 (concat cur string)) ; @r{else-part}
8643 If the region being killed is before the region that was killed in the
8644 last command, then it should be prepended before the material that was
8645 saved in the previous kill; and conversely, if the killed text follows
8646 what was just killed, it should be appended after the previous text.
8647 The @code{if} expression depends on the predicate @code{before-p} to
8648 decide whether the newly saved text should be put before or after the
8649 previously saved text.
8651 The symbol @code{before-p} is the name of one of the arguments to
8652 @code{kill-append}. When the @code{kill-append} function is
8653 evaluated, it is bound to the value returned by evaluating the actual
8654 argument. In this case, this is the expression @code{(< end beg)}.
8655 This expression does not directly determine whether the killed text in
8656 this command is located before or after the kill text of the last
8657 command; what it does is determine whether the value of the variable
8658 @code{end} is less than the value of the variable @code{beg}. If it
8659 is, it means that the user is most likely heading towards the
8660 beginning of the buffer. Also, the result of evaluating the predicate
8661 expression, @code{(< end beg)}, will be true and the text will be
8662 prepended before the previous text. On the other hand, if the value of
8663 the variable @code{end} is greater than the value of the variable
8664 @code{beg}, the text will be appended after the previous text.
8667 When the newly saved text will be prepended, then the string with the new
8668 text will be concatenated before the old text:
8676 But if the text will be appended, it will be concatenated
8680 (concat cur string))
8683 To understand how this works, we first need to review the
8684 @code{concat} function. The @code{concat} function links together or
8685 unites two strings of text. The result is a string. For example:
8689 (concat "abc" "def")
8695 (car '("first element" "second element")))
8696 @result{} "new first element"
8699 '("first element" "second element")) " modified")
8700 @result{} "first element modified"
8704 We can now make sense of @code{kill-append}: it modifies the contents
8705 of the kill ring. The kill ring is a list, each element of which is
8706 saved text. The @code{kill-append} function uses the @code{kill-new}
8707 function which in turn uses the @code{setcar} function.
8709 @node kill-new function, , kill-append function, copy-region-as-kill body
8710 @unnumberedsubsubsec The @code{kill-new} function
8713 @c in GNU Emacs 22, additional documentation to kill-new:
8715 Optional third arguments YANK-HANDLER controls how the STRING is later
8716 inserted into a buffer; see `insert-for-yank' for details.
8717 When a yank handler is specified, STRING must be non-empty (the yank
8718 handler, if non-nil, is stored as a `yank-handler' text property on STRING).
8720 When the yank handler has a non-nil PARAM element, the original STRING
8721 argument is not used by `insert-for-yank'. However, since Lisp code
8722 may access and use elements from the kill ring directly, the STRING
8723 argument should still be a \"useful\" string for such uses."
8726 The @code{kill-new} function looks like this:
8730 (defun kill-new (string &optional replace yank-handler)
8731 "Make STRING the latest kill in the kill ring.
8732 Set `kill-ring-yank-pointer' to point to it.
8734 If `interprogram-cut-function' is non-nil, apply it to STRING.
8735 Optional second argument REPLACE non-nil means that STRING will replace
8736 the front of the kill ring, rather than being added to the list.
8740 (if (> (length string) 0)
8742 (put-text-property 0 (length string)
8743 'yank-handler yank-handler string))
8745 (signal 'args-out-of-range
8746 (list string "yank-handler specified for empty string"))))
8749 (if (fboundp 'menu-bar-update-yank-menu)
8750 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8753 (if (and replace kill-ring)
8754 (setcar kill-ring string)
8755 (push string kill-ring)
8756 (if (> (length kill-ring) kill-ring-max)
8757 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8760 (setq kill-ring-yank-pointer kill-ring)
8761 (if interprogram-cut-function
8762 (funcall interprogram-cut-function string (not replace))))
8767 (defun kill-new (string &optional replace)
8768 "Make STRING the latest kill in the kill ring.
8769 Set the kill-ring-yank pointer to point to it.
8770 If `interprogram-cut-function' is non-nil, apply it to STRING.
8771 Optional second argument REPLACE non-nil means that STRING will replace
8772 the front of the kill ring, rather than being added to the list."
8773 (and (fboundp 'menu-bar-update-yank-menu)
8774 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8775 (if (and replace kill-ring)
8776 (setcar kill-ring string)
8777 (setq kill-ring (cons string kill-ring))
8778 (if (> (length kill-ring) kill-ring-max)
8779 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8780 (setq kill-ring-yank-pointer kill-ring)
8781 (if interprogram-cut-function
8782 (funcall interprogram-cut-function string (not replace))))
8785 (Notice that the function is not interactive.)
8787 As usual, we can look at this function in parts.
8789 The function definition has an optional @code{yank-handler} argument,
8790 which when invoked tells the function how to deal with properties
8791 added to the text, such as `bold' or `italics'. We will skip that.
8794 The first line of the documentation makes sense:
8797 Make STRING the latest kill in the kill ring.
8801 Let's skip over the rest of the documentation for the moment.
8804 Also, let's skip over the initial @code{if} expression and those lines
8805 of code involving @code{menu-bar-update-yank-menu}. We will explain
8809 The critical lines are these:
8813 (if (and replace kill-ring)
8815 (setcar kill-ring string)
8819 (push string kill-ring)
8822 (setq kill-ring (cons string kill-ring))
8823 (if (> (length kill-ring) kill-ring-max)
8824 ;; @r{avoid overly long kill ring}
8825 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8828 (setq kill-ring-yank-pointer kill-ring)
8829 (if interprogram-cut-function
8830 (funcall interprogram-cut-function string (not replace))))
8834 The conditional test is @w{@code{(and replace kill-ring)}}.
8835 This will be true when two conditions are met: the kill ring has
8836 something in it, and the @code{replace} variable is true.
8839 When the @code{kill-append} function sets @code{replace} to be true
8840 and when the kill ring has at least one item in it, the @code{setcar}
8841 expression is executed:
8844 (setcar kill-ring string)
8847 The @code{setcar} function actually changes the first element of the
8848 @code{kill-ring} list to the value of @code{string}. It replaces the
8852 On the other hand, if the kill ring is empty, or replace is false, the
8853 else-part of the condition is executed:
8856 (push string kill-ring)
8861 @code{push} puts its first argument onto the second. It is similar to
8865 (setq kill-ring (cons string kill-ring))
8873 (add-to-list kill-ring string)
8877 When it is false, the expression first constructs a new version of the
8878 kill ring by prepending @code{string} to the existing kill ring as a
8879 new element (that is what the @code{push} does). Then it executes a
8880 second @code{if} clause. This second @code{if} clause keeps the kill
8881 ring from growing too long.
8883 Let's look at these two expressions in order.
8885 The @code{push} line of the else-part sets the new value of the kill
8886 ring to what results from adding the string being killed to the old
8889 We can see how this works with an example.
8895 (setq example-list '("here is a clause" "another clause"))
8900 After evaluating this expression with @kbd{C-x C-e}, you can evaluate
8901 @code{example-list} and see what it returns:
8906 @result{} ("here is a clause" "another clause")
8912 Now, we can add a new element on to this list by evaluating the
8913 following expression:
8914 @findex push, @r{example}
8917 (push "a third clause" example-list)
8922 When we evaluate @code{example-list}, we find its value is:
8927 @result{} ("a third clause" "here is a clause" "another clause")
8932 Thus, the third clause is added to the list by @code{push}.
8935 Now for the second part of the @code{if} clause. This expression
8936 keeps the kill ring from growing too long. It looks like this:
8940 (if (> (length kill-ring) kill-ring-max)
8941 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
8945 The code checks whether the length of the kill ring is greater than
8946 the maximum permitted length. This is the value of
8947 @code{kill-ring-max} (which is 60, by default). If the length of the
8948 kill ring is too long, then this code sets the last element of the
8949 kill ring to @code{nil}. It does this by using two functions,
8950 @code{nthcdr} and @code{setcdr}.
8952 We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
8953 It sets the @sc{cdr} of a list, just as @code{setcar} sets the
8954 @sc{car} of a list. In this case, however, @code{setcdr} will not be
8955 setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
8956 function is used to cause it to set the @sc{cdr} of the next to last
8957 element of the kill ring---this means that since the @sc{cdr} of the
8958 next to last element is the last element of the kill ring, it will set
8959 the last element of the kill ring.
8961 @findex nthcdr, @r{example}
8962 The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
8963 list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
8964 @dots{} It does this @var{N} times and returns the results.
8965 (@xref{nthcdr, , @code{nthcdr}}.)
8967 @findex setcdr, @r{example}
8968 Thus, if we had a four element list that was supposed to be three
8969 elements long, we could set the @sc{cdr} of the next to last element
8970 to @code{nil}, and thereby shorten the list. (If you set the last
8971 element to some other value than @code{nil}, which you could do, then
8972 you would not have shortened the list. @xref{setcdr, ,
8975 You can see shortening by evaluating the following three expressions
8976 in turn. First set the value of @code{trees} to @code{(maple oak pine
8977 birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
8978 and then find the value of @code{trees}:
8982 (setq trees '(maple oak pine birch))
8983 @result{} (maple oak pine birch)
8987 (setcdr (nthcdr 2 trees) nil)
8991 @result{} (maple oak pine)
8996 (The value returned by the @code{setcdr} expression is @code{nil} since
8997 that is what the @sc{cdr} is set to.)
8999 To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
9000 @sc{cdr} a number of times that is one less than the maximum permitted
9001 size of the kill ring and @code{setcdr} sets the @sc{cdr} of that
9002 element (which will be the rest of the elements in the kill ring) to
9003 @code{nil}. This prevents the kill ring from growing too long.
9006 The next to last expression in the @code{kill-new} function is
9009 (setq kill-ring-yank-pointer kill-ring)
9012 The @code{kill-ring-yank-pointer} is a global variable that is set to be
9013 the @code{kill-ring}.
9015 Even though the @code{kill-ring-yank-pointer} is called a
9016 @samp{pointer}, it is a variable just like the kill ring. However, the
9017 name has been chosen to help humans understand how the variable is used.
9020 Now, to return to an early expression in the body of the function:
9024 (if (fboundp 'menu-bar-update-yank-menu)
9025 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
9030 It starts with an @code{if} expression
9032 In this case, the expression tests first to see whether
9033 @code{menu-bar-update-yank-menu} exists as a function, and if so,
9034 calls it. The @code{fboundp} function returns true if the symbol it
9035 is testing has a function definition that `is not void'. If the
9036 symbol's function definition were void, we would receive an error
9037 message, as we did when we created errors intentionally (@pxref{Making
9038 Errors, , Generate an Error Message}).
9041 The then-part contains an expression whose first element is the
9042 function @code{and}.
9045 The @code{and} special form evaluates each of its arguments until one
9046 of the arguments returns a value of @code{nil}, in which case the
9047 @code{and} expression returns @code{nil}; however, if none of the
9048 arguments returns a value of @code{nil}, the value resulting from
9049 evaluating the last argument is returned. (Since such a value is not
9050 @code{nil}, it is considered true in Emacs Lisp.) In other words, an
9051 @code{and} expression returns a true value only if all its arguments
9052 are true. (@xref{Second Buffer Related Review}.)
9054 The expression determines whether the second argument to
9055 @code{menu-bar-update-yank-menu} is true or not.
9057 ;; If we're supposed to be extending an existing string, and that
9058 ;; string really is at the front of the menu, then update it in place.
9061 @code{menu-bar-update-yank-menu} is one of the functions that make it
9062 possible to use the `Select and Paste' menu in the Edit item of a menu
9063 bar; using a mouse, you can look at the various pieces of text you
9064 have saved and select one piece to paste.
9066 The last expression in the @code{kill-new} function adds the newly
9067 copied string to whatever facility exists for copying and pasting
9068 among different programs running in a windowing system. In the X
9069 Windowing system, for example, the @code{x-select-text} function takes
9070 the string and stores it in memory operated by X. You can paste the
9071 string in another program, such as an Xterm.
9074 The expression looks like this:
9078 (if interprogram-cut-function
9079 (funcall interprogram-cut-function string (not replace))))
9083 If an @code{interprogram-cut-function} exists, then Emacs executes
9084 @code{funcall}, which in turn calls its first argument as a function
9085 and passes the remaining arguments to it. (Incidentally, as far as I
9086 can see, this @code{if} expression could be replaced by an @code{and}
9087 expression similar to the one in the first part of the function.)
9089 We are not going to discuss windowing systems and other programs
9090 further, but merely note that this is a mechanism that enables GNU
9091 Emacs to work easily and well with other programs.
9093 This code for placing text in the kill ring, either concatenated with
9094 an existing element or as a new element, leads us to the code for
9095 bringing back text that has been cut out of the buffer---the yank
9096 commands. However, before discussing the yank commands, it is better
9097 to learn how lists are implemented in a computer. This will make
9098 clear such mysteries as the use of the term `pointer'. But before
9099 that, we will digress into C.
9102 @c is this true in Emacs 22? Does not seems to be
9104 (If the @w{@code{(< end beg))}}
9105 expression is true, @code{kill-append} prepends the string to the just
9106 previously clipped text. For a detailed discussion, see
9107 @ref{kill-append function, , The @code{kill-append} function}.)
9109 If you then yank back the text, i.e., `paste' it, you get both
9110 pieces of text at once. That way, if you delete two words in a row,
9111 and then yank them back, you get both words, in their proper order,
9112 with one yank. (The @w{@code{(< end beg))}} expression makes sure the
9115 On the other hand, if the previous command is not @code{kill-region},
9116 then the @code{kill-new} function is called, which adds the text to
9117 the kill ring as the latest item, and sets the
9118 @code{kill-ring-yank-pointer} variable to point to it.
9122 @c Evidently, changed for Emacs 22. The zap-to-char command does not
9123 @c use the delete-and-extract-region function
9125 2006 Oct 26, the Digression into C is now OK but should come after
9126 copy-region-as-kill and filter-buffer-substring
9130 copy-region-as-kill is short, 12 lines, and uses
9131 filter-buffer-substring, which is longer, 39 lines
9132 and has delete-and-extract-region in it.
9133 delete-and-extract-region is written in C.
9135 see Initializing a Variable with @code{defvar}
9138 @node Digression into C, defvar, copy-region-as-kill, Cutting & Storing Text
9139 @comment node-name, next, previous, up
9140 @section Digression into C
9141 @findex delete-and-extract-region
9142 @cindex C, a digression into
9143 @cindex Digression into C
9145 The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, ,
9146 @code{copy-region-as-kill}}) uses the @code{filter-buffer-substring}
9147 function, which in turn uses the @code{delete-and-extract-region}
9148 function. It removes the contents of a region and you cannot get them
9151 Unlike the other code discussed here, the
9152 @code{delete-and-extract-region} function is not written in Emacs
9153 Lisp; it is written in C and is one of the primitives of the GNU Emacs
9154 system. Since it is very simple, I will digress briefly from Lisp and
9157 @c GNU Emacs 22 in /usr/local/src/emacs/src/editfns.c
9158 @c the DEFUN for buffer-substring-no-properties
9161 Like many of the other Emacs primitives,
9162 @code{delete-and-extract-region} is written as an instance of a C
9163 macro, a macro being a template for code. The complete macro looks
9168 DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties,
9169 Sbuffer_substring_no_properties, 2, 2, 0,
9170 doc: /* Return the characters of part of the buffer,
9171 without the text properties.
9172 The two arguments START and END are character positions;
9173 they can be in either order. */)
9175 Lisp_Object start, end;
9179 validate_region (&start, &end);
9183 return make_buffer_string (b, e, 0);
9188 Without going into the details of the macro writing process, let me
9189 point out that this macro starts with the word @code{DEFUN}. The word
9190 @code{DEFUN} was chosen since the code serves the same purpose as
9191 @code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in
9192 @file{emacs/src/lisp.h}.)
9194 The word @code{DEFUN} is followed by seven parts inside of
9199 The first part is the name given to the function in Lisp,
9200 @code{delete-and-extract-region}.
9203 The second part is the name of the function in C,
9204 @code{Fdelete_and_extract_region}. By convention, it starts with
9205 @samp{F}. Since C does not use hyphens in names, underscores are used
9209 The third part is the name for the C constant structure that records
9210 information on this function for internal use. It is the name of the
9211 function in C but begins with an @samp{S} instead of an @samp{F}.
9214 The fourth and fifth parts specify the minimum and maximum number of
9215 arguments the function can have. This function demands exactly 2
9219 The sixth part is nearly like the argument that follows the
9220 @code{interactive} declaration in a function written in Lisp: a letter
9221 followed, perhaps, by a prompt. The only difference from the Lisp is
9222 when the macro is called with no arguments. Then you write a @code{0}
9223 (which is a `null string'), as in this macro.
9225 If you were to specify arguments, you would place them between
9226 quotation marks. The C macro for @code{goto-char} includes
9227 @code{"NGoto char: "} in this position to indicate that the function
9228 expects a raw prefix, in this case, a numerical location in a buffer,
9229 and provides a prompt.
9232 The seventh part is a documentation string, just like the one for a
9233 function written in Emacs Lisp, except that every newline must be
9234 written explicitly as @samp{\n} followed by a backslash and carriage
9238 Thus, the first two lines of documentation for @code{goto-char} are
9243 "Set point to POSITION, a number or marker.\n\
9244 Beginning of buffer is position (point-min), end is (point-max)."
9250 In a C macro, the formal parameters come next, with a statement of
9251 what kind of object they are, followed by what might be called the `body'
9252 of the macro. For @code{delete-and-extract-region} the `body'
9253 consists of the following four lines:
9257 validate_region (&start, &end);
9258 if (XINT (start) == XINT (end))
9259 return build_string ("");
9260 return del_range_1 (XINT (start), XINT (end), 1, 1);
9264 The @code{validate_region} function checks whether the values
9265 passed as the beginning and end of the region are the proper type and
9266 are within range. If the beginning and end positions are the same,
9267 then return and empty string.
9269 The @code{del_range_1} function actually deletes the text. It is a
9270 complex function we will not look into. It updates the buffer and
9271 does other things. However, it is worth looking at the two arguments
9272 passed to @code{del_range}. These are @w{@code{XINT (start)}} and
9273 @w{@code{XINT (end)}}.
9275 As far as the C language is concerned, @code{start} and @code{end} are
9276 two integers that mark the beginning and end of the region to be
9277 deleted@footnote{More precisely, and requiring more expert knowledge
9278 to understand, the two integers are of type `Lisp_Object', which can
9279 also be a C union instead of an integer type.}.
9281 In early versions of Emacs, these two numbers were thirty-two bits
9282 long, but the code is slowly being generalized to handle other
9283 lengths. Three of the available bits are used to specify the type of
9284 information; the remaining bits are used as `content'.
9286 @samp{XINT} is a C macro that extracts the relevant number from the
9287 longer collection of bits; the three other bits are discarded.
9290 The command in @code{delete-and-extract-region} looks like this:
9293 del_range_1 (XINT (start), XINT (end), 1, 1);
9297 It deletes the region between the beginning position, @code{start},
9298 and the ending position, @code{end}.
9300 From the point of view of the person writing Lisp, Emacs is all very
9301 simple; but hidden underneath is a great deal of complexity to make it
9304 @node defvar, cons & search-fwd Review, Digression into C, Cutting & Storing Text
9305 @comment node-name, next, previous, up
9306 @section Initializing a Variable with @code{defvar}
9308 @cindex Initializing a variable
9309 @cindex Variable initialization
9314 copy-region-as-kill is short, 12 lines, and uses
9315 filter-buffer-substring, which is longer, 39 lines
9316 and has delete-and-extract-region in it.
9317 delete-and-extract-region is written in C.
9319 see Initializing a Variable with @code{defvar}
9323 The @code{copy-region-as-kill} function is written in Emacs Lisp. Two
9324 functions within it, @code{kill-append} and @code{kill-new}, copy a
9325 region in a buffer and save it in a variable called the
9326 @code{kill-ring}. This section describes how the @code{kill-ring}
9327 variable is created and initialized using the @code{defvar} special
9330 (Again we note that the term @code{kill-ring} is a misnomer. The text
9331 that is clipped out of the buffer can be brought back; it is not a ring
9332 of corpses, but a ring of resurrectable text.)
9334 In Emacs Lisp, a variable such as the @code{kill-ring} is created and
9335 given an initial value by using the @code{defvar} special form. The
9336 name comes from ``define variable''.
9338 The @code{defvar} special form is similar to @code{setq} in that it sets
9339 the value of a variable. It is unlike @code{setq} in two ways: first,
9340 it only sets the value of the variable if the variable does not already
9341 have a value. If the variable already has a value, @code{defvar} does
9342 not override the existing value. Second, @code{defvar} has a
9343 documentation string.
9345 (Another special form, @code{defcustom}, is designed for variables
9346 that people customize. It has more features than @code{defvar}.
9347 (@xref{defcustom, , Setting Variables with @code{defcustom}}.)
9350 * See variable current value::
9351 * defvar and asterisk::
9354 @node See variable current value, defvar and asterisk, defvar, defvar
9356 @unnumberedsubsec Seeing the Current Value of a Variable
9359 You can see the current value of a variable, any variable, by using
9360 the @code{describe-variable} function, which is usually invoked by
9361 typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring}
9362 (followed by @key{RET}) when prompted, you will see what is in your
9363 current kill ring---this may be quite a lot! Conversely, if you have
9364 been doing nothing this Emacs session except read this document, you
9365 may have nothing in it. Also, you will see the documentation for
9371 List of killed text sequences.
9372 Since the kill ring is supposed to interact nicely with cut-and-paste
9373 facilities offered by window systems, use of this variable should
9376 interact nicely with `interprogram-cut-function' and
9377 `interprogram-paste-function'. The functions `kill-new',
9378 `kill-append', and `current-kill' are supposed to implement this
9379 interaction; you may want to use them instead of manipulating the kill
9385 The kill ring is defined by a @code{defvar} in the following way:
9389 (defvar kill-ring nil
9390 "List of killed text sequences.
9396 In this variable definition, the variable is given an initial value of
9397 @code{nil}, which makes sense, since if you have saved nothing, you want
9398 nothing back if you give a @code{yank} command. The documentation
9399 string is written just like the documentation string of a @code{defun}.
9400 As with the documentation string of the @code{defun}, the first line of
9401 the documentation should be a complete sentence, since some commands,
9402 like @code{apropos}, print only the first line of documentation.
9403 Succeeding lines should not be indented; otherwise they look odd when
9404 you use @kbd{C-h v} (@code{describe-variable}).
9406 @node defvar and asterisk, , See variable current value, defvar
9407 @subsection @code{defvar} and an asterisk
9408 @findex defvar @r{for a user customizable variable}
9409 @findex defvar @r{with an asterisk}
9411 In the past, Emacs used the @code{defvar} special form both for
9412 internal variables that you would not expect a user to change and for
9413 variables that you do expect a user to change. Although you can still
9414 use @code{defvar} for user customizable variables, please use
9415 @code{defcustom} instead, since that special form provides a path into
9416 the Customization commands. (@xref{defcustom, , Specifying Variables
9417 using @code{defcustom}}.)
9419 When you specified a variable using the @code{defvar} special form,
9420 you could distinguish a readily settable variable from others by
9421 typing an asterisk, @samp{*}, in the first column of its documentation
9422 string. For example:
9426 (defvar shell-command-default-error-buffer nil
9427 "*Buffer name for `shell-command' @dots{} error output.
9432 @findex set-variable
9434 You could (and still can) use the @code{set-variable} command to
9435 change the value of @code{shell-command-default-error-buffer}
9436 temporarily. However, options set using @code{set-variable} are set
9437 only for the duration of your editing session. The new values are not
9438 saved between sessions. Each time Emacs starts, it reads the original
9439 value, unless you change the value within your @file{.emacs} file,
9440 either by setting it manually or by using @code{customize}.
9441 @xref{Emacs Initialization, , Your @file{.emacs} File}.
9443 For me, the major use of the @code{set-variable} command is to suggest
9444 variables that I might want to set in my @file{.emacs} file. There
9445 are now more than 700 such variables --- far too many to remember
9446 readily. Fortunately, you can press @key{TAB} after calling the
9447 @code{M-x set-variable} command to see the list of variables.
9448 (@xref{Examining, , Examining and Setting Variables, emacs,
9449 The GNU Emacs Manual}.)
9452 @node cons & search-fwd Review, search Exercises, defvar, Cutting & Storing Text
9453 @comment node-name, next, previous, up
9456 Here is a brief summary of some recently introduced functions.
9461 @code{car} returns the first element of a list; @code{cdr} returns the
9462 second and subsequent elements of a list.
9469 (car '(1 2 3 4 5 6 7))
9471 (cdr '(1 2 3 4 5 6 7))
9472 @result{} (2 3 4 5 6 7)
9477 @code{cons} constructs a list by prepending its first argument to its
9491 @code{funcall} evaluates its first argument as a function. It passes
9492 its remaining arguments to its first argument.
9495 Return the result of taking @sc{cdr} `n' times on a list.
9503 The `rest of the rest', as it were.
9510 (nthcdr 3 '(1 2 3 4 5 6 7))
9517 @code{setcar} changes the first element of a list; @code{setcdr}
9518 changes the second and subsequent elements of a list.
9525 (setq triple '(1 2 3))
9532 (setcdr triple '("foo" "bar"))
9535 @result{} (37 "foo" "bar")
9540 Evaluate each argument in sequence and then return the value of the
9553 @item save-restriction
9554 Record whatever narrowing is in effect in the current buffer, if any,
9555 and restore that narrowing after evaluating the arguments.
9557 @item search-forward
9558 Search for a string, and if the string is found, move point. With a
9559 regular expression, use the similar @code{re-search-forward}.
9560 (@xref{Regexp Search, , Regular Expression Searches}, for an
9561 explanation of regular expression patterns and searches.)
9565 @code{search-forward} and @code{re-search-forward} take four
9570 The string or regular expression to search for.
9573 Optionally, the limit of the search.
9576 Optionally, what to do if the search fails, return @code{nil} or an
9580 Optionally, how many times to repeat the search; if negative, the
9581 search goes backwards.
9585 @itemx delete-and-extract-region
9586 @itemx copy-region-as-kill
9588 @code{kill-region} cuts the text between point and mark from the
9589 buffer and stores that text in the kill ring, so you can get it back
9592 @code{copy-region-as-kill} copies the text between point and mark into
9593 the kill ring, from which you can get it by yanking. The function
9594 does not cut or remove the text from the buffer.
9597 @code{delete-and-extract-region} removes the text between point and
9598 mark from the buffer and throws it away. You cannot get it back.
9599 (This is not an interactive command.)
9602 @node search Exercises, , cons & search-fwd Review, Cutting & Storing Text
9603 @section Searching Exercises
9607 Write an interactive function that searches for a string. If the
9608 search finds the string, leave point after it and display a message
9609 that says ``Found!''. (Do not use @code{search-forward} for the name
9610 of this function; if you do, you will overwrite the existing version of
9611 @code{search-forward} that comes with Emacs. Use a name such as
9612 @code{test-search} instead.)
9615 Write a function that prints the third element of the kill ring in the
9616 echo area, if any; if the kill ring does not contain a third element,
9617 print an appropriate message.
9620 @node List Implementation, Yanking, Cutting & Storing Text, Top
9621 @comment node-name, next, previous, up
9622 @chapter How Lists are Implemented
9623 @cindex Lists in a computer
9625 In Lisp, atoms are recorded in a straightforward fashion; if the
9626 implementation is not straightforward in practice, it is, nonetheless,
9627 straightforward in theory. The atom @samp{rose}, for example, is
9628 recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s},
9629 @samp{e}. A list, on the other hand, is kept differently. The mechanism
9630 is equally simple, but it takes a moment to get used to the idea. A
9631 list is kept using a series of pairs of pointers. In the series, the
9632 first pointer in each pair points to an atom or to another list, and the
9633 second pointer in each pair points to the next pair, or to the symbol
9634 @code{nil}, which marks the end of the list.
9636 A pointer itself is quite simply the electronic address of what is
9637 pointed to. Hence, a list is kept as a series of electronic addresses.
9640 * Lists diagrammed::
9641 * Symbols as Chest::
9645 @node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation
9647 @unnumberedsec Lists diagrammed
9650 For example, the list @code{(rose violet buttercup)} has three elements,
9651 @samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the
9652 electronic address of @samp{rose} is recorded in a segment of computer
9653 memory along with the address that gives the electronic address of where
9654 the atom @samp{violet} is located; and that address (the one that tells
9655 where @samp{violet} is located) is kept along with an address that tells
9656 where the address for the atom @samp{buttercup} is located.
9659 This sounds more complicated than it is and is easier seen in a diagram:
9661 @c clear print-postscript-figures
9662 @c !!! cons-cell-diagram #1
9666 ___ ___ ___ ___ ___ ___
9667 |___|___|--> |___|___|--> |___|___|--> nil
9670 --> rose --> violet --> buttercup
9674 @ifset print-postscript-figures
9677 @center @image{cons-1}
9678 %%%% old method of including an image
9679 % \input /usr/local/lib/tex/inputs/psfig.tex
9680 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}}
9685 @ifclear print-postscript-figures
9689 ___ ___ ___ ___ ___ ___
9690 |___|___|--> |___|___|--> |___|___|--> nil
9693 --> rose --> violet --> buttercup
9700 In the diagram, each box represents a word of computer memory that
9701 holds a Lisp object, usually in the form of a memory address. The boxes,
9702 i.e.@: the addresses, are in pairs. Each arrow points to what the address
9703 is the address of, either an atom or another pair of addresses. The
9704 first box is the electronic address of @samp{rose} and the arrow points
9705 to @samp{rose}; the second box is the address of the next pair of boxes,
9706 the first part of which is the address of @samp{violet} and the second
9707 part of which is the address of the next pair. The very last box
9708 points to the symbol @code{nil}, which marks the end of the list.
9711 When a variable is set to a list with a function such as @code{setq},
9712 it stores the address of the first box in the variable. Thus,
9713 evaluation of the expression
9716 (setq bouquet '(rose violet buttercup))
9721 creates a situation like this:
9723 @c cons-cell-diagram #2
9729 | ___ ___ ___ ___ ___ ___
9730 --> |___|___|--> |___|___|--> |___|___|--> nil
9733 --> rose --> violet --> buttercup
9737 @ifset print-postscript-figures
9740 @center @image{cons-2}
9741 %%%% old method of including an image
9742 % \input /usr/local/lib/tex/inputs/psfig.tex
9743 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}}
9748 @ifclear print-postscript-figures
9754 | ___ ___ ___ ___ ___ ___
9755 --> |___|___|--> |___|___|--> |___|___|--> nil
9758 --> rose --> violet --> buttercup
9765 In this example, the symbol @code{bouquet} holds the address of the first
9769 This same list can be illustrated in a different sort of box notation
9772 @c cons-cell-diagram #2a
9778 | -------------- --------------- ----------------
9779 | | car | cdr | | car | cdr | | car | cdr |
9780 -->| rose | o------->| violet | o------->| butter- | nil |
9781 | | | | | | | cup | |
9782 -------------- --------------- ----------------
9786 @ifset print-postscript-figures
9789 @center @image{cons-2a}
9790 %%%% old method of including an image
9791 % \input /usr/local/lib/tex/inputs/psfig.tex
9792 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}}
9797 @ifclear print-postscript-figures
9803 | -------------- --------------- ----------------
9804 | | car | cdr | | car | cdr | | car | cdr |
9805 -->| rose | o------->| violet | o------->| butter- | nil |
9806 | | | | | | | cup | |
9807 -------------- --------------- ----------------
9813 (Symbols consist of more than pairs of addresses, but the structure of
9814 a symbol is made up of addresses. Indeed, the symbol @code{bouquet}
9815 consists of a group of address-boxes, one of which is the address of
9816 the printed word @samp{bouquet}, a second of which is the address of a
9817 function definition attached to the symbol, if any, a third of which
9818 is the address of the first pair of address-boxes for the list
9819 @code{(rose violet buttercup)}, and so on. Here we are showing that
9820 the symbol's third address-box points to the first pair of
9821 address-boxes for the list.)
9823 If a symbol is set to the @sc{cdr} of a list, the list itself is not
9824 changed; the symbol simply has an address further down the list. (In
9825 the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus,
9826 evaluation of the following expression
9829 (setq flowers (cdr bouquet))
9836 @c cons-cell-diagram #3
9843 | ___ ___ | ___ ___ ___ ___
9844 --> | | | --> | | | | | |
9845 |___|___|----> |___|___|--> |___|___|--> nil
9848 --> rose --> violet --> buttercup
9853 @ifset print-postscript-figures
9856 @center @image{cons-3}
9857 %%%% old method of including an image
9858 % \input /usr/local/lib/tex/inputs/psfig.tex
9859 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}}
9864 @ifclear print-postscript-figures
9871 | ___ ___ | ___ ___ ___ ___
9872 --> | | | --> | | | | | |
9873 |___|___|----> |___|___|--> |___|___|--> nil
9876 --> rose --> violet --> buttercup
9884 The value of @code{flowers} is @code{(violet buttercup)}, which is
9885 to say, the symbol @code{flowers} holds the address of the pair of
9886 address-boxes, the first of which holds the address of @code{violet},
9887 and the second of which holds the address of @code{buttercup}.
9889 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
9890 pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp
9891 Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair
9892 Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more
9893 information about cons cells and dotted pairs.
9896 The function @code{cons} adds a new pair of addresses to the front of
9897 a series of addresses like that shown above. For example, evaluating
9901 (setq bouquet (cons 'lily bouquet))
9908 @c cons-cell-diagram #4
9915 | ___ ___ ___ ___ | ___ ___ ___ ___
9916 --> | | | | | | --> | | | | | |
9917 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9920 --> lily --> rose --> violet --> buttercup
9925 @ifset print-postscript-figures
9928 @center @image{cons-4}
9929 %%%% old method of including an image
9930 % \input /usr/local/lib/tex/inputs/psfig.tex
9931 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}}
9936 @ifclear print-postscript-figures
9943 | ___ ___ ___ ___ | ___ ___ ___ ___
9944 --> | | | | | | --> | | | | | |
9945 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9948 --> lily --> rose --> violet --> buttercup
9957 However, this does not change the value of the symbol
9958 @code{flowers}, as you can see by evaluating the following,
9961 (eq (cdr (cdr bouquet)) flowers)
9965 which returns @code{t} for true.
9967 Until it is reset, @code{flowers} still has the value
9968 @code{(violet buttercup)}; that is, it has the address of the cons
9969 cell whose first address is of @code{violet}. Also, this does not
9970 alter any of the pre-existing cons cells; they are all still there.
9972 Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address
9973 of the next cons cell in the series; to get the @sc{car} of a list,
9974 you get the address of the first element of the list; to @code{cons} a
9975 new element on a list, you add a new cons cell to the front of the list.
9976 That is all there is to it! The underlying structure of Lisp is
9979 And what does the last address in a series of cons cells refer to? It
9980 is the address of the empty list, of @code{nil}.
9982 In summary, when a Lisp variable is set to a value, it is provided with
9983 the address of the list to which the variable refers.
9985 @node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation
9986 @section Symbols as a Chest of Drawers
9987 @cindex Symbols as a Chest of Drawers
9988 @cindex Chest of Drawers, metaphor for a symbol
9989 @cindex Drawers, Chest of, metaphor for a symbol
9991 In an earlier section, I suggested that you might imagine a symbol as
9992 being a chest of drawers. The function definition is put in one
9993 drawer, the value in another, and so on. What is put in the drawer
9994 holding the value can be changed without affecting the contents of the
9995 drawer holding the function definition, and vice-verse.
9997 Actually, what is put in each drawer is the address of the value or
9998 function definition. It is as if you found an old chest in the attic,
9999 and in one of its drawers you found a map giving you directions to
10000 where the buried treasure lies.
10002 (In addition to its name, symbol definition, and variable value, a
10003 symbol has a `drawer' for a @dfn{property list} which can be used to
10004 record other information. Property lists are not discussed here; see
10005 @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp
10006 Reference Manual}.)
10009 Here is a fanciful representation:
10011 @c chest-of-drawers diagram
10016 Chest of Drawers Contents of Drawers
10020 ---------------------
10021 | directions to | [map to]
10022 | symbol name | bouquet
10024 +---------------------+
10026 | symbol definition | [none]
10028 +---------------------+
10029 | directions to | [map to]
10030 | variable value | (rose violet buttercup)
10032 +---------------------+
10034 | property list | [not described here]
10036 +---------------------+
10042 @ifset print-postscript-figures
10045 @center @image{drawers}
10046 %%%% old method of including an image
10047 % \input /usr/local/lib/tex/inputs/psfig.tex
10048 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}}
10053 @ifclear print-postscript-figures
10058 Chest of Drawers Contents of Drawers
10062 ---------------------
10063 | directions to | [map to]
10064 | symbol name | bouquet
10066 +---------------------+
10068 | symbol definition | [none]
10070 +---------------------+
10071 | directions to | [map to]
10072 | variable value | (rose violet buttercup)
10074 +---------------------+
10076 | property list | [not described here]
10078 +---------------------+
10086 @node List Exercise, , Symbols as Chest, List Implementation
10089 Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two
10090 more flowers on to this list and set this new list to
10091 @code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish.
10092 What does the @code{more-flowers} list now contain?
10094 @node Yanking, Loops & Recursion, List Implementation, Top
10095 @comment node-name, next, previous, up
10096 @chapter Yanking Text Back
10098 @cindex Text retrieval
10099 @cindex Retrieving text
10100 @cindex Pasting text
10102 Whenever you cut text out of a buffer with a `kill' command in GNU Emacs,
10103 you can bring it back with a `yank' command. The text that is cut out of
10104 the buffer is put in the kill ring and the yank commands insert the
10105 appropriate contents of the kill ring back into a buffer (not necessarily
10106 the original buffer).
10108 A simple @kbd{C-y} (@code{yank}) command inserts the first item from
10109 the kill ring into the current buffer. If the @kbd{C-y} command is
10110 followed immediately by @kbd{M-y}, the first element is replaced by
10111 the second element. Successive @kbd{M-y} commands replace the second
10112 element with the third, fourth, or fifth element, and so on. When the
10113 last element in the kill ring is reached, it is replaced by the first
10114 element and the cycle is repeated. (Thus the kill ring is called a
10115 `ring' rather than just a `list'. However, the actual data structure
10116 that holds the text is a list.
10117 @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the
10118 list is handled as a ring.)
10121 * Kill Ring Overview::
10122 * kill-ring-yank-pointer::
10123 * yank nthcdr Exercises::
10126 @node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking
10127 @comment node-name, next, previous, up
10128 @section Kill Ring Overview
10129 @cindex Kill ring overview
10131 The kill ring is a list of textual strings. This is what it looks like:
10134 ("some text" "a different piece of text" "yet more text")
10137 If this were the contents of my kill ring and I pressed @kbd{C-y}, the
10138 string of characters saying @samp{some text} would be inserted in this
10139 buffer where my cursor is located.
10141 The @code{yank} command is also used for duplicating text by copying it.
10142 The copied text is not cut from the buffer, but a copy of it is put on the
10143 kill ring and is inserted by yanking it back.
10145 Three functions are used for bringing text back from the kill ring:
10146 @code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop},
10147 which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer},
10148 which is used by the two other functions.
10150 These functions refer to the kill ring through a variable called the
10151 @code{kill-ring-yank-pointer}. Indeed, the insertion code for both the
10152 @code{yank} and @code{yank-pop} functions is:
10155 (insert (car kill-ring-yank-pointer))
10159 (Well, no more. In GNU Emacs 22, the function has been replaced by
10160 @code{insert-for-yank} which calls @code{insert-for-yank-1}
10161 repetitively for each @code{yank-handler} segment. In turn,
10162 @code{insert-for-yank-1} strips text properties from the inserted text
10163 according to @code{yank-excluded-properties}. Otherwise, it is just
10164 like @code{insert}. We will stick with plain @code{insert} since it
10165 is easier to understand.)
10167 To begin to understand how @code{yank} and @code{yank-pop} work, it is
10168 first necessary to look at the @code{kill-ring-yank-pointer} variable.
10170 @node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking
10171 @comment node-name, next, previous, up
10172 @section The @code{kill-ring-yank-pointer} Variable
10174 @code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is
10175 a variable. It points to something by being bound to the value of what
10176 it points to, like any other Lisp variable.
10179 Thus, if the value of the kill ring is:
10182 ("some text" "a different piece of text" "yet more text")
10187 and the @code{kill-ring-yank-pointer} points to the second clause, the
10188 value of @code{kill-ring-yank-pointer} is:
10191 ("a different piece of text" "yet more text")
10194 As explained in the previous chapter (@pxref{List Implementation}), the
10195 computer does not keep two different copies of the text being pointed to
10196 by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The
10197 words ``a different piece of text'' and ``yet more text'' are not
10198 duplicated. Instead, the two Lisp variables point to the same pieces of
10199 text. Here is a diagram:
10201 @c cons-cell-diagram #5
10205 kill-ring kill-ring-yank-pointer
10207 | ___ ___ | ___ ___ ___ ___
10208 ---> | | | --> | | | | | |
10209 |___|___|----> |___|___|--> |___|___|--> nil
10212 | | --> "yet more text"
10214 | --> "a different piece of text"
10221 @ifset print-postscript-figures
10224 @center @image{cons-5}
10225 %%%% old method of including an image
10226 % \input /usr/local/lib/tex/inputs/psfig.tex
10227 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}}
10232 @ifclear print-postscript-figures
10236 kill-ring kill-ring-yank-pointer
10238 | ___ ___ | ___ ___ ___ ___
10239 ---> | | | --> | | | | | |
10240 |___|___|----> |___|___|--> |___|___|--> nil
10243 | | --> "yet more text"
10245 | --> "a different piece of text
10254 Both the variable @code{kill-ring} and the variable
10255 @code{kill-ring-yank-pointer} are pointers. But the kill ring itself is
10256 usually described as if it were actually what it is composed of. The
10257 @code{kill-ring} is spoken of as if it were the list rather than that it
10258 points to the list. Conversely, the @code{kill-ring-yank-pointer} is
10259 spoken of as pointing to a list.
10261 These two ways of talking about the same thing sound confusing at first but
10262 make sense on reflection. The kill ring is generally thought of as the
10263 complete structure of data that holds the information of what has recently
10264 been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer}
10265 on the other hand, serves to indicate---that is, to `point to'---that part
10266 of the kill ring of which the first element (the @sc{car}) will be
10270 In GNU Emacs 22, the @code{kill-new} function calls
10272 @code{(setq kill-ring-yank-pointer kill-ring)}
10274 (defun rotate-yank-pointer (arg)
10275 "Rotate the yanking point in the kill ring.
10276 With argument, rotate that many kills forward (or backward, if negative)."
10278 (current-kill arg))
10280 (defun current-kill (n &optional do-not-move)
10281 "Rotate the yanking point by N places, and then return that kill.
10282 If N is zero, `interprogram-paste-function' is set, and calling it
10283 returns a string, then that string is added to the front of the
10284 kill ring and returned as the latest kill.
10285 If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
10286 yanking point; just return the Nth kill forward."
10287 (let ((interprogram-paste (and (= n 0)
10288 interprogram-paste-function
10289 (funcall interprogram-paste-function))))
10290 (if interprogram-paste
10292 ;; Disable the interprogram cut function when we add the new
10293 ;; text to the kill ring, so Emacs doesn't try to own the
10294 ;; selection, with identical text.
10295 (let ((interprogram-cut-function nil))
10296 (kill-new interprogram-paste))
10297 interprogram-paste)
10298 (or kill-ring (error "Kill ring is empty"))
10299 (let ((ARGth-kill-element
10300 (nthcdr (mod (- n (length kill-ring-yank-pointer))
10301 (length kill-ring))
10304 (setq kill-ring-yank-pointer ARGth-kill-element))
10305 (car ARGth-kill-element)))))
10310 @node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking
10311 @section Exercises with @code{yank} and @code{nthcdr}
10315 Using @kbd{C-h v} (@code{describe-variable}), look at the value of
10316 your kill ring. Add several items to your kill ring; look at its
10317 value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way
10318 around the kill ring. How many items were in your kill ring? Find
10319 the value of @code{kill-ring-max}. Was your kill ring full, or could
10320 you have kept more blocks of text within it?
10323 Using @code{nthcdr} and @code{car}, construct a series of expressions
10324 to return the first, second, third, and fourth elements of a list.
10327 @node Loops & Recursion, Regexp Search, Yanking, Top
10328 @comment node-name, next, previous, up
10329 @chapter Loops and Recursion
10330 @cindex Loops and recursion
10331 @cindex Recursion and loops
10332 @cindex Repetition (loops)
10334 Emacs Lisp has two primary ways to cause an expression, or a series of
10335 expressions, to be evaluated repeatedly: one uses a @code{while}
10336 loop, and the other uses @dfn{recursion}.
10338 Repetition can be very valuable. For example, to move forward four
10339 sentences, you need only write a program that will move forward one
10340 sentence and then repeat the process four times. Since a computer does
10341 not get bored or tired, such repetitive action does not have the
10342 deleterious effects that excessive or the wrong kinds of repetition can
10345 People mostly write Emacs Lisp functions using @code{while} loops and
10346 their kin; but you can use recursion, which provides a very powerful
10347 way to think about and then to solve problems@footnote{You can write
10348 recursive functions to be frugal or wasteful of mental or computer
10349 resources; as it happens, methods that people find easy---that are
10350 frugal of `mental resources'---sometimes use considerable computer
10351 resources. Emacs was designed to run on machines that we now consider
10352 limited and its default settings are conservative. You may want to
10353 increase the values of @code{max-specpdl-size} and
10354 @code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to
10355 15 and 30 times their default value.}.
10361 * Looping exercise::
10364 @node while, dolist dotimes, Loops & Recursion, Loops & Recursion
10365 @comment node-name, next, previous, up
10366 @section @code{while}
10370 The @code{while} special form tests whether the value returned by
10371 evaluating its first argument is true or false. This is similar to what
10372 the Lisp interpreter does with an @code{if}; what the interpreter does
10373 next, however, is different.
10375 In a @code{while} expression, if the value returned by evaluating the
10376 first argument is false, the Lisp interpreter skips the rest of the
10377 expression (the @dfn{body} of the expression) and does not evaluate it.
10378 However, if the value is true, the Lisp interpreter evaluates the body
10379 of the expression and then again tests whether the first argument to
10380 @code{while} is true or false. If the value returned by evaluating the
10381 first argument is again true, the Lisp interpreter again evaluates the
10382 body of the expression.
10385 The template for a @code{while} expression looks like this:
10389 (while @var{true-or-false-test}
10395 * Looping with while::
10397 * print-elements-of-list::
10398 * Incrementing Loop::
10399 * Decrementing Loop::
10402 @node Looping with while, Loop Example, while, while
10404 @unnumberedsubsec Looping with @code{while}
10407 So long as the true-or-false-test of the @code{while} expression
10408 returns a true value when it is evaluated, the body is repeatedly
10409 evaluated. This process is called a loop since the Lisp interpreter
10410 repeats the same thing again and again, like an airplane doing a loop.
10411 When the result of evaluating the true-or-false-test is false, the
10412 Lisp interpreter does not evaluate the rest of the @code{while}
10413 expression and `exits the loop'.
10415 Clearly, if the value returned by evaluating the first argument to
10416 @code{while} is always true, the body following will be evaluated
10417 again and again @dots{} and again @dots{} forever. Conversely, if the
10418 value returned is never true, the expressions in the body will never
10419 be evaluated. The craft of writing a @code{while} loop consists of
10420 choosing a mechanism such that the true-or-false-test returns true
10421 just the number of times that you want the subsequent expressions to
10422 be evaluated, and then have the test return false.
10424 The value returned by evaluating a @code{while} is the value of the
10425 true-or-false-test. An interesting consequence of this is that a
10426 @code{while} loop that evaluates without error will return @code{nil}
10427 or false regardless of whether it has looped 1 or 100 times or none at
10428 all. A @code{while} expression that evaluates successfully never
10429 returns a true value! What this means is that @code{while} is always
10430 evaluated for its side effects, which is to say, the consequences of
10431 evaluating the expressions within the body of the @code{while} loop.
10432 This makes sense. It is not the mere act of looping that is desired,
10433 but the consequences of what happens when the expressions in the loop
10434 are repeatedly evaluated.
10436 @node Loop Example, print-elements-of-list, Looping with while, while
10437 @comment node-name, next, previous, up
10438 @subsection A @code{while} Loop and a List
10440 A common way to control a @code{while} loop is to test whether a list
10441 has any elements. If it does, the loop is repeated; but if it does not,
10442 the repetition is ended. Since this is an important technique, we will
10443 create a short example to illustrate it.
10445 A simple way to test whether a list has elements is to evaluate the
10446 list: if it has no elements, it is an empty list and will return the
10447 empty list, @code{()}, which is a synonym for @code{nil} or false. On
10448 the other hand, a list with elements will return those elements when it
10449 is evaluated. Since Emacs Lisp considers as true any value that is not
10450 @code{nil}, a list that returns elements will test true in a
10454 For example, you can set the variable @code{empty-list} to @code{nil} by
10455 evaluating the following @code{setq} expression:
10458 (setq empty-list ())
10462 After evaluating the @code{setq} expression, you can evaluate the
10463 variable @code{empty-list} in the usual way, by placing the cursor after
10464 the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your
10471 On the other hand, if you set a variable to be a list with elements, the
10472 list will appear when you evaluate the variable, as you can see by
10473 evaluating the following two expressions:
10477 (setq animals '(gazelle giraffe lion tiger))
10483 Thus, to create a @code{while} loop that tests whether there are any
10484 items in the list @code{animals}, the first part of the loop will be
10495 When the @code{while} tests its first argument, the variable
10496 @code{animals} is evaluated. It returns a list. So long as the list
10497 has elements, the @code{while} considers the results of the test to be
10498 true; but when the list is empty, it considers the results of the test
10501 To prevent the @code{while} loop from running forever, some mechanism
10502 needs to be provided to empty the list eventually. An oft-used
10503 technique is to have one of the subsequent forms in the @code{while}
10504 expression set the value of the list to be the @sc{cdr} of the list.
10505 Each time the @code{cdr} function is evaluated, the list will be made
10506 shorter, until eventually only the empty list will be left. At this
10507 point, the test of the @code{while} loop will return false, and the
10508 arguments to the @code{while} will no longer be evaluated.
10510 For example, the list of animals bound to the variable @code{animals}
10511 can be set to be the @sc{cdr} of the original list with the
10512 following expression:
10515 (setq animals (cdr animals))
10519 If you have evaluated the previous expressions and then evaluate this
10520 expression, you will see @code{(giraffe lion tiger)} appear in the echo
10521 area. If you evaluate the expression again, @code{(lion tiger)} will
10522 appear in the echo area. If you evaluate it again and yet again,
10523 @code{(tiger)} appears and then the empty list, shown by @code{nil}.
10525 A template for a @code{while} loop that uses the @code{cdr} function
10526 repeatedly to cause the true-or-false-test eventually to test false
10531 (while @var{test-whether-list-is-empty}
10533 @var{set-list-to-cdr-of-list})
10537 This test and use of @code{cdr} can be put together in a function that
10538 goes through a list and prints each element of the list on a line of its
10541 @node print-elements-of-list, Incrementing Loop, Loop Example, while
10542 @subsection An Example: @code{print-elements-of-list}
10543 @findex print-elements-of-list
10545 The @code{print-elements-of-list} function illustrates a @code{while}
10548 @cindex @file{*scratch*} buffer
10549 The function requires several lines for its output. If you are
10550 reading this in a recent instance of GNU Emacs,
10551 @c GNU Emacs 21, GNU Emacs 22, or a later version,
10552 you can evaluate the following expression inside of Info, as usual.
10554 If you are using an earlier version of Emacs, you need to copy the
10555 necessary expressions to your @file{*scratch*} buffer and evaluate
10556 them there. This is because the echo area had only one line in the
10559 You can copy the expressions by marking the beginning of the region
10560 with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to
10561 the end of the region and then copying the region using @kbd{M-w}
10562 (@code{kill-ring-save}, which calls @code{copy-region-as-kill} and
10563 then provides visual feedback). In the @file{*scratch*}
10564 buffer, you can yank the expressions back by typing @kbd{C-y}
10567 After you have copied the expressions to the @file{*scratch*} buffer,
10568 evaluate each expression in turn. Be sure to evaluate the last
10569 expression, @code{(print-elements-of-list animals)}, by typing
10570 @kbd{C-u C-x C-e}, that is, by giving an argument to
10571 @code{eval-last-sexp}. This will cause the result of the evaluation
10572 to be printed in the @file{*scratch*} buffer instead of being printed
10573 in the echo area. (Otherwise you will see something like this in your
10574 echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which
10575 each @samp{^J} stands for a `newline'.)
10578 In a recent instance of GNU Emacs, you can evaluate these expressions
10579 directly in the Info buffer, and the echo area will grow to show the
10584 (setq animals '(gazelle giraffe lion tiger))
10586 (defun print-elements-of-list (list)
10587 "Print each element of LIST on a line of its own."
10590 (setq list (cdr list))))
10592 (print-elements-of-list animals)
10598 When you evaluate the three expressions in sequence, you will see
10614 Each element of the list is printed on a line of its own (that is what
10615 the function @code{print} does) and then the value returned by the
10616 function is printed. Since the last expression in the function is the
10617 @code{while} loop, and since @code{while} loops always return
10618 @code{nil}, a @code{nil} is printed after the last element of the list.
10620 @node Incrementing Loop, Decrementing Loop, print-elements-of-list, while
10621 @comment node-name, next, previous, up
10622 @subsection A Loop with an Incrementing Counter
10624 A loop is not useful unless it stops when it ought. Besides
10625 controlling a loop with a list, a common way of stopping a loop is to
10626 write the first argument as a test that returns false when the correct
10627 number of repetitions are complete. This means that the loop must
10628 have a counter---an expression that counts how many times the loop
10631 The test can be an expression such as @code{(< count desired-number)}
10632 which returns @code{t} for true if the value of @code{count} is less
10633 than the @code{desired-number} of repetitions and @code{nil} for false if
10634 the value of @code{count} is equal to or is greater than the
10635 @code{desired-number}. The expression that increments the count can be
10636 a simple @code{setq} such as @code{(setq count (1+ count))}, where
10637 @code{1+} is a built-in function in Emacs Lisp that adds 1 to its
10638 argument. (The expression @w{@code{(1+ count)}} has the same result as
10639 @w{@code{(+ count 1)}}, but is easier for a human to read.)
10642 The template for a @code{while} loop controlled by an incrementing
10643 counter looks like this:
10647 @var{set-count-to-initial-value}
10648 (while (< count desired-number) ; @r{true-or-false-test}
10650 (setq count (1+ count))) ; @r{incrementer}
10655 Note that you need to set the initial value of @code{count}; usually it
10659 * Incrementing Example::
10660 * Inc Example parts::
10661 * Inc Example altogether::
10664 @node Incrementing Example, Inc Example parts, Incrementing Loop, Incrementing Loop
10665 @unnumberedsubsubsec Example with incrementing counter
10667 Suppose you are playing on the beach and decide to make a triangle of
10668 pebbles, putting one pebble in the first row, two in the second row,
10669 three in the third row and so on, like this:
10687 @bullet{} @bullet{}
10688 @bullet{} @bullet{} @bullet{}
10689 @bullet{} @bullet{} @bullet{} @bullet{}
10696 (About 2500 years ago, Pythagoras and others developed the beginnings of
10697 number theory by considering questions such as this.)
10699 Suppose you want to know how many pebbles you will need to make a
10700 triangle with 7 rows?
10702 Clearly, what you need to do is add up the numbers from 1 to 7. There
10703 are two ways to do this; start with the smallest number, one, and add up
10704 the list in sequence, 1, 2, 3, 4 and so on; or start with the largest
10705 number and add the list going down: 7, 6, 5, 4 and so on. Because both
10706 mechanisms illustrate common ways of writing @code{while} loops, we will
10707 create two examples, one counting up and the other counting down. In
10708 this first example, we will start with 1 and add 2, 3, 4 and so on.
10710 If you are just adding up a short list of numbers, the easiest way to do
10711 it is to add up all the numbers at once. However, if you do not know
10712 ahead of time how many numbers your list will have, or if you want to be
10713 prepared for a very long list, then you need to design your addition so
10714 that what you do is repeat a simple process many times instead of doing
10715 a more complex process once.
10717 For example, instead of adding up all the pebbles all at once, what you
10718 can do is add the number of pebbles in the first row, 1, to the number
10719 in the second row, 2, and then add the total of those two rows to the
10720 third row, 3. Then you can add the number in the fourth row, 4, to the
10721 total of the first three rows; and so on.
10723 The critical characteristic of the process is that each repetitive
10724 action is simple. In this case, at each step we add only two numbers,
10725 the number of pebbles in the row and the total already found. This
10726 process of adding two numbers is repeated again and again until the last
10727 row has been added to the total of all the preceding rows. In a more
10728 complex loop the repetitive action might not be so simple, but it will
10729 be simpler than doing everything all at once.
10731 @node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop
10732 @unnumberedsubsubsec The parts of the function definition
10734 The preceding analysis gives us the bones of our function definition:
10735 first, we will need a variable that we can call @code{total} that will
10736 be the total number of pebbles. This will be the value returned by
10739 Second, we know that the function will require an argument: this
10740 argument will be the total number of rows in the triangle. It can be
10741 called @code{number-of-rows}.
10743 Finally, we need a variable to use as a counter. We could call this
10744 variable @code{counter}, but a better name is @code{row-number}. That
10745 is because what the counter does in this function is count rows, and a
10746 program should be written to be as understandable as possible.
10748 When the Lisp interpreter first starts evaluating the expressions in the
10749 function, the value of @code{total} should be set to zero, since we have
10750 not added anything to it. Then the function should add the number of
10751 pebbles in the first row to the total, and then add the number of
10752 pebbles in the second to the total, and then add the number of
10753 pebbles in the third row to the total, and so on, until there are no
10754 more rows left to add.
10756 Both @code{total} and @code{row-number} are used only inside the
10757 function, so they can be declared as local variables with @code{let}
10758 and given initial values. Clearly, the initial value for @code{total}
10759 should be 0. The initial value of @code{row-number} should be 1,
10760 since we start with the first row. This means that the @code{let}
10761 statement will look like this:
10771 After the internal variables are declared and bound to their initial
10772 values, we can begin the @code{while} loop. The expression that serves
10773 as the test should return a value of @code{t} for true so long as the
10774 @code{row-number} is less than or equal to the @code{number-of-rows}.
10775 (If the expression tests true only so long as the row number is less
10776 than the number of rows in the triangle, the last row will never be
10777 added to the total; hence the row number has to be either less than or
10778 equal to the number of rows.)
10781 @findex <= @r{(less than or equal)}
10782 Lisp provides the @code{<=} function that returns true if the value of
10783 its first argument is less than or equal to the value of its second
10784 argument and false otherwise. So the expression that the @code{while}
10785 will evaluate as its test should look like this:
10788 (<= row-number number-of-rows)
10791 The total number of pebbles can be found by repeatedly adding the number
10792 of pebbles in a row to the total already found. Since the number of
10793 pebbles in the row is equal to the row number, the total can be found by
10794 adding the row number to the total. (Clearly, in a more complex
10795 situation, the number of pebbles in the row might be related to the row
10796 number in a more complicated way; if this were the case, the row number
10797 would be replaced by the appropriate expression.)
10800 (setq total (+ total row-number))
10804 What this does is set the new value of @code{total} to be equal to the
10805 sum of adding the number of pebbles in the row to the previous total.
10807 After setting the value of @code{total}, the conditions need to be
10808 established for the next repetition of the loop, if there is one. This
10809 is done by incrementing the value of the @code{row-number} variable,
10810 which serves as a counter. After the @code{row-number} variable has
10811 been incremented, the true-or-false-test at the beginning of the
10812 @code{while} loop tests whether its value is still less than or equal to
10813 the value of the @code{number-of-rows} and if it is, adds the new value
10814 of the @code{row-number} variable to the @code{total} of the previous
10815 repetition of the loop.
10818 The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the
10819 @code{row-number} variable can be incremented with this expression:
10822 (setq row-number (1+ row-number))
10825 @node Inc Example altogether, , Inc Example parts, Incrementing Loop
10826 @unnumberedsubsubsec Putting the function definition together
10828 We have created the parts for the function definition; now we need to
10832 First, the contents of the @code{while} expression:
10836 (while (<= row-number number-of-rows) ; @r{true-or-false-test}
10837 (setq total (+ total row-number))
10838 (setq row-number (1+ row-number))) ; @r{incrementer}
10842 Along with the @code{let} expression varlist, this very nearly
10843 completes the body of the function definition. However, it requires
10844 one final element, the need for which is somewhat subtle.
10846 The final touch is to place the variable @code{total} on a line by
10847 itself after the @code{while} expression. Otherwise, the value returned
10848 by the whole function is the value of the last expression that is
10849 evaluated in the body of the @code{let}, and this is the value
10850 returned by the @code{while}, which is always @code{nil}.
10852 This may not be evident at first sight. It almost looks as if the
10853 incrementing expression is the last expression of the whole function.
10854 But that expression is part of the body of the @code{while}; it is the
10855 last element of the list that starts with the symbol @code{while}.
10856 Moreover, the whole of the @code{while} loop is a list within the body
10860 In outline, the function will look like this:
10864 (defun @var{name-of-function} (@var{argument-list})
10865 "@var{documentation}@dots{}"
10866 (let (@var{varlist})
10867 (while (@var{true-or-false-test})
10868 @var{body-of-while}@dots{} )
10869 @dots{} )) ; @r{Need final expression here.}
10873 The result of evaluating the @code{let} is what is going to be returned
10874 by the @code{defun} since the @code{let} is not embedded within any
10875 containing list, except for the @code{defun} as a whole. However, if
10876 the @code{while} is the last element of the @code{let} expression, the
10877 function will always return @code{nil}. This is not what we want!
10878 Instead, what we want is the value of the variable @code{total}. This
10879 is returned by simply placing the symbol as the last element of the list
10880 starting with @code{let}. It gets evaluated after the preceding
10881 elements of the list are evaluated, which means it gets evaluated after
10882 it has been assigned the correct value for the total.
10884 It may be easier to see this by printing the list starting with
10885 @code{let} all on one line. This format makes it evident that the
10886 @var{varlist} and @code{while} expressions are the second and third
10887 elements of the list starting with @code{let}, and the @code{total} is
10892 (let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total)
10897 Putting everything together, the @code{triangle} function definition
10902 (defun triangle (number-of-rows) ; @r{Version with}
10903 ; @r{ incrementing counter.}
10904 "Add up the number of pebbles in a triangle.
10905 The first row has one pebble, the second row two pebbles,
10906 the third row three pebbles, and so on.
10907 The argument is NUMBER-OF-ROWS."
10912 (while (<= row-number number-of-rows)
10913 (setq total (+ total row-number))
10914 (setq row-number (1+ row-number)))
10920 After you have installed @code{triangle} by evaluating the function, you
10921 can try it out. Here are two examples:
10932 The sum of the first four numbers is 10 and the sum of the first seven
10935 @node Decrementing Loop, , Incrementing Loop, while
10936 @comment node-name, next, previous, up
10937 @subsection Loop with a Decrementing Counter
10939 Another common way to write a @code{while} loop is to write the test
10940 so that it determines whether a counter is greater than zero. So long
10941 as the counter is greater than zero, the loop is repeated. But when
10942 the counter is equal to or less than zero, the loop is stopped. For
10943 this to work, the counter has to start out greater than zero and then
10944 be made smaller and smaller by a form that is evaluated
10947 The test will be an expression such as @code{(> counter 0)} which
10948 returns @code{t} for true if the value of @code{counter} is greater
10949 than zero, and @code{nil} for false if the value of @code{counter} is
10950 equal to or less than zero. The expression that makes the number
10951 smaller and smaller can be a simple @code{setq} such as @code{(setq
10952 counter (1- counter))}, where @code{1-} is a built-in function in
10953 Emacs Lisp that subtracts 1 from its argument.
10956 The template for a decrementing @code{while} loop looks like this:
10960 (while (> counter 0) ; @r{true-or-false-test}
10962 (setq counter (1- counter))) ; @r{decrementer}
10967 * Decrementing Example::
10968 * Dec Example parts::
10969 * Dec Example altogether::
10972 @node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop
10973 @unnumberedsubsubsec Example with decrementing counter
10975 To illustrate a loop with a decrementing counter, we will rewrite the
10976 @code{triangle} function so the counter decreases to zero.
10978 This is the reverse of the earlier version of the function. In this
10979 case, to find out how many pebbles are needed to make a triangle with
10980 3 rows, add the number of pebbles in the third row, 3, to the number
10981 in the preceding row, 2, and then add the total of those two rows to
10982 the row that precedes them, which is 1.
10984 Likewise, to find the number of pebbles in a triangle with 7 rows, add
10985 the number of pebbles in the seventh row, 7, to the number in the
10986 preceding row, which is 6, and then add the total of those two rows to
10987 the row that precedes them, which is 5, and so on. As in the previous
10988 example, each addition only involves adding two numbers, the total of
10989 the rows already added up and the number of pebbles in the row that is
10990 being added to the total. This process of adding two numbers is
10991 repeated again and again until there are no more pebbles to add.
10993 We know how many pebbles to start with: the number of pebbles in the
10994 last row is equal to the number of rows. If the triangle has seven
10995 rows, the number of pebbles in the last row is 7. Likewise, we know how
10996 many pebbles are in the preceding row: it is one less than the number in
10999 @node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop
11000 @unnumberedsubsubsec The parts of the function definition
11002 We start with three variables: the total number of rows in the
11003 triangle; the number of pebbles in a row; and the total number of
11004 pebbles, which is what we want to calculate. These variables can be
11005 named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and
11006 @code{total}, respectively.
11008 Both @code{total} and @code{number-of-pebbles-in-row} are used only
11009 inside the function and are declared with @code{let}. The initial
11010 value of @code{total} should, of course, be zero. However, the
11011 initial value of @code{number-of-pebbles-in-row} should be equal to
11012 the number of rows in the triangle, since the addition will start with
11016 This means that the beginning of the @code{let} expression will look
11022 (number-of-pebbles-in-row number-of-rows))
11027 The total number of pebbles can be found by repeatedly adding the number
11028 of pebbles in a row to the total already found, that is, by repeatedly
11029 evaluating the following expression:
11032 (setq total (+ total number-of-pebbles-in-row))
11036 After the @code{number-of-pebbles-in-row} is added to the @code{total},
11037 the @code{number-of-pebbles-in-row} should be decremented by one, since
11038 the next time the loop repeats, the preceding row will be
11039 added to the total.
11041 The number of pebbles in a preceding row is one less than the number of
11042 pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be
11043 used to compute the number of pebbles in the preceding row. This can be
11044 done with the following expression:
11048 (setq number-of-pebbles-in-row
11049 (1- number-of-pebbles-in-row))
11053 Finally, we know that the @code{while} loop should stop making repeated
11054 additions when there are no pebbles in a row. So the test for
11055 the @code{while} loop is simply:
11058 (while (> number-of-pebbles-in-row 0)
11061 @node Dec Example altogether, , Dec Example parts, Decrementing Loop
11062 @unnumberedsubsubsec Putting the function definition together
11064 We can put these expressions together to create a function definition
11065 that works. However, on examination, we find that one of the local
11066 variables is unneeded!
11069 The function definition looks like this:
11073 ;;; @r{First subtractive version.}
11074 (defun triangle (number-of-rows)
11075 "Add up the number of pebbles in a triangle."
11077 (number-of-pebbles-in-row number-of-rows))
11078 (while (> number-of-pebbles-in-row 0)
11079 (setq total (+ total number-of-pebbles-in-row))
11080 (setq number-of-pebbles-in-row
11081 (1- number-of-pebbles-in-row)))
11086 As written, this function works.
11088 However, we do not need @code{number-of-pebbles-in-row}.
11090 @cindex Argument as local variable
11091 When the @code{triangle} function is evaluated, the symbol
11092 @code{number-of-rows} will be bound to a number, giving it an initial
11093 value. That number can be changed in the body of the function as if
11094 it were a local variable, without any fear that such a change will
11095 effect the value of the variable outside of the function. This is a
11096 very useful characteristic of Lisp; it means that the variable
11097 @code{number-of-rows} can be used anywhere in the function where
11098 @code{number-of-pebbles-in-row} is used.
11101 Here is a second version of the function written a bit more cleanly:
11105 (defun triangle (number) ; @r{Second version.}
11106 "Return sum of numbers 1 through NUMBER inclusive."
11108 (while (> number 0)
11109 (setq total (+ total number))
11110 (setq number (1- number)))
11115 In brief, a properly written @code{while} loop will consist of three parts:
11119 A test that will return false after the loop has repeated itself the
11120 correct number of times.
11123 An expression the evaluation of which will return the value desired
11124 after being repeatedly evaluated.
11127 An expression to change the value passed to the true-or-false-test so
11128 that the test returns false after the loop has repeated itself the right
11132 @node dolist dotimes, Recursion, while, Loops & Recursion
11133 @comment node-name, next, previous, up
11134 @section Save your time: @code{dolist} and @code{dotimes}
11136 In addition to @code{while}, both @code{dolist} and @code{dotimes}
11137 provide for looping. Sometimes these are quicker to write than the
11138 equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, ,
11139 Macros, elisp, The GNU Emacs Lisp Reference Manual}. )
11141 @code{dolist} works like a @code{while} loop that `@sc{cdr}s down a
11142 list': @code{dolist} automatically shortens the list each time it
11143 loops---takes the @sc{cdr} of the list---and binds the @sc{car} of
11144 each shorter version of the list to the first of its arguments.
11146 @code{dotimes} loops a specific number of times: you specify the number.
11153 @node dolist, dotimes, dolist dotimes, dolist dotimes
11154 @unnumberedsubsubsec The @code{dolist} Macro
11157 Suppose, for example, you want to reverse a list, so that
11158 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''.
11161 In practice, you would use the @code{reverse} function, like this:
11165 (setq animals '(gazelle giraffe lion tiger))
11173 Here is how you could reverse the list using a @code{while} loop:
11177 (setq animals '(gazelle giraffe lion tiger))
11179 (defun reverse-list-with-while (list)
11180 "Using while, reverse the order of LIST."
11181 (let (value) ; make sure list starts empty
11183 (setq value (cons (car list) value))
11184 (setq list (cdr list)))
11187 (reverse-list-with-while animals)
11193 And here is how you could use the @code{dolist} macro:
11197 (setq animals '(gazelle giraffe lion tiger))
11199 (defun reverse-list-with-dolist (list)
11200 "Using dolist, reverse the order of LIST."
11201 (let (value) ; make sure list starts empty
11202 (dolist (element list value)
11203 (setq value (cons element value)))))
11205 (reverse-list-with-dolist animals)
11211 In Info, you can place your cursor after the closing parenthesis of
11212 each expression and type @kbd{C-x C-e}; in each case, you should see
11215 (tiger lion giraffe gazelle)
11221 For this example, the existing @code{reverse} function is obviously best.
11222 The @code{while} loop is just like our first example (@pxref{Loop
11223 Example, , A @code{while} Loop and a List}). The @code{while} first
11224 checks whether the list has elements; if so, it constructs a new list
11225 by adding the first element of the list to the existing list (which in
11226 the first iteration of the loop is @code{nil}). Since the second
11227 element is prepended in front of the first element, and the third
11228 element is prepended in front of the second element, the list is reversed.
11230 In the expression using a @code{while} loop,
11231 the @w{@code{(setq list (cdr list))}}
11232 expression shortens the list, so the @code{while} loop eventually
11233 stops. In addition, it provides the @code{cons} expression with a new
11234 first element by creating a new and shorter list at each repetition of
11237 The @code{dolist} expression does very much the same as the
11238 @code{while} expression, except that the @code{dolist} macro does some
11239 of the work you have to do when writing a @code{while} expression.
11241 Like a @code{while} loop, a @code{dolist} loops. What is different is
11242 that it automatically shortens the list each time it loops --- it
11243 `@sc{cdr}s down the list' on its own --- and it automatically binds
11244 the @sc{car} of each shorter version of the list to the first of its
11247 In the example, the @sc{car} of each shorter version of the list is
11248 referred to using the symbol @samp{element}, the list itself is called
11249 @samp{list}, and the value returned is called @samp{value}. The
11250 remainder of the @code{dolist} expression is the body.
11252 The @code{dolist} expression binds the @sc{car} of each shorter
11253 version of the list to @code{element} and then evaluates the body of
11254 the expression; and repeats the loop. The result is returned in
11257 @node dotimes, , dolist, dolist dotimes
11258 @unnumberedsubsubsec The @code{dotimes} Macro
11261 The @code{dotimes} macro is similar to @code{dolist}, except that it
11262 loops a specific number of times.
11264 The first argument to @code{dotimes} is assigned the numbers 0, 1, 2
11265 and so forth each time around the loop, and the value of the third
11266 argument is returned. You need to provide the value of the second
11267 argument, which is how many times the macro loops.
11270 For example, the following binds the numbers from 0 up to, but not
11271 including, the number 3 to the first argument, @var{number}, and then
11272 constructs a list of the three numbers. (The first number is 0, the
11273 second number is 1, and the third number is 2; this makes a total of
11274 three numbers in all, starting with zero as the first number.)
11278 (let (value) ; otherwise a value is a void variable
11279 (dotimes (number 3 value)
11280 (setq value (cons number value))))
11287 @code{dotimes} returns @code{value}, so the way to use
11288 @code{dotimes} is to operate on some expression @var{number} number of
11289 times and then return the result, either as a list or an atom.
11292 Here is an example of a @code{defun} that uses @code{dotimes} to add
11293 up the number of pebbles in a triangle.
11297 (defun triangle-using-dotimes (number-of-rows)
11298 "Using dotimes, add up the number of pebbles in a triangle."
11299 (let ((total 0)) ; otherwise a total is a void variable
11300 (dotimes (number number-of-rows total)
11301 (setq total (+ total (1+ number))))))
11303 (triangle-using-dotimes 4)
11307 @node Recursion, Looping exercise, dolist dotimes, Loops & Recursion
11308 @comment node-name, next, previous, up
11312 A recursive function contains code that tells the Lisp interpreter to
11313 call a program that runs exactly like itself, but with slightly
11314 different arguments. The code runs exactly the same because it has
11315 the same name. However, even though the program has the same name, it
11316 is not the same entity. It is different. In the jargon, it is a
11317 different `instance'.
11319 Eventually, if the program is written correctly, the `slightly
11320 different arguments' will become sufficiently different from the first
11321 arguments that the final instance will stop.
11324 * Building Robots::
11325 * Recursive Definition Parts::
11326 * Recursion with list::
11327 * Recursive triangle function::
11328 * Recursion with cond::
11329 * Recursive Patterns::
11331 * No deferment solution::
11334 @node Building Robots, Recursive Definition Parts, Recursion, Recursion
11335 @comment node-name, next, previous, up
11336 @subsection Building Robots: Extending the Metaphor
11337 @cindex Building robots
11338 @cindex Robots, building
11340 It is sometimes helpful to think of a running program as a robot that
11341 does a job. In doing its job, a recursive function calls on a second
11342 robot to help it. The second robot is identical to the first in every
11343 way, except that the second robot helps the first and has been
11344 passed different arguments than the first.
11346 In a recursive function, the second robot may call a third; and the
11347 third may call a fourth, and so on. Each of these is a different
11348 entity; but all are clones.
11350 Since each robot has slightly different instructions---the arguments
11351 will differ from one robot to the next---the last robot should know
11354 Let's expand on the metaphor in which a computer program is a robot.
11356 A function definition provides the blueprints for a robot. When you
11357 install a function definition, that is, when you evaluate a
11358 @code{defun} special form, you install the necessary equipment to
11359 build robots. It is as if you were in a factory, setting up an
11360 assembly line. Robots with the same name are built according to the
11361 same blueprints. So they have, as it were, the same `model number',
11362 but a different `serial number'.
11364 We often say that a recursive function `calls itself'. What we mean
11365 is that the instructions in a recursive function cause the Lisp
11366 interpreter to run a different function that has the same name and
11367 does the same job as the first, but with different arguments.
11369 It is important that the arguments differ from one instance to the
11370 next; otherwise, the process will never stop.
11372 @node Recursive Definition Parts, Recursion with list, Building Robots, Recursion
11373 @comment node-name, next, previous, up
11374 @subsection The Parts of a Recursive Definition
11375 @cindex Parts of a Recursive Definition
11376 @cindex Recursive Definition Parts
11378 A recursive function typically contains a conditional expression which
11383 A true-or-false-test that determines whether the function is called
11384 again, here called the @dfn{do-again-test}.
11387 The name of the function. When this name is called, a new instance of
11388 the function---a new robot, as it were---is created and told what to do.
11391 An expression that returns a different value each time the function is
11392 called, here called the @dfn{next-step-expression}. Consequently, the
11393 argument (or arguments) passed to the new instance of the function
11394 will be different from that passed to the previous instance. This
11395 causes the conditional expression, the @dfn{do-again-test}, to test
11396 false after the correct number of repetitions.
11399 Recursive functions can be much simpler than any other kind of
11400 function. Indeed, when people first start to use them, they often look
11401 so mysteriously simple as to be incomprehensible. Like riding a
11402 bicycle, reading a recursive function definition takes a certain knack
11403 which is hard at first but then seems simple.
11406 There are several different common recursive patterns. A very simple
11407 pattern looks like this:
11411 (defun @var{name-of-recursive-function} (@var{argument-list})
11412 "@var{documentation}@dots{}"
11413 (if @var{do-again-test}
11415 (@var{name-of-recursive-function}
11416 @var{next-step-expression})))
11420 Each time a recursive function is evaluated, a new instance of it is
11421 created and told what to do. The arguments tell the instance what to do.
11423 An argument is bound to the value of the next-step-expression. Each
11424 instance runs with a different value of the next-step-expression.
11426 The value in the next-step-expression is used in the do-again-test.
11428 The value returned by the next-step-expression is passed to the new
11429 instance of the function, which evaluates it (or some
11430 transmogrification of it) to determine whether to continue or stop.
11431 The next-step-expression is designed so that the do-again-test returns
11432 false when the function should no longer be repeated.
11434 The do-again-test is sometimes called the @dfn{stop condition},
11435 since it stops the repetitions when it tests false.
11437 @node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion
11438 @comment node-name, next, previous, up
11439 @subsection Recursion with a List
11441 The example of a @code{while} loop that printed the elements of a list
11442 of numbers can be written recursively. Here is the code, including
11443 an expression to set the value of the variable @code{animals} to a list.
11445 If you are using GNU Emacs 20 or before, this example must be copied
11446 to the @file{*scratch*} buffer and each expression must be evaluated
11447 there. Use @kbd{C-u C-x C-e} to evaluate the
11448 @code{(print-elements-recursively animals)} expression so that the
11449 results are printed in the buffer; otherwise the Lisp interpreter will
11450 try to squeeze the results into the one line of the echo area.
11452 Also, place your cursor immediately after the last closing parenthesis
11453 of the @code{print-elements-recursively} function, before the comment.
11454 Otherwise, the Lisp interpreter will try to evaluate the comment.
11456 If you are using a more recent version of Emacs, you can evaluate this
11457 expression directly in Info.
11459 @findex print-elements-recursively
11462 (setq animals '(gazelle giraffe lion tiger))
11464 (defun print-elements-recursively (list)
11465 "Print each element of LIST on a line of its own.
11467 (when list ; @r{do-again-test}
11468 (print (car list)) ; @r{body}
11469 (print-elements-recursively ; @r{recursive call}
11470 (cdr list)))) ; @r{next-step-expression}
11472 (print-elements-recursively animals)
11476 The @code{print-elements-recursively} function first tests whether
11477 there is any content in the list; if there is, the function prints the
11478 first element of the list, the @sc{car} of the list. Then the
11479 function `invokes itself', but gives itself as its argument, not the
11480 whole list, but the second and subsequent elements of the list, the
11481 @sc{cdr} of the list.
11483 Put another way, if the list is not empty, the function invokes
11484 another instance of code that is similar to the initial code, but is a
11485 different thread of execution, with different arguments than the first
11488 Put in yet another way, if the list is not empty, the first robot
11489 assemblies a second robot and tells it what to do; the second robot is
11490 a different individual from the first, but is the same model.
11492 When the second evaluation occurs, the @code{when} expression is
11493 evaluated and if true, prints the first element of the list it
11494 receives as its argument (which is the second element of the original
11495 list). Then the function `calls itself' with the @sc{cdr} of the list
11496 it is invoked with, which (the second time around) is the @sc{cdr} of
11497 the @sc{cdr} of the original list.
11499 Note that although we say that the function `calls itself', what we
11500 mean is that the Lisp interpreter assembles and instructs a new
11501 instance of the program. The new instance is a clone of the first,
11502 but is a separate individual.
11504 Each time the function `invokes itself', it invokes itself on a
11505 shorter version of the original list. It creates a new instance that
11506 works on a shorter list.
11508 Eventually, the function invokes itself on an empty list. It creates
11509 a new instance whose argument is @code{nil}. The conditional expression
11510 tests the value of @code{list}. Since the value of @code{list} is
11511 @code{nil}, the @code{when} expression tests false so the then-part is
11512 not evaluated. The function as a whole then returns @code{nil}.
11515 When you evaluate @code{(print-elements-recursively animals)} in the
11516 @file{*scratch*} buffer, you see this result:
11532 @node Recursive triangle function, Recursion with cond, Recursion with list, Recursion
11533 @comment node-name, next, previous, up
11534 @subsection Recursion in Place of a Counter
11535 @findex triangle-recursively
11538 The @code{triangle} function described in a previous section can also
11539 be written recursively. It looks like this:
11543 (defun triangle-recursively (number)
11544 "Return the sum of the numbers 1 through NUMBER inclusive.
11546 (if (= number 1) ; @r{do-again-test}
11548 (+ number ; @r{else-part}
11549 (triangle-recursively ; @r{recursive call}
11550 (1- number))))) ; @r{next-step-expression}
11552 (triangle-recursively 7)
11557 You can install this function by evaluating it and then try it by
11558 evaluating @code{(triangle-recursively 7)}. (Remember to put your
11559 cursor immediately after the last parenthesis of the function
11560 definition, before the comment.) The function evaluates to 28.
11562 To understand how this function works, let's consider what happens in the
11563 various cases when the function is passed 1, 2, 3, or 4 as the value of
11567 * Recursive Example arg of 1 or 2::
11568 * Recursive Example arg of 3 or 4::
11571 @node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function
11573 @unnumberedsubsubsec An argument of 1 or 2
11576 First, what happens if the value of the argument is 1?
11578 The function has an @code{if} expression after the documentation
11579 string. It tests whether the value of @code{number} is equal to 1; if
11580 so, Emacs evaluates the then-part of the @code{if} expression, which
11581 returns the number 1 as the value of the function. (A triangle with
11582 one row has one pebble in it.)
11584 Suppose, however, that the value of the argument is 2. In this case,
11585 Emacs evaluates the else-part of the @code{if} expression.
11588 The else-part consists of an addition, the recursive call to
11589 @code{triangle-recursively} and a decrementing action; and it looks like
11593 (+ number (triangle-recursively (1- number)))
11596 When Emacs evaluates this expression, the innermost expression is
11597 evaluated first; then the other parts in sequence. Here are the steps
11601 @item Step 1 @w{ } Evaluate the innermost expression.
11603 The innermost expression is @code{(1- number)} so Emacs decrements the
11604 value of @code{number} from 2 to 1.
11606 @item Step 2 @w{ } Evaluate the @code{triangle-recursively} function.
11608 The Lisp interpreter creates an individual instance of
11609 @code{triangle-recursively}. It does not matter that this function is
11610 contained within itself. Emacs passes the result Step 1 as the
11611 argument used by this instance of the @code{triangle-recursively}
11614 In this case, Emacs evaluates @code{triangle-recursively} with an
11615 argument of 1. This means that this evaluation of
11616 @code{triangle-recursively} returns 1.
11618 @item Step 3 @w{ } Evaluate the value of @code{number}.
11620 The variable @code{number} is the second element of the list that
11621 starts with @code{+}; its value is 2.
11623 @item Step 4 @w{ } Evaluate the @code{+} expression.
11625 The @code{+} expression receives two arguments, the first
11626 from the evaluation of @code{number} (Step 3) and the second from the
11627 evaluation of @code{triangle-recursively} (Step 2).
11629 The result of the addition is the sum of 2 plus 1, and the number 3 is
11630 returned, which is correct. A triangle with two rows has three
11634 @node Recursive Example arg of 3 or 4, , Recursive Example arg of 1 or 2, Recursive triangle function
11635 @unnumberedsubsubsec An argument of 3 or 4
11637 Suppose that @code{triangle-recursively} is called with an argument of
11641 @item Step 1 @w{ } Evaluate the do-again-test.
11643 The @code{if} expression is evaluated first. This is the do-again
11644 test and returns false, so the else-part of the @code{if} expression
11645 is evaluated. (Note that in this example, the do-again-test causes
11646 the function to call itself when it tests false, not when it tests
11649 @item Step 2 @w{ } Evaluate the innermost expression of the else-part.
11651 The innermost expression of the else-part is evaluated, which decrements
11652 3 to 2. This is the next-step-expression.
11654 @item Step 3 @w{ } Evaluate the @code{triangle-recursively} function.
11656 The number 2 is passed to the @code{triangle-recursively} function.
11658 We know what happens when Emacs evaluates @code{triangle-recursively} with
11659 an argument of 2. After going through the sequence of actions described
11660 earlier, it returns a value of 3. So that is what will happen here.
11662 @item Step 4 @w{ } Evaluate the addition.
11664 3 will be passed as an argument to the addition and will be added to the
11665 number with which the function was called, which is 3.
11669 The value returned by the function as a whole will be 6.
11671 Now that we know what will happen when @code{triangle-recursively} is
11672 called with an argument of 3, it is evident what will happen if it is
11673 called with an argument of 4:
11677 In the recursive call, the evaluation of
11680 (triangle-recursively (1- 4))
11685 will return the value of evaluating
11688 (triangle-recursively 3)
11692 which is 6 and this value will be added to 4 by the addition in the
11697 The value returned by the function as a whole will be 10.
11699 Each time @code{triangle-recursively} is evaluated, it evaluates a
11700 version of itself---a different instance of itself---with a smaller
11701 argument, until the argument is small enough so that it does not
11704 Note that this particular design for a recursive function
11705 requires that operations be deferred.
11707 Before @code{(triangle-recursively 7)} can calculate its answer, it
11708 must call @code{(triangle-recursively 6)}; and before
11709 @code{(triangle-recursively 6)} can calculate its answer, it must call
11710 @code{(triangle-recursively 5)}; and so on. That is to say, the
11711 calculation that @code{(triangle-recursively 7)} makes must be
11712 deferred until @code{(triangle-recursively 6)} makes its calculation;
11713 and @code{(triangle-recursively 6)} must defer until
11714 @code{(triangle-recursively 5)} completes; and so on.
11716 If each of these instances of @code{triangle-recursively} are thought
11717 of as different robots, the first robot must wait for the second to
11718 complete its job, which must wait until the third completes, and so
11721 There is a way around this kind of waiting, which we will discuss in
11722 @ref{No Deferment, , Recursion without Deferments}.
11724 @node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion
11725 @comment node-name, next, previous, up
11726 @subsection Recursion Example Using @code{cond}
11729 The version of @code{triangle-recursively} described earlier is written
11730 with the @code{if} special form. It can also be written using another
11731 special form called @code{cond}. The name of the special form
11732 @code{cond} is an abbreviation of the word @samp{conditional}.
11734 Although the @code{cond} special form is not used as often in the
11735 Emacs Lisp sources as @code{if}, it is used often enough to justify
11739 The template for a @code{cond} expression looks like this:
11749 where the @var{body} is a series of lists.
11752 Written out more fully, the template looks like this:
11757 (@var{first-true-or-false-test} @var{first-consequent})
11758 (@var{second-true-or-false-test} @var{second-consequent})
11759 (@var{third-true-or-false-test} @var{third-consequent})
11764 When the Lisp interpreter evaluates the @code{cond} expression, it
11765 evaluates the first element (the @sc{car} or true-or-false-test) of
11766 the first expression in a series of expressions within the body of the
11769 If the true-or-false-test returns @code{nil} the rest of that
11770 expression, the consequent, is skipped and the true-or-false-test of the
11771 next expression is evaluated. When an expression is found whose
11772 true-or-false-test returns a value that is not @code{nil}, the
11773 consequent of that expression is evaluated. The consequent can be one
11774 or more expressions. If the consequent consists of more than one
11775 expression, the expressions are evaluated in sequence and the value of
11776 the last one is returned. If the expression does not have a consequent,
11777 the value of the true-or-false-test is returned.
11779 If none of the true-or-false-tests test true, the @code{cond} expression
11780 returns @code{nil}.
11783 Written using @code{cond}, the @code{triangle} function looks like this:
11787 (defun triangle-using-cond (number)
11788 (cond ((<= number 0) 0)
11791 (+ number (triangle-using-cond (1- number))))))
11796 In this example, the @code{cond} returns 0 if the number is less than or
11797 equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+
11798 number (triangle-using-cond (1- number)))} if the number is greater than
11801 @node Recursive Patterns, No Deferment, Recursion with cond, Recursion
11802 @comment node-name, next, previous, up
11803 @subsection Recursive Patterns
11804 @cindex Recursive Patterns
11806 Here are three common recursive patterns. Each involves a list.
11807 Recursion does not need to involve lists, but Lisp is designed for lists
11808 and this provides a sense of its primal capabilities.
11816 @node Every, Accumulate, Recursive Patterns, Recursive Patterns
11817 @comment node-name, next, previous, up
11818 @unnumberedsubsubsec Recursive Pattern: @emph{every}
11819 @cindex Every, type of recursive pattern
11820 @cindex Recursive pattern: every
11822 In the @code{every} recursive pattern, an action is performed on every
11826 The basic pattern is:
11830 If a list be empty, return @code{nil}.
11832 Else, act on the beginning of the list (the @sc{car} of the list)
11835 through a recursive call by the function on the rest (the
11836 @sc{cdr}) of the list,
11838 and, optionally, combine the acted-on element, using @code{cons},
11839 with the results of acting on the rest.
11848 (defun square-each (numbers-list)
11849 "Square each of a NUMBERS LIST, recursively."
11850 (if (not numbers-list) ; do-again-test
11853 (* (car numbers-list) (car numbers-list))
11854 (square-each (cdr numbers-list))))) ; next-step-expression
11858 (square-each '(1 2 3))
11865 If @code{numbers-list} is empty, do nothing. But if it has content,
11866 construct a list combining the square of the first number in the list
11867 with the result of the recursive call.
11869 (The example follows the pattern exactly: @code{nil} is returned if
11870 the numbers' list is empty. In practice, you would write the
11871 conditional so it carries out the action when the numbers' list is not
11874 The @code{print-elements-recursively} function (@pxref{Recursion with
11875 list, , Recursion with a List}) is another example of an @code{every}
11876 pattern, except in this case, rather than bring the results together
11877 using @code{cons}, we print each element of output.
11880 The @code{print-elements-recursively} function looks like this:
11884 (setq animals '(gazelle giraffe lion tiger))
11888 (defun print-elements-recursively (list)
11889 "Print each element of LIST on a line of its own.
11891 (when list ; @r{do-again-test}
11892 (print (car list)) ; @r{body}
11893 (print-elements-recursively ; @r{recursive call}
11894 (cdr list)))) ; @r{next-step-expression}
11896 (print-elements-recursively animals)
11901 The pattern for @code{print-elements-recursively} is:
11905 When the list is empty, do nothing.
11907 But when the list has at least one element,
11910 act on the beginning of the list (the @sc{car} of the list),
11912 and make a recursive call on the rest (the @sc{cdr}) of the list.
11916 @node Accumulate, Keep, Every, Recursive Patterns
11917 @comment node-name, next, previous, up
11918 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
11919 @cindex Accumulate, type of recursive pattern
11920 @cindex Recursive pattern: accumulate
11922 Another recursive pattern is called the @code{accumulate} pattern. In
11923 the @code{accumulate} recursive pattern, an action is performed on
11924 every element of a list and the result of that action is accumulated
11925 with the results of performing the action on the other elements.
11927 This is very like the `every' pattern using @code{cons}, except that
11928 @code{cons} is not used, but some other combiner.
11935 If a list be empty, return zero or some other constant.
11937 Else, act on the beginning of the list (the @sc{car} of the list),
11940 and combine that acted-on element, using @code{+} or
11941 some other combining function, with
11943 a recursive call by the function on the rest (the @sc{cdr}) of the list.
11948 Here is an example:
11952 (defun add-elements (numbers-list)
11953 "Add the elements of NUMBERS-LIST together."
11954 (if (not numbers-list)
11956 (+ (car numbers-list) (add-elements (cdr numbers-list)))))
11960 (add-elements '(1 2 3 4))
11965 @xref{Files List, , Making a List of Files}, for an example of the
11966 accumulate pattern.
11968 @node Keep, , Accumulate, Recursive Patterns
11969 @comment node-name, next, previous, up
11970 @unnumberedsubsubsec Recursive Pattern: @emph{keep}
11971 @cindex Keep, type of recursive pattern
11972 @cindex Recursive pattern: keep
11974 A third recursive pattern is called the @code{keep} pattern.
11975 In the @code{keep} recursive pattern, each element of a list is tested;
11976 the element is acted on and the results are kept only if the element
11979 Again, this is very like the `every' pattern, except the element is
11980 skipped unless it meets a criterion.
11983 The pattern has three parts:
11987 If a list be empty, return @code{nil}.
11989 Else, if the beginning of the list (the @sc{car} of the list) passes
11993 act on that element and combine it, using @code{cons} with
11995 a recursive call by the function on the rest (the @sc{cdr}) of the list.
11998 Otherwise, if the beginning of the list (the @sc{car} of the list) fails
12002 skip on that element,
12004 and, recursively call the function on the rest (the @sc{cdr}) of the list.
12009 Here is an example that uses @code{cond}:
12013 (defun keep-three-letter-words (word-list)
12014 "Keep three letter words in WORD-LIST."
12016 ;; First do-again-test: stop-condition
12017 ((not word-list) nil)
12019 ;; Second do-again-test: when to act
12020 ((eq 3 (length (symbol-name (car word-list))))
12021 ;; combine acted-on element with recursive call on shorter list
12022 (cons (car word-list) (keep-three-letter-words (cdr word-list))))
12024 ;; Third do-again-test: when to skip element;
12025 ;; recursively call shorter list with next-step expression
12026 (t (keep-three-letter-words (cdr word-list)))))
12030 (keep-three-letter-words '(one two three four five six))
12031 @result{} (one two six)
12035 It goes without saying that you need not use @code{nil} as the test for
12036 when to stop; and you can, of course, combine these patterns.
12038 @node No Deferment, No deferment solution, Recursive Patterns, Recursion
12039 @subsection Recursion without Deferments
12040 @cindex Deferment in recursion
12041 @cindex Recursion without Deferments
12043 Let's consider again what happens with the @code{triangle-recursively}
12044 function. We will find that the intermediate calculations are
12045 deferred until all can be done.
12048 Here is the function definition:
12052 (defun triangle-recursively (number)
12053 "Return the sum of the numbers 1 through NUMBER inclusive.
12055 (if (= number 1) ; @r{do-again-test}
12057 (+ number ; @r{else-part}
12058 (triangle-recursively ; @r{recursive call}
12059 (1- number))))) ; @r{next-step-expression}
12063 What happens when we call this function with a argument of 7?
12065 The first instance of the @code{triangle-recursively} function adds
12066 the number 7 to the value returned by a second instance of
12067 @code{triangle-recursively}, an instance that has been passed an
12068 argument of 6. That is to say, the first calculation is:
12071 (+ 7 (triangle-recursively 6))
12075 The first instance of @code{triangle-recursively}---you may want to
12076 think of it as a little robot---cannot complete its job. It must hand
12077 off the calculation for @code{(triangle-recursively 6)} to a second
12078 instance of the program, to a second robot. This second individual is
12079 completely different from the first one; it is, in the jargon, a
12080 `different instantiation'. Or, put another way, it is a different
12081 robot. It is the same model as the first; it calculates triangle
12082 numbers recursively; but it has a different serial number.
12084 And what does @code{(triangle-recursively 6)} return? It returns the
12085 number 6 added to the value returned by evaluating
12086 @code{triangle-recursively} with an argument of 5. Using the robot
12087 metaphor, it asks yet another robot to help it.
12093 (+ 7 6 (triangle-recursively 5))
12097 And what happens next?
12100 (+ 7 6 5 (triangle-recursively 4))
12103 Each time @code{triangle-recursively} is called, except for the last
12104 time, it creates another instance of the program---another robot---and
12105 asks it to make a calculation.
12108 Eventually, the full addition is set up and performed:
12114 This design for the function defers the calculation of the first step
12115 until the second can be done, and defers that until the third can be
12116 done, and so on. Each deferment means the computer must remember what
12117 is being waited on. This is not a problem when there are only a few
12118 steps, as in this example. But it can be a problem when there are
12121 @node No deferment solution, , No Deferment, Recursion
12122 @subsection No Deferment Solution
12123 @cindex No deferment solution
12124 @cindex Defermentless solution
12125 @cindex Solution without deferment
12127 The solution to the problem of deferred operations is to write in a
12128 manner that does not defer operations@footnote{The phrase @dfn{tail
12129 recursive} is used to describe such a process, one that uses
12130 `constant space'.}. This requires
12131 writing to a different pattern, often one that involves writing two
12132 function definitions, an `initialization' function and a `helper'
12135 The `initialization' function sets up the job; the `helper' function
12139 Here are the two function definitions for adding up numbers. They are
12140 so simple, I find them hard to understand.
12144 (defun triangle-initialization (number)
12145 "Return the sum of the numbers 1 through NUMBER inclusive.
12146 This is the `initialization' component of a two function
12147 duo that uses recursion."
12148 (triangle-recursive-helper 0 0 number))
12154 (defun triangle-recursive-helper (sum counter number)
12155 "Return SUM, using COUNTER, through NUMBER inclusive.
12156 This is the `helper' component of a two function duo
12157 that uses recursion."
12158 (if (> counter number)
12160 (triangle-recursive-helper (+ sum counter) ; @r{sum}
12161 (1+ counter) ; @r{counter}
12162 number))) ; @r{number}
12167 Install both function definitions by evaluating them, then call
12168 @code{triangle-initialization} with 2 rows:
12172 (triangle-initialization 2)
12177 The `initialization' function calls the first instance of the `helper'
12178 function with three arguments: zero, zero, and a number which is the
12179 number of rows in the triangle.
12181 The first two arguments passed to the `helper' function are
12182 initialization values. These values are changed when
12183 @code{triangle-recursive-helper} invokes new instances.@footnote{The
12184 jargon is mildly confusing: @code{triangle-recursive-helper} uses a
12185 process that is iterative in a procedure that is recursive. The
12186 process is called iterative because the computer need only record the
12187 three values, @code{sum}, @code{counter}, and @code{number}; the
12188 procedure is recursive because the function `calls itself'. On the
12189 other hand, both the process and the procedure used by
12190 @code{triangle-recursively} are called recursive. The word
12191 `recursive' has different meanings in the two contexts.}
12193 Let's see what happens when we have a triangle that has one row. (This
12194 triangle will have one pebble in it!)
12197 @code{triangle-initialization} will call its helper with
12198 the arguments @w{@code{0 0 1}}. That function will run the conditional
12199 test whether @code{(> counter number)}:
12207 and find that the result is false, so it will invoke
12208 the else-part of the @code{if} clause:
12212 (triangle-recursive-helper
12213 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
12214 (1+ counter) ; @r{increment counter} @result{} @r{counter}
12215 number) ; @r{number stays the same}
12221 which will first compute:
12225 (triangle-recursive-helper (+ 0 0) ; @r{sum}
12226 (1+ 0) ; @r{counter}
12230 (triangle-recursive-helper 0 1 1)
12234 Again, @code{(> counter number)} will be false, so again, the Lisp
12235 interpreter will evaluate @code{triangle-recursive-helper}, creating a
12236 new instance with new arguments.
12239 This new instance will be;
12243 (triangle-recursive-helper
12244 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
12245 (1+ counter) ; @r{increment counter} @result{} @r{counter}
12246 number) ; @r{number stays the same}
12250 (triangle-recursive-helper 1 2 1)
12254 In this case, the @code{(> counter number)} test will be true! So the
12255 instance will return the value of the sum, which will be 1, as
12258 Now, let's pass @code{triangle-initialization} an argument
12259 of 2, to find out how many pebbles there are in a triangle with two rows.
12261 That function calls @code{(triangle-recursive-helper 0 0 2)}.
12264 In stages, the instances called will be:
12268 @r{sum counter number}
12269 (triangle-recursive-helper 0 1 2)
12271 (triangle-recursive-helper 1 2 2)
12273 (triangle-recursive-helper 3 3 2)
12277 When the last instance is called, the @code{(> counter number)} test
12278 will be true, so the instance will return the value of @code{sum},
12281 This kind of pattern helps when you are writing functions that can use
12282 many resources in a computer.
12285 @node Looping exercise, , Recursion, Loops & Recursion
12286 @section Looping Exercise
12290 Write a function similar to @code{triangle} in which each row has a
12291 value which is the square of the row number. Use a @code{while} loop.
12294 Write a function similar to @code{triangle} that multiplies instead of
12298 Rewrite these two functions recursively. Rewrite these functions
12301 @c comma in printed title causes problem in Info cross reference
12303 Write a function for Texinfo mode that creates an index entry at the
12304 beginning of a paragraph for every @samp{@@dfn} within the paragraph.
12305 (In a Texinfo file, @samp{@@dfn} marks a definition. This book is
12306 written in Texinfo.)
12308 Many of the functions you will need are described in two of the
12309 previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing
12310 Text}, and @ref{Yanking, , Yanking Text Back}. If you use
12311 @code{forward-paragraph} to put the index entry at the beginning of
12312 the paragraph, you will have to use @w{@kbd{C-h f}}
12313 (@code{describe-function}) to find out how to make the command go
12316 For more information, see
12318 @ref{Indicating, , Indicating Definitions, texinfo}.
12321 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to
12322 a Texinfo manual in the current directory. Or, if you are on the
12324 @uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
12327 ``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU
12328 Documentation Format}.
12332 @node Regexp Search, Counting Words, Loops & Recursion, Top
12333 @comment node-name, next, previous, up
12334 @chapter Regular Expression Searches
12335 @cindex Searches, illustrating
12336 @cindex Regular expression searches
12337 @cindex Patterns, searching for
12338 @cindex Motion by sentence and paragraph
12339 @cindex Sentences, movement by
12340 @cindex Paragraphs, movement by
12342 Regular expression searches are used extensively in GNU Emacs. The
12343 two functions, @code{forward-sentence} and @code{forward-paragraph},
12344 illustrate these searches well. They use regular expressions to find
12345 where to move point. The phrase `regular expression' is often written
12348 Regular expression searches are described in @ref{Regexp Search, ,
12349 Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in
12350 @ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference
12351 Manual}. In writing this chapter, I am presuming that you have at
12352 least a mild acquaintance with them. The major point to remember is
12353 that regular expressions permit you to search for patterns as well as
12354 for literal strings of characters. For example, the code in
12355 @code{forward-sentence} searches for the pattern of possible
12356 characters that could mark the end of a sentence, and moves point to
12359 Before looking at the code for the @code{forward-sentence} function, it
12360 is worth considering what the pattern that marks the end of a sentence
12361 must be. The pattern is discussed in the next section; following that
12362 is a description of the regular expression search function,
12363 @code{re-search-forward}. The @code{forward-sentence} function
12364 is described in the section following. Finally, the
12365 @code{forward-paragraph} function is described in the last section of
12366 this chapter. @code{forward-paragraph} is a complex function that
12367 introduces several new features.
12371 * re-search-forward::
12372 * forward-sentence::
12373 * forward-paragraph::
12376 * re-search Exercises::
12379 @node sentence-end, re-search-forward, Regexp Search, Regexp Search
12380 @comment node-name, next, previous, up
12381 @section The Regular Expression for @code{sentence-end}
12382 @findex sentence-end
12384 The symbol @code{sentence-end} is bound to the pattern that marks the
12385 end of a sentence. What should this regular expression be?
12387 Clearly, a sentence may be ended by a period, a question mark, or an
12388 exclamation mark. Indeed, in English, only clauses that end with one
12389 of those three characters should be considered the end of a sentence.
12390 This means that the pattern should include the character set:
12396 However, we do not want @code{forward-sentence} merely to jump to a
12397 period, a question mark, or an exclamation mark, because such a character
12398 might be used in the middle of a sentence. A period, for example, is
12399 used after abbreviations. So other information is needed.
12401 According to convention, you type two spaces after every sentence, but
12402 only one space after a period, a question mark, or an exclamation mark in
12403 the body of a sentence. So a period, a question mark, or an exclamation
12404 mark followed by two spaces is a good indicator of an end of sentence.
12405 However, in a file, the two spaces may instead be a tab or the end of a
12406 line. This means that the regular expression should include these three
12407 items as alternatives.
12410 This group of alternatives will look like this:
12421 Here, @samp{$} indicates the end of the line, and I have pointed out
12422 where the tab and two spaces are inserted in the expression. Both are
12423 inserted by putting the actual characters into the expression.
12425 Two backslashes, @samp{\\}, are required before the parentheses and
12426 vertical bars: the first backslash quotes the following backslash in
12427 Emacs; and the second indicates that the following character, the
12428 parenthesis or the vertical bar, is special.
12431 Also, a sentence may be followed by one or more carriage returns, like
12442 Like tabs and spaces, a carriage return is inserted into a regular
12443 expression by inserting it literally. The asterisk indicates that the
12444 @key{RET} is repeated zero or more times.
12446 But a sentence end does not consist only of a period, a question mark or
12447 an exclamation mark followed by appropriate space: a closing quotation
12448 mark or a closing brace of some kind may precede the space. Indeed more
12449 than one such mark or brace may precede the space. These require a
12450 expression that looks like this:
12456 In this expression, the first @samp{]} is the first character in the
12457 expression; the second character is @samp{"}, which is preceded by a
12458 @samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last
12459 three characters are @samp{'}, @samp{)}, and @samp{@}}.
12461 All this suggests what the regular expression pattern for matching the
12462 end of a sentence should be; and, indeed, if we evaluate
12463 @code{sentence-end} we find that it returns the following value:
12468 @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[
12474 (Well, not in GNU Emacs 22; that is because of an effort to make the
12475 process simpler and to handle more glyphs and languages. When the
12476 value of @code{sentence-end} is @code{nil}, then use the value defined
12477 by the function @code{sentence-end}. (Here is a use of the difference
12478 between a value and a function in Emacs Lisp.) The function returns a
12479 value constructed from the variables @code{sentence-end-base},
12480 @code{sentence-end-double-space}, @code{sentence-end-without-period},
12481 and @code{sentence-end-without-space}. The critical variable is
12482 @code{sentence-end-base}; its global value is similar to the one
12483 described above but it also contains two additional quotation marks.
12484 These have differing degrees of curliness. The
12485 @code{sentence-end-without-period} variable, when true, tells Emacs
12486 that a sentence may end without a period, such as text in Thai.)
12490 (Note that here the @key{TAB}, two spaces, and @key{RET} are shown
12491 literally in the pattern.)
12493 This regular expression can be deciphered as follows:
12497 The first part of the pattern is the three characters, a period, a question
12498 mark and an exclamation mark, within square brackets. The pattern must
12499 begin with one or other of these characters.
12502 The second part of the pattern is the group of closing braces and
12503 quotation marks, which can appear zero or more times. These may follow
12504 the period, question mark or exclamation mark. In a regular expression,
12505 the backslash, @samp{\}, followed by the double quotation mark,
12506 @samp{"}, indicates the class of string-quote characters. Usually, the
12507 double quotation mark is the only character in this class. The
12508 asterisk, @samp{*}, indicates that the items in the previous group (the
12509 group surrounded by square brackets, @samp{[]}) may be repeated zero or
12512 @item \\($\\| \\| \\)
12513 The third part of the pattern is one or other of: either the end of a
12514 line, or two blank spaces, or a tab. The double back-slashes are used
12515 to prevent Emacs from reading the parentheses and vertical bars as part
12516 of the search pattern; the parentheses are used to mark the group and
12517 the vertical bars are used to indicated that the patterns to either side
12518 of them are alternatives. The dollar sign is used to indicate the end
12519 of a line and both the two spaces and the tab are each inserted as is to
12520 indicate what they are.
12523 Finally, the last part of the pattern indicates that the end of the line
12524 or the whitespace following the period, question mark or exclamation
12525 mark may, but need not, be followed by one or more carriage returns. In
12526 the pattern, the carriage return is inserted as an actual carriage
12527 return between square brackets but here it is shown as @key{RET}.
12531 @node re-search-forward, forward-sentence, sentence-end, Regexp Search
12532 @comment node-name, next, previous, up
12533 @section The @code{re-search-forward} Function
12534 @findex re-search-forward
12536 The @code{re-search-forward} function is very like the
12537 @code{search-forward} function. (@xref{search-forward, , The
12538 @code{search-forward} Function}.)
12540 @code{re-search-forward} searches for a regular expression. If the
12541 search is successful, it leaves point immediately after the last
12542 character in the target. If the search is backwards, it leaves point
12543 just before the first character in the target. You may tell
12544 @code{re-search-forward} to return @code{t} for true. (Moving point
12545 is therefore a `side effect'.)
12547 Like @code{search-forward}, the @code{re-search-forward} function takes
12552 The first argument is the regular expression that the function searches
12553 for. The regular expression will be a string between quotations marks.
12556 The optional second argument limits how far the function will search; it is a
12557 bound, which is specified as a position in the buffer.
12560 The optional third argument specifies how the function responds to
12561 failure: @code{nil} as the third argument causes the function to
12562 signal an error (and print a message) when the search fails; any other
12563 value causes it to return @code{nil} if the search fails and @code{t}
12564 if the search succeeds.
12567 The optional fourth argument is the repeat count. A negative repeat
12568 count causes @code{re-search-forward} to search backwards.
12572 The template for @code{re-search-forward} looks like this:
12576 (re-search-forward "@var{regular-expression}"
12577 @var{limit-of-search}
12578 @var{what-to-do-if-search-fails}
12579 @var{repeat-count})
12583 The second, third, and fourth arguments are optional. However, if you
12584 want to pass a value to either or both of the last two arguments, you
12585 must also pass a value to all the preceding arguments. Otherwise, the
12586 Lisp interpreter will mistake which argument you are passing the value
12590 In the @code{forward-sentence} function, the regular expression will be
12591 the value of the variable @code{sentence-end}. In simple form, that is:
12595 "[.?!][]\"')@}]*\\($\\| \\| \\)[
12601 The limit of the search will be the end of the paragraph (since a
12602 sentence cannot go beyond a paragraph). If the search fails, the
12603 function will return @code{nil}; and the repeat count will be provided
12604 by the argument to the @code{forward-sentence} function.
12606 @node forward-sentence, forward-paragraph, re-search-forward, Regexp Search
12607 @comment node-name, next, previous, up
12608 @section @code{forward-sentence}
12609 @findex forward-sentence
12611 The command to move the cursor forward a sentence is a straightforward
12612 illustration of how to use regular expression searches in Emacs Lisp.
12613 Indeed, the function looks longer and more complicated than it is; this
12614 is because the function is designed to go backwards as well as forwards;
12615 and, optionally, over more than one sentence. The function is usually
12616 bound to the key command @kbd{M-e}.
12619 * Complete forward-sentence::
12620 * fwd-sentence while loops::
12621 * fwd-sentence re-search::
12624 @node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence
12626 @unnumberedsubsec Complete @code{forward-sentence} function definition
12630 Here is the code for @code{forward-sentence}:
12635 (defun forward-sentence (&optional arg)
12636 "Move forward to next `sentence-end'. With argument, repeat.
12637 With negative argument, move backward repeatedly to `sentence-beginning'.
12639 The variable `sentence-end' is a regular expression that matches ends of
12640 sentences. Also, every paragraph boundary terminates sentences as well."
12644 (or arg (setq arg 1))
12645 (let ((opoint (point))
12646 (sentence-end (sentence-end)))
12648 (let ((pos (point))
12649 (par-beg (save-excursion (start-of-paragraph-text) (point))))
12650 (if (and (re-search-backward sentence-end par-beg t)
12651 (or (< (match-end 0) pos)
12652 (re-search-backward sentence-end par-beg t)))
12653 (goto-char (match-end 0))
12654 (goto-char par-beg)))
12655 (setq arg (1+ arg)))
12659 (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
12660 (if (re-search-forward sentence-end par-end t)
12661 (skip-chars-backward " \t\n")
12662 (goto-char par-end)))
12663 (setq arg (1- arg)))
12664 (constrain-to-field nil opoint t)))
12672 (defun forward-sentence (&optional arg)
12673 "Move forward to next sentence-end. With argument, repeat.
12674 With negative argument, move backward repeatedly to sentence-beginning.
12675 Sentence ends are identified by the value of sentence-end
12676 treated as a regular expression. Also, every paragraph boundary
12677 terminates sentences as well."
12681 (or arg (setq arg 1))
12684 (save-excursion (start-of-paragraph-text) (point))))
12685 (if (re-search-backward
12686 (concat sentence-end "[^ \t\n]") par-beg t)
12687 (goto-char (1- (match-end 0)))
12688 (goto-char par-beg)))
12689 (setq arg (1+ arg)))
12692 (save-excursion (end-of-paragraph-text) (point))))
12693 (if (re-search-forward sentence-end par-end t)
12694 (skip-chars-backward " \t\n")
12695 (goto-char par-end)))
12696 (setq arg (1- arg))))
12701 The function looks long at first sight and it is best to look at its
12702 skeleton first, and then its muscle. The way to see the skeleton is to
12703 look at the expressions that start in the left-most columns:
12707 (defun forward-sentence (&optional arg)
12708 "@var{documentation}@dots{}"
12710 (or arg (setq arg 1))
12711 (let ((opoint (point)) (sentence-end (sentence-end)))
12713 (let ((pos (point))
12714 (par-beg (save-excursion (start-of-paragraph-text) (point))))
12715 @var{rest-of-body-of-while-loop-when-going-backwards}
12717 (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
12718 @var{rest-of-body-of-while-loop-when-going-forwards}
12719 @var{handle-forms-and-equivalent}
12723 This looks much simpler! The function definition consists of
12724 documentation, an @code{interactive} expression, an @code{or}
12725 expression, a @code{let} expression, and @code{while} loops.
12727 Let's look at each of these parts in turn.
12729 We note that the documentation is thorough and understandable.
12731 The function has an @code{interactive "p"} declaration. This means
12732 that the processed prefix argument, if any, is passed to the
12733 function as its argument. (This will be a number.) If the function
12734 is not passed an argument (it is optional) then the argument
12735 @code{arg} will be bound to 1.
12737 When @code{forward-sentence} is called non-interactively without an
12738 argument, @code{arg} is bound to @code{nil}. The @code{or} expression
12739 handles this. What it does is either leave the value of @code{arg} as
12740 it is, but only if @code{arg} is bound to a value; or it sets the
12741 value of @code{arg} to 1, in the case when @code{arg} is bound to
12744 Next is a @code{let}. That specifies the values of two local
12745 variables, @code{point} and @code{sentence-end}. The local value of
12746 point, from before the search, is used in the
12747 @code{constrain-to-field} function which handles forms and
12748 equivalents. The @code{sentence-end} variable is set by the
12749 @code{sentence-end} function.
12751 @node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence
12752 @unnumberedsubsec The @code{while} loops
12754 Two @code{while} loops follow. The first @code{while} has a
12755 true-or-false-test that tests true if the prefix argument for
12756 @code{forward-sentence} is a negative number. This is for going
12757 backwards. The body of this loop is similar to the body of the second
12758 @code{while} clause, but it is not exactly the same. We will skip
12759 this @code{while} loop and concentrate on the second @code{while}
12763 The second @code{while} loop is for moving point forward. Its skeleton
12768 (while (> arg 0) ; @r{true-or-false-test}
12770 (if (@var{true-or-false-test})
12773 (setq arg (1- arg)))) ; @code{while} @r{loop decrementer}
12777 The @code{while} loop is of the decrementing kind.
12778 (@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It
12779 has a true-or-false-test that tests true so long as the counter (in
12780 this case, the variable @code{arg}) is greater than zero; and it has a
12781 decrementer that subtracts 1 from the value of the counter every time
12784 If no prefix argument is given to @code{forward-sentence}, which is
12785 the most common way the command is used, this @code{while} loop will
12786 run once, since the value of @code{arg} will be 1.
12788 The body of the @code{while} loop consists of a @code{let} expression,
12789 which creates and binds a local variable, and has, as its body, an
12790 @code{if} expression.
12793 The body of the @code{while} loop looks like this:
12798 (save-excursion (end-of-paragraph-text) (point))))
12799 (if (re-search-forward sentence-end par-end t)
12800 (skip-chars-backward " \t\n")
12801 (goto-char par-end)))
12805 The @code{let} expression creates and binds the local variable
12806 @code{par-end}. As we shall see, this local variable is designed to
12807 provide a bound or limit to the regular expression search. If the
12808 search fails to find a proper sentence ending in the paragraph, it will
12809 stop on reaching the end of the paragraph.
12811 But first, let us examine how @code{par-end} is bound to the value of
12812 the end of the paragraph. What happens is that the @code{let} sets the
12813 value of @code{par-end} to the value returned when the Lisp interpreter
12814 evaluates the expression
12818 (save-excursion (end-of-paragraph-text) (point))
12823 In this expression, @code{(end-of-paragraph-text)} moves point to the
12824 end of the paragraph, @code{(point)} returns the value of point, and then
12825 @code{save-excursion} restores point to its original position. Thus,
12826 the @code{let} binds @code{par-end} to the value returned by the
12827 @code{save-excursion} expression, which is the position of the end of
12828 the paragraph. (The @code{end-of-paragraph-text} function uses
12829 @code{forward-paragraph}, which we will discuss shortly.)
12832 Emacs next evaluates the body of the @code{let}, which is an @code{if}
12833 expression that looks like this:
12837 (if (re-search-forward sentence-end par-end t) ; @r{if-part}
12838 (skip-chars-backward " \t\n") ; @r{then-part}
12839 (goto-char par-end))) ; @r{else-part}
12843 The @code{if} tests whether its first argument is true and if so,
12844 evaluates its then-part; otherwise, the Emacs Lisp interpreter
12845 evaluates the else-part. The true-or-false-test of the @code{if}
12846 expression is the regular expression search.
12848 It may seem odd to have what looks like the `real work' of
12849 the @code{forward-sentence} function buried here, but this is a common
12850 way this kind of operation is carried out in Lisp.
12852 @node fwd-sentence re-search, , fwd-sentence while loops, forward-sentence
12853 @unnumberedsubsec The regular expression search
12855 The @code{re-search-forward} function searches for the end of the
12856 sentence, that is, for the pattern defined by the @code{sentence-end}
12857 regular expression. If the pattern is found---if the end of the sentence is
12858 found---then the @code{re-search-forward} function does two things:
12862 The @code{re-search-forward} function carries out a side effect, which
12863 is to move point to the end of the occurrence found.
12866 The @code{re-search-forward} function returns a value of true. This is
12867 the value received by the @code{if}, and means that the search was
12872 The side effect, the movement of point, is completed before the
12873 @code{if} function is handed the value returned by the successful
12874 conclusion of the search.
12876 When the @code{if} function receives the value of true from a successful
12877 call to @code{re-search-forward}, the @code{if} evaluates the then-part,
12878 which is the expression @code{(skip-chars-backward " \t\n")}. This
12879 expression moves backwards over any blank spaces, tabs or carriage
12880 returns until a printed character is found and then leaves point after
12881 the character. Since point has already been moved to the end of the
12882 pattern that marks the end of the sentence, this action leaves point
12883 right after the closing printed character of the sentence, which is
12886 On the other hand, if the @code{re-search-forward} function fails to
12887 find a pattern marking the end of the sentence, the function returns
12888 false. The false then causes the @code{if} to evaluate its third
12889 argument, which is @code{(goto-char par-end)}: it moves point to the
12890 end of the paragraph.
12892 (And if the text is in a form or equivalent, and point may not move
12893 fully, then the @code{constrain-to-field} function comes into play.)
12895 Regular expression searches are exceptionally useful and the pattern
12896 illustrated by @code{re-search-forward}, in which the search is the
12897 test of an @code{if} expression, is handy. You will see or write code
12898 incorporating this pattern often.
12900 @node forward-paragraph, etags, forward-sentence, Regexp Search
12901 @comment node-name, next, previous, up
12902 @section @code{forward-paragraph}: a Goldmine of Functions
12903 @findex forward-paragraph
12907 (defun forward-paragraph (&optional arg)
12908 "Move forward to end of paragraph.
12909 With argument ARG, do it ARG times;
12910 a negative argument ARG = -N means move backward N paragraphs.
12912 A line which `paragraph-start' matches either separates paragraphs
12913 \(if `paragraph-separate' matches it also) or is the first line of a paragraph.
12914 A paragraph end is the beginning of a line which is not part of the paragraph
12915 to which the end of the previous line belongs, or the end of the buffer.
12916 Returns the count of paragraphs left to move."
12918 (or arg (setq arg 1))
12919 (let* ((opoint (point))
12920 (fill-prefix-regexp
12921 (and fill-prefix (not (equal fill-prefix ""))
12922 (not paragraph-ignore-fill-prefix)
12923 (regexp-quote fill-prefix)))
12924 ;; Remove ^ from paragraph-start and paragraph-sep if they are there.
12925 ;; These regexps shouldn't be anchored, because we look for them
12926 ;; starting at the left-margin. This allows paragraph commands to
12927 ;; work normally with indented text.
12928 ;; This hack will not find problem cases like "whatever\\|^something".
12929 (parstart (if (and (not (equal "" paragraph-start))
12930 (equal ?^ (aref paragraph-start 0)))
12931 (substring paragraph-start 1)
12933 (parsep (if (and (not (equal "" paragraph-separate))
12934 (equal ?^ (aref paragraph-separate 0)))
12935 (substring paragraph-separate 1)
12936 paragraph-separate))
12938 (if fill-prefix-regexp
12939 (concat parsep "\\|"
12940 fill-prefix-regexp "[ \t]*$")
12942 ;; This is used for searching.
12943 (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)"))
12945 (while (and (< arg 0) (not (bobp)))
12946 (if (and (not (looking-at parsep))
12947 (re-search-backward "^\n" (max (1- (point)) (point-min)) t)
12948 (looking-at parsep))
12949 (setq arg (1+ arg))
12950 (setq start (point))
12951 ;; Move back over paragraph-separating lines.
12952 (forward-char -1) (beginning-of-line)
12953 (while (and (not (bobp))
12954 (progn (move-to-left-margin)
12955 (looking-at parsep)))
12959 (setq arg (1+ arg))
12960 ;; Go to end of the previous (non-separating) line.
12962 ;; Search back for line that starts or separates paragraphs.
12963 (if (if fill-prefix-regexp
12964 ;; There is a fill prefix; it overrides parstart.
12965 (let (multiple-lines)
12966 (while (and (progn (beginning-of-line) (not (bobp)))
12967 (progn (move-to-left-margin)
12968 (not (looking-at parsep)))
12969 (looking-at fill-prefix-regexp))
12970 (unless (= (point) start)
12971 (setq multiple-lines t))
12973 (move-to-left-margin)
12974 ;; This deleted code caused a long hanging-indent line
12975 ;; not to be filled together with the following lines.
12976 ;; ;; Don't move back over a line before the paragraph
12977 ;; ;; which doesn't start with fill-prefix
12978 ;; ;; unless that is the only line we've moved over.
12979 ;; (and (not (looking-at fill-prefix-regexp))
12981 ;; (forward-line 1))
12983 (while (and (re-search-backward sp-parstart nil 1)
12984 (setq found-start t)
12985 ;; Found a candidate, but need to check if it is a
12987 (progn (setq start (point))
12988 (move-to-left-margin)
12989 (not (looking-at parsep)))
12990 (not (and (looking-at parstart)
12991 (or (not use-hard-newlines)
12994 (1- start) 'hard)))))
12995 (setq found-start nil)
13000 ;; Move forward over paragraph separators.
13001 ;; We know this cannot reach the place we started
13002 ;; because we know we moved back over a non-separator.
13003 (while (and (not (eobp))
13004 (progn (move-to-left-margin)
13005 (looking-at parsep)))
13007 ;; If line before paragraph is just margin, back up to there.
13009 (if (> (current-column) (current-left-margin))
13011 (skip-chars-backward " \t")
13013 (forward-line 1))))
13014 ;; No starter or separator line => use buffer beg.
13015 (goto-char (point-min))))))
13017 (while (and (> arg 0) (not (eobp)))
13018 ;; Move forward over separator lines...
13019 (while (and (not (eobp))
13020 (progn (move-to-left-margin) (not (eobp)))
13021 (looking-at parsep))
13023 (unless (eobp) (setq arg (1- arg)))
13024 ;; ... and one more line.
13026 (if fill-prefix-regexp
13027 ;; There is a fill prefix; it overrides parstart.
13028 (while (and (not (eobp))
13029 (progn (move-to-left-margin) (not (eobp)))
13030 (not (looking-at parsep))
13031 (looking-at fill-prefix-regexp))
13033 (while (and (re-search-forward sp-parstart nil 1)
13034 (progn (setq start (match-beginning 0))
13037 (progn (move-to-left-margin)
13038 (not (looking-at parsep)))
13039 (or (not (looking-at parstart))
13040 (and use-hard-newlines
13041 (not (get-text-property (1- start) 'hard)))))
13043 (if (< (point) (point-max))
13044 (goto-char start))))
13045 (constrain-to-field nil opoint t)
13046 ;; Return the number of steps that could not be done.
13050 The @code{forward-paragraph} function moves point forward to the end
13051 of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a
13052 number of functions that are important in themselves, including
13053 @code{let*}, @code{match-beginning}, and @code{looking-at}.
13055 The function definition for @code{forward-paragraph} is considerably
13056 longer than the function definition for @code{forward-sentence}
13057 because it works with a paragraph, each line of which may begin with a
13060 A fill prefix consists of a string of characters that are repeated at
13061 the beginning of each line. For example, in Lisp code, it is a
13062 convention to start each line of a paragraph-long comment with
13063 @samp{;;; }. In Text mode, four blank spaces make up another common
13064 fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , ,
13065 emacs, The GNU Emacs Manual}, for more information about fill
13068 The existence of a fill prefix means that in addition to being able to
13069 find the end of a paragraph whose lines begin on the left-most
13070 column, the @code{forward-paragraph} function must be able to find the
13071 end of a paragraph when all or many of the lines in the buffer begin
13072 with the fill prefix.
13074 Moreover, it is sometimes practical to ignore a fill prefix that
13075 exists, especially when blank lines separate paragraphs.
13076 This is an added complication.
13079 * forward-paragraph in brief::
13084 @node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph
13086 @unnumberedsubsec Shortened @code{forward-paragraph} function definition
13089 Rather than print all of the @code{forward-paragraph} function, we
13090 will only print parts of it. Read without preparation, the function
13094 In outline, the function looks like this:
13098 (defun forward-paragraph (&optional arg)
13099 "@var{documentation}@dots{}"
13101 (or arg (setq arg 1))
13104 (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code}
13106 (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code}
13111 The first parts of the function are routine: the function's argument
13112 list consists of one optional argument. Documentation follows.
13114 The lower case @samp{p} in the @code{interactive} declaration means
13115 that the processed prefix argument, if any, is passed to the function.
13116 This will be a number, and is the repeat count of how many paragraphs
13117 point will move. The @code{or} expression in the next line handles
13118 the common case when no argument is passed to the function, which occurs
13119 if the function is called from other code rather than interactively.
13120 This case was described earlier. (@xref{forward-sentence, The
13121 @code{forward-sentence} function}.) Now we reach the end of the
13122 familiar part of this function.
13124 @node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph
13125 @unnumberedsubsec The @code{let*} expression
13127 The next line of the @code{forward-paragraph} function begins a
13128 @code{let*} expression. This is a different than @code{let}. The
13129 symbol is @code{let*} not @code{let}.
13131 The @code{let*} special form is like @code{let} except that Emacs sets
13132 each variable in sequence, one after another, and variables in the
13133 latter part of the varlist can make use of the values to which Emacs
13134 set variables in the earlier part of the varlist.
13137 ( refappend save-excursion, , code save-excursion in code append-to-buffer .)
13140 (@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.)
13142 In the @code{let*} expression in this function, Emacs binds a total of
13143 seven variables: @code{opoint}, @code{fill-prefix-regexp},
13144 @code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and
13145 @code{found-start}.
13147 The variable @code{parsep} appears twice, first, to remove instances
13148 of @samp{^}, and second, to handle fill prefixes.
13150 The variable @code{opoint} is just the value of @code{point}. As you
13151 can guess, it is used in a @code{constrain-to-field} expression, just
13152 as in @code{forward-sentence}.
13154 The variable @code{fill-prefix-regexp} is set to the value returned by
13155 evaluating the following list:
13160 (not (equal fill-prefix ""))
13161 (not paragraph-ignore-fill-prefix)
13162 (regexp-quote fill-prefix))
13167 This is an expression whose first element is the @code{and} special form.
13169 As we learned earlier (@pxref{kill-new function, , The @code{kill-new}
13170 function}), the @code{and} special form evaluates each of its
13171 arguments until one of the arguments returns a value of @code{nil}, in
13172 which case the @code{and} expression returns @code{nil}; however, if
13173 none of the arguments returns a value of @code{nil}, the value
13174 resulting from evaluating the last argument is returned. (Since such
13175 a value is not @code{nil}, it is considered true in Lisp.) In other
13176 words, an @code{and} expression returns a true value only if all its
13177 arguments are true.
13180 In this case, the variable @code{fill-prefix-regexp} is bound to a
13181 non-@code{nil} value only if the following four expressions produce a
13182 true (i.e., a non-@code{nil}) value when they are evaluated; otherwise,
13183 @code{fill-prefix-regexp} is bound to @code{nil}.
13187 When this variable is evaluated, the value of the fill prefix, if any,
13188 is returned. If there is no fill prefix, this variable returns
13191 @item (not (equal fill-prefix "")
13192 This expression checks whether an existing fill prefix is an empty
13193 string, that is, a string with no characters in it. An empty string is
13194 not a useful fill prefix.
13196 @item (not paragraph-ignore-fill-prefix)
13197 This expression returns @code{nil} if the variable
13198 @code{paragraph-ignore-fill-prefix} has been turned on by being set to a
13199 true value such as @code{t}.
13201 @item (regexp-quote fill-prefix)
13202 This is the last argument to the @code{and} special form. If all the
13203 arguments to the @code{and} are true, the value resulting from
13204 evaluating this expression will be returned by the @code{and} expression
13205 and bound to the variable @code{fill-prefix-regexp},
13208 @findex regexp-quote
13210 The result of evaluating this @code{and} expression successfully is that
13211 @code{fill-prefix-regexp} will be bound to the value of
13212 @code{fill-prefix} as modified by the @code{regexp-quote} function.
13213 What @code{regexp-quote} does is read a string and return a regular
13214 expression that will exactly match the string and match nothing else.
13215 This means that @code{fill-prefix-regexp} will be set to a value that
13216 will exactly match the fill prefix if the fill prefix exists.
13217 Otherwise, the variable will be set to @code{nil}.
13219 The next two local variables in the @code{let*} expression are
13220 designed to remove instances of @samp{^} from @code{parstart} and
13221 @code{parsep}, the local variables which indicate the paragraph start
13222 and the paragraph separator. The next expression sets @code{parsep}
13223 again. That is to handle fill prefixes.
13225 This is the setting that requires the definition call @code{let*}
13226 rather than @code{let}. The true-or-false-test for the @code{if}
13227 depends on whether the variable @code{fill-prefix-regexp} evaluates to
13228 @code{nil} or some other value.
13230 If @code{fill-prefix-regexp} does not have a value, Emacs evaluates
13231 the else-part of the @code{if} expression and binds @code{parsep} to
13232 its local value. (@code{parsep} is a regular expression that matches
13233 what separates paragraphs.)
13235 But if @code{fill-prefix-regexp} does have a value, Emacs evaluates
13236 the then-part of the @code{if} expression and binds @code{parsep} to a
13237 regular expression that includes the @code{fill-prefix-regexp} as part
13240 Specifically, @code{parsep} is set to the original value of the
13241 paragraph separate regular expression concatenated with an alternative
13242 expression that consists of the @code{fill-prefix-regexp} followed by
13243 optional whitespace to the end of the line. The whitespace is defined
13244 by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the
13245 regexp as an alternative to @code{parsep}.
13247 According to a comment in the code, the next local variable,
13248 @code{sp-parstart}, is used for searching, and then the final two,
13249 @code{start} and @code{found-start}, are set to @code{nil}.
13251 Now we get into the body of the @code{let*}. The first part of the body
13252 of the @code{let*} deals with the case when the function is given a
13253 negative argument and is therefore moving backwards. We will skip this
13256 @node fwd-para while, , fwd-para let, forward-paragraph
13257 @unnumberedsubsec The forward motion @code{while} loop
13259 The second part of the body of the @code{let*} deals with forward
13260 motion. It is a @code{while} loop that repeats itself so long as the
13261 value of @code{arg} is greater than zero. In the most common use of
13262 the function, the value of the argument is 1, so the body of the
13263 @code{while} loop is evaluated exactly once, and the cursor moves
13264 forward one paragraph.
13267 (while (and (> arg 0) (not (eobp)))
13269 ;; Move forward over separator lines...
13270 (while (and (not (eobp))
13271 (progn (move-to-left-margin) (not (eobp)))
13272 (looking-at parsep))
13274 (unless (eobp) (setq arg (1- arg)))
13275 ;; ... and one more line.
13278 (if fill-prefix-regexp
13279 ;; There is a fill prefix; it overrides parstart.
13280 (while (and (not (eobp))
13281 (progn (move-to-left-margin) (not (eobp)))
13282 (not (looking-at parsep))
13283 (looking-at fill-prefix-regexp))
13286 (while (and (re-search-forward sp-parstart nil 1)
13287 (progn (setq start (match-beginning 0))
13290 (progn (move-to-left-margin)
13291 (not (looking-at parsep)))
13292 (or (not (looking-at parstart))
13293 (and use-hard-newlines
13294 (not (get-text-property (1- start) 'hard)))))
13297 (if (< (point) (point-max))
13298 (goto-char start))))
13301 This part handles three situations: when point is between paragraphs,
13302 when there is a fill prefix and when there is no fill prefix.
13305 The @code{while} loop looks like this:
13309 ;; @r{going forwards and not at the end of the buffer}
13310 (while (and (> arg 0) (not (eobp)))
13312 ;; @r{between paragraphs}
13313 ;; Move forward over separator lines...
13314 (while (and (not (eobp))
13315 (progn (move-to-left-margin) (not (eobp)))
13316 (looking-at parsep))
13318 ;; @r{This decrements the loop}
13319 (unless (eobp) (setq arg (1- arg)))
13320 ;; ... and one more line.
13325 (if fill-prefix-regexp
13326 ;; There is a fill prefix; it overrides parstart;
13327 ;; we go forward line by line
13328 (while (and (not (eobp))
13329 (progn (move-to-left-margin) (not (eobp)))
13330 (not (looking-at parsep))
13331 (looking-at fill-prefix-regexp))
13336 ;; There is no fill prefix;
13337 ;; we go forward character by character
13338 (while (and (re-search-forward sp-parstart nil 1)
13339 (progn (setq start (match-beginning 0))
13342 (progn (move-to-left-margin)
13343 (not (looking-at parsep)))
13344 (or (not (looking-at parstart))
13345 (and use-hard-newlines
13346 (not (get-text-property (1- start) 'hard)))))
13351 ;; and if there is no fill prefix and if we are not at the end,
13352 ;; go to whatever was found in the regular expression search
13354 (if (< (point) (point-max))
13355 (goto-char start))))
13360 We can see that this is a decrementing counter @code{while} loop,
13361 using the expression @code{(setq arg (1- arg))} as the decrementer.
13362 That expression is not far from the @code{while}, but is hidden in
13363 another Lisp macro, an @code{unless} macro. Unless we are at the end
13364 of the buffer --- that is what the @code{eobp} function determines; it
13365 is an abbreviation of @samp{End Of Buffer P} --- we decrease the value
13366 of @code{arg} by one.
13368 (If we are at the end of the buffer, we cannot go forward any more and
13369 the next loop of the @code{while} expression will test false since the
13370 test is an @code{and} with @code{(not (eobp))}. The @code{not}
13371 function means exactly as you expect; it is another name for
13372 @code{null}, a function that returns true when its argument is false.)
13374 Interestingly, the loop count is not decremented until we leave the
13375 space between paragraphs, unless we come to the end of buffer or stop
13376 seeing the local value of the paragraph separator.
13378 That second @code{while} also has a @code{(move-to-left-margin)}
13379 expression. The function is self-explanatory. It is inside a
13380 @code{progn} expression and not the last element of its body, so it is
13381 only invoked for its side effect, which is to move point to the left
13382 margin of the current line.
13385 The @code{looking-at} function is also self-explanatory; it returns
13386 true if the text after point matches the regular expression given as
13389 The rest of the body of the loop looks difficult at first, but makes
13390 sense as you come to understand it.
13393 First consider what happens if there is a fill prefix:
13397 (if fill-prefix-regexp
13398 ;; There is a fill prefix; it overrides parstart;
13399 ;; we go forward line by line
13400 (while (and (not (eobp))
13401 (progn (move-to-left-margin) (not (eobp)))
13402 (not (looking-at parsep))
13403 (looking-at fill-prefix-regexp))
13409 This expression moves point forward line by line so long
13410 as four conditions are true:
13414 Point is not at the end of the buffer.
13417 We can move to the left margin of the text and are
13418 not at the end of the buffer.
13421 The text following point does not separate paragraphs.
13424 The pattern following point is the fill prefix regular expression.
13427 The last condition may be puzzling, until you remember that point was
13428 moved to the beginning of the line early in the @code{forward-paragraph}
13429 function. This means that if the text has a fill prefix, the
13430 @code{looking-at} function will see it.
13433 Consider what happens when there is no fill prefix.
13437 (while (and (re-search-forward sp-parstart nil 1)
13438 (progn (setq start (match-beginning 0))
13441 (progn (move-to-left-margin)
13442 (not (looking-at parsep)))
13443 (or (not (looking-at parstart))
13444 (and use-hard-newlines
13445 (not (get-text-property (1- start) 'hard)))))
13451 This @code{while} loop has us searching forward for
13452 @code{sp-parstart}, which is the combination of possible whitespace
13453 with a the local value of the start of a paragraph or of a paragraph
13454 separator. (The latter two are within an expression starting
13455 @code{\(?:} so that they are not referenced by the
13456 @code{match-beginning} function.)
13459 The two expressions,
13463 (setq start (match-beginning 0))
13469 mean go to the start of the text matched by the regular expression
13472 The @code{(match-beginning 0)} expression is new. It returns a number
13473 specifying the location of the start of the text that was matched by
13476 The @code{match-beginning} function is used here because of a
13477 characteristic of a forward search: a successful forward search,
13478 regardless of whether it is a plain search or a regular expression
13479 search, moves point to the end of the text that is found. In this
13480 case, a successful search moves point to the end of the pattern for
13481 @code{sp-parstart}.
13483 However, we want to put point at the end of the current paragraph, not
13484 somewhere else. Indeed, since the search possibly includes the
13485 paragraph separator, point may end up at the beginning of the next one
13486 unless we use an expression that includes @code{match-beginning}.
13488 @findex match-beginning
13489 When given an argument of 0, @code{match-beginning} returns the
13490 position that is the start of the text matched by the most recent
13491 search. In this case, the most recent search looks for
13492 @code{sp-parstart}. The @code{(match-beginning 0)} expression returns
13493 the beginning position of that pattern, rather than the end position
13496 (Incidentally, when passed a positive number as an argument, the
13497 @code{match-beginning} function returns the location of point at that
13498 parenthesized expression in the last search unless that parenthesized
13499 expression begins with @code{\(?:}. I don't know why @code{\(?:}
13500 appears here since the argument is 0.)
13503 The last expression when there is no fill prefix is
13507 (if (< (point) (point-max))
13508 (goto-char start))))
13513 This says that if there is no fill prefix and if we are not at the
13514 end, point should move to the beginning of whatever was found by the
13515 regular expression search for @code{sp-parstart}.
13517 The full definition for the @code{forward-paragraph} function not only
13518 includes code for going forwards, but also code for going backwards.
13520 If you are reading this inside of GNU Emacs and you want to see the
13521 whole function, you can type @kbd{C-h f} (@code{describe-function})
13522 and the name of the function. This gives you the function
13523 documentation and the name of the library containing the function's
13524 source. Place point over the name of the library and press the RET
13525 key; you will be taken directly to the source. (Be sure to install
13526 your sources! Without them, you are like a person who tries to drive
13527 a car with his eyes shut!)
13529 @node etags, Regexp Review, forward-paragraph, Regexp Search
13530 @section Create Your Own @file{TAGS} File
13532 @cindex @file{TAGS} file, create own
13534 Besides @kbd{C-h f} (@code{describe-function}), another way to see the
13535 source of a function is to type @kbd{M-.} (@code{find-tag}) and the
13536 name of the function when prompted for it. This is a good habit to
13537 get into. The @kbd{M-.} (@code{find-tag}) command takes you directly
13538 to the source for a function, variable, or node. The function depends
13539 on tags tables to tell it where to go.
13541 If the @code{find-tag} function first asks you for the name of a
13542 @file{TAGS} table, give it the name of a @file{TAGS} file such as
13543 @file{/usr/local/src/emacs/src/TAGS}. (The exact path to your
13544 @file{TAGS} file depends on how your copy of Emacs was installed. I
13545 just told you the location that provides both my C and my Emacs Lisp
13548 You can also create your own @file{TAGS} file for directories that
13551 You often need to build and install tags tables yourself. They are
13552 not built automatically. A tags table is called a @file{TAGS} file;
13553 the name is in upper case letters.
13555 You can create a @file{TAGS} file by calling the @code{etags} program
13556 that comes as a part of the Emacs distribution. Usually, @code{etags}
13557 is compiled and installed when Emacs is built. (@code{etags} is not
13558 an Emacs Lisp function or a part of Emacs; it is a C program.)
13561 To create a @file{TAGS} file, first switch to the directory in which
13562 you want to create the file. In Emacs you can do this with the
13563 @kbd{M-x cd} command, or by visiting a file in the directory, or by
13564 listing the directory with @kbd{C-x d} (@code{dired}). Then run the
13565 compile command, with @w{@code{etags *.el}} as the command to execute
13568 M-x compile RET etags *.el RET
13572 to create a @file{TAGS} file for Emacs Lisp.
13574 For example, if you have a large number of files in your
13575 @file{~/emacs} directory, as I do---I have 137 @file{.el} files in it,
13576 of which I load 12---you can create a @file{TAGS} file for the Emacs
13577 Lisp files in that directory.
13580 The @code{etags} program takes all the usual shell `wildcards'. For
13581 example, if you have two directories for which you want a single
13582 @file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where
13583 @file{../elisp/} is the second directory:
13586 M-x compile RET etags *.el ../elisp/*.el RET
13593 M-x compile RET etags --help RET
13597 to see a list of the options accepted by @code{etags} as well as a
13598 list of supported languages.
13600 The @code{etags} program handles more than 20 languages, including
13601 Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java,
13602 LaTeX, Pascal, Perl, Postscript, Python, TeX, Texinfo, makefiles, and
13603 most assemblers. The program has no switches for specifying the
13604 language; it recognizes the language in an input file according to its
13605 file name and contents.
13607 @file{etags} is very helpful when you are writing code yourself and
13608 want to refer back to functions you have already written. Just run
13609 @code{etags} again at intervals as you write new functions, so they
13610 become part of the @file{TAGS} file.
13612 If you think an appropriate @file{TAGS} file already exists for what
13613 you want, but do not know where it is, you can use the @code{locate}
13614 program to attempt to find it.
13616 Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list
13617 for you the full path names of all your @file{TAGS} files. On my
13618 system, this command lists 34 @file{TAGS} files. On the other hand, a
13619 `plain vanilla' system I recently installed did not contain any
13622 If the tags table you want has been created, you can use the @code{M-x
13623 visit-tags-table} command to specify it. Otherwise, you will need to
13624 create the tag table yourself and then use @code{M-x
13627 @subsubheading Building Tags in the Emacs sources
13628 @cindex Building Tags in the Emacs sources
13629 @cindex Tags in the Emacs sources
13632 The GNU Emacs sources come with a @file{Makefile} that contains a
13633 sophisticated @code{etags} command that creates, collects, and merges
13634 tags tables from all over the Emacs sources and puts the information
13635 into one @file{TAGS} file in the @file{src/} directory. (The
13636 @file{src/} directory is below the top level of your Emacs directory.)
13639 To build this @file{TAGS} file, go to the top level of your Emacs
13640 source directory and run the compile command @code{make tags}:
13643 M-x compile RET make tags RET
13647 (The @code{make tags} command works well with the GNU Emacs sources,
13648 as well as with some other source packages.)
13650 For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs
13653 @node Regexp Review, re-search Exercises, etags, Regexp Search
13654 @comment node-name, next, previous, up
13657 Here is a brief summary of some recently introduced functions.
13661 Repeatedly evaluate the body of the expression so long as the first
13662 element of the body tests true. Then return @code{nil}. (The
13663 expression is evaluated only for its side effects.)
13672 (insert (format "foo is %d.\n" foo))
13673 (setq foo (1- foo))))
13675 @result{} foo is 2.
13682 (The @code{insert} function inserts its arguments at point; the
13683 @code{format} function returns a string formatted from its arguments
13684 the way @code{message} formats its arguments; @code{\n} produces a new
13687 @item re-search-forward
13688 Search for a pattern, and if the pattern is found, move point to rest
13692 Takes four arguments, like @code{search-forward}:
13696 A regular expression that specifies the pattern to search for.
13697 (Remember to put quotation marks around this argument!)
13700 Optionally, the limit of the search.
13703 Optionally, what to do if the search fails, return @code{nil} or an
13707 Optionally, how many times to repeat the search; if negative, the
13708 search goes backwards.
13712 Bind some variables locally to particular values,
13713 and then evaluate the remaining arguments, returning the value of the
13714 last one. While binding the local variables, use the local values of
13715 variables bound earlier, if any.
13724 (message "`bar' is %d." bar))
13725 @result{} `bar' is 21.
13729 @item match-beginning
13730 Return the position of the start of the text found by the last regular
13734 Return @code{t} for true if the text after point matches the argument,
13735 which should be a regular expression.
13738 Return @code{t} for true if point is at the end of the accessible part
13739 of a buffer. The end of the accessible part is the end of the buffer
13740 if the buffer is not narrowed; it is the end of the narrowed part if
13741 the buffer is narrowed.
13745 @node re-search Exercises, , Regexp Review, Regexp Search
13746 @section Exercises with @code{re-search-forward}
13750 Write a function to search for a regular expression that matches two
13751 or more blank lines in sequence.
13754 Write a function to search for duplicated words, such as `the the'.
13755 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
13756 Manual}, for information on how to write a regexp (a regular
13757 expression) to match a string that is composed of two identical
13758 halves. You can devise several regexps; some are better than others.
13759 The function I use is described in an appendix, along with several
13760 regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}.
13763 @node Counting Words, Words in a defun, Regexp Search, Top
13764 @chapter Counting: Repetition and Regexps
13765 @cindex Repetition for word counting
13766 @cindex Regular expressions for word counting
13768 Repetition and regular expression searches are powerful tools that you
13769 often use when you write code in Emacs Lisp. This chapter illustrates
13770 the use of regular expression searches through the construction of
13771 word count commands using @code{while} loops and recursion.
13774 * Why Count Words::
13775 * count-words-region::
13776 * recursive-count-words::
13777 * Counting Exercise::
13780 @node Why Count Words, count-words-region, Counting Words, Counting Words
13782 @unnumberedsec Counting words
13785 The standard Emacs distribution contains a function for counting the
13786 number of lines within a region. However, there is no corresponding
13787 function for counting words.
13789 Certain types of writing ask you to count words. Thus, if you write
13790 an essay, you may be limited to 800 words; if you write a novel, you
13791 may discipline yourself to write 1000 words a day. It seems odd to me
13792 that Emacs lacks a word count command. Perhaps people use Emacs
13793 mostly for code or types of documentation that do not require word
13794 counts; or perhaps they restrict themselves to the operating system
13795 word count command, @code{wc}. Alternatively, people may follow
13796 the publishers' convention and compute a word count by dividing the
13797 number of characters in a document by five. In any event, here are
13798 commands to count words.
13800 @node count-words-region, recursive-count-words, Why Count Words, Counting Words
13801 @comment node-name, next, previous, up
13802 @section The @code{count-words-region} Function
13803 @findex count-words-region
13805 A word count command could count words in a line, paragraph, region,
13806 or buffer. What should the command cover? You could design the
13807 command to count the number of words in a complete buffer. However,
13808 the Emacs tradition encourages flexibility---you may want to count
13809 words in just a section, rather than all of a buffer. So it makes
13810 more sense to design the command to count the number of words in a
13811 region. Once you have a @code{count-words-region} command, you can,
13812 if you wish, count words in a whole buffer by marking it with
13813 @w{@kbd{C-x h}} (@code{mark-whole-buffer}).
13815 Clearly, counting words is a repetitive act: starting from the
13816 beginning of the region, you count the first word, then the second
13817 word, then the third word, and so on, until you reach the end of the
13818 region. This means that word counting is ideally suited to recursion
13819 or to a @code{while} loop.
13822 * Design count-words-region::
13826 @node Design count-words-region, Whitespace Bug, count-words-region, count-words-region
13828 @unnumberedsubsec Designing @code{count-words-region}
13831 First, we will implement the word count command with a @code{while}
13832 loop, then with recursion. The command will, of course, be
13836 The template for an interactive function definition is, as always:
13840 (defun @var{name-of-function} (@var{argument-list})
13841 "@var{documentation}@dots{}"
13842 (@var{interactive-expression}@dots{})
13847 What we need to do is fill in the slots.
13849 The name of the function should be self-explanatory and similar to the
13850 existing @code{count-lines-region} name. This makes the name easier
13851 to remember. @code{count-words-region} is a good choice.
13853 The function counts words within a region. This means that the
13854 argument list must contain symbols that are bound to the two
13855 positions, the beginning and end of the region. These two positions
13856 can be called @samp{beginning} and @samp{end} respectively. The first
13857 line of the documentation should be a single sentence, since that is
13858 all that is printed as documentation by a command such as
13859 @code{apropos}. The interactive expression will be of the form
13860 @samp{(interactive "r")}, since that will cause Emacs to pass the
13861 beginning and end of the region to the function's argument list. All
13864 The body of the function needs to be written to do three tasks:
13865 first, to set up conditions under which the @code{while} loop can
13866 count words, second, to run the @code{while} loop, and third, to send
13867 a message to the user.
13869 When a user calls @code{count-words-region}, point may be at the
13870 beginning or the end of the region. However, the counting process
13871 must start at the beginning of the region. This means we will want
13872 to put point there if it is not already there. Executing
13873 @code{(goto-char beginning)} ensures this. Of course, we will want to
13874 return point to its expected position when the function finishes its
13875 work. For this reason, the body must be enclosed in a
13876 @code{save-excursion} expression.
13878 The central part of the body of the function consists of a
13879 @code{while} loop in which one expression jumps point forward word by
13880 word, and another expression counts those jumps. The true-or-false-test
13881 of the @code{while} loop should test true so long as point should jump
13882 forward, and false when point is at the end of the region.
13884 We could use @code{(forward-word 1)} as the expression for moving point
13885 forward word by word, but it is easier to see what Emacs identifies as a
13886 `word' if we use a regular expression search.
13888 A regular expression search that finds the pattern for which it is
13889 searching leaves point after the last character matched. This means
13890 that a succession of successful word searches will move point forward
13893 As a practical matter, we want the regular expression search to jump
13894 over whitespace and punctuation between words as well as over the
13895 words themselves. A regexp that refuses to jump over interword
13896 whitespace would never jump more than one word! This means that
13897 the regexp should include the whitespace and punctuation that follows
13898 a word, if any, as well as the word itself. (A word may end a buffer
13899 and not have any following whitespace or punctuation, so that part of
13900 the regexp must be optional.)
13902 Thus, what we want for the regexp is a pattern defining one or more
13903 word constituent characters followed, optionally, by one or more
13904 characters that are not word constituents. The regular expression for
13912 The buffer's syntax table determines which characters are and are not
13913 word constituents. (@xref{Syntax, , What Constitutes a Word or
13914 Symbol?}, for more about syntax. Also, see @ref{Syntax, Syntax, The
13915 Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, ,
13916 Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
13919 The search expression looks like this:
13922 (re-search-forward "\\w+\\W*")
13926 (Note that paired backslashes precede the @samp{w} and @samp{W}. A
13927 single backslash has special meaning to the Emacs Lisp interpreter.
13928 It indicates that the following character is interpreted differently
13929 than usual. For example, the two characters, @samp{\n}, stand for
13930 @samp{newline}, rather than for a backslash followed by @samp{n}. Two
13931 backslashes in a row stand for an ordinary, `unspecial' backslash, so
13932 Emacs Lisp interpreter ends of seeing a single backslash followed by a
13933 letter. So it discovers the letter is special.)
13935 We need a counter to count how many words there are; this variable
13936 must first be set to 0 and then incremented each time Emacs goes
13937 around the @code{while} loop. The incrementing expression is simply:
13940 (setq count (1+ count))
13943 Finally, we want to tell the user how many words there are in the
13944 region. The @code{message} function is intended for presenting this
13945 kind of information to the user. The message has to be phrased so
13946 that it reads properly regardless of how many words there are in the
13947 region: we don't want to say that ``there are 1 words in the region''.
13948 The conflict between singular and plural is ungrammatical. We can
13949 solve this problem by using a conditional expression that evaluates
13950 different messages depending on the number of words in the region.
13951 There are three possibilities: no words in the region, one word in the
13952 region, and more than one word. This means that the @code{cond}
13953 special form is appropriate.
13956 All this leads to the following function definition:
13960 ;;; @r{First version; has bugs!}
13961 (defun count-words-region (beginning end)
13962 "Print number of words in the region.
13963 Words are defined as at least one word-constituent
13964 character followed by at least one character that
13965 is not a word-constituent. The buffer's syntax
13966 table determines which characters these are."
13968 (message "Counting words in region ... ")
13972 ;;; @r{1. Set up appropriate conditions.}
13974 (goto-char beginning)
13979 ;;; @r{2. Run the} while @r{loop.}
13980 (while (< (point) end)
13981 (re-search-forward "\\w+\\W*")
13982 (setq count (1+ count)))
13986 ;;; @r{3. Send a message to the user.}
13987 (cond ((zerop count)
13989 "The region does NOT have any words."))
13992 "The region has 1 word."))
13995 "The region has %d words." count))))))
14000 As written, the function works, but not in all circumstances.
14002 @node Whitespace Bug, , Design count-words-region, count-words-region
14003 @comment node-name, next, previous, up
14004 @subsection The Whitespace Bug in @code{count-words-region}
14006 The @code{count-words-region} command described in the preceding
14007 section has two bugs, or rather, one bug with two manifestations.
14008 First, if you mark a region containing only whitespace in the middle
14009 of some text, the @code{count-words-region} command tells you that the
14010 region contains one word! Second, if you mark a region containing
14011 only whitespace at the end of the buffer or the accessible portion of
14012 a narrowed buffer, the command displays an error message that looks
14016 Search failed: "\\w+\\W*"
14019 If you are reading this in Info in GNU Emacs, you can test for these
14022 First, evaluate the function in the usual manner to install it.
14024 Here is a copy of the definition. Place your cursor after the closing
14025 parenthesis and type @kbd{C-x C-e} to install it.
14029 ;; @r{First version; has bugs!}
14030 (defun count-words-region (beginning end)
14031 "Print number of words in the region.
14032 Words are defined as at least one word-constituent character followed
14033 by at least one character that is not a word-constituent. The buffer's
14034 syntax table determines which characters these are."
14038 (message "Counting words in region ... ")
14042 ;;; @r{1. Set up appropriate conditions.}
14044 (goto-char beginning)
14049 ;;; @r{2. Run the} while @r{loop.}
14050 (while (< (point) end)
14051 (re-search-forward "\\w+\\W*")
14052 (setq count (1+ count)))
14056 ;;; @r{3. Send a message to the user.}
14057 (cond ((zerop count)
14058 (message "The region does NOT have any words."))
14059 ((= 1 count) (message "The region has 1 word."))
14060 (t (message "The region has %d words." count))))))
14066 If you wish, you can also install this keybinding by evaluating it:
14069 (global-set-key "\C-c=" 'count-words-region)
14072 To conduct the first test, set mark and point to the beginning and end
14073 of the following line and then type @kbd{C-c =} (or @kbd{M-x
14074 count-words-region} if you have not bound @kbd{C-c =}):
14081 Emacs will tell you, correctly, that the region has three words.
14083 Repeat the test, but place mark at the beginning of the line and place
14084 point just @emph{before} the word @samp{one}. Again type the command
14085 @kbd{C-c =} (or @kbd{M-x count-words-region}). Emacs should tell you
14086 that the region has no words, since it is composed only of the
14087 whitespace at the beginning of the line. But instead Emacs tells you
14088 that the region has one word!
14090 For the third test, copy the sample line to the end of the
14091 @file{*scratch*} buffer and then type several spaces at the end of the
14092 line. Place mark right after the word @samp{three} and point at the
14093 end of line. (The end of the line will be the end of the buffer.)
14094 Type @kbd{C-c =} (or @kbd{M-x count-words-region}) as you did before.
14095 Again, Emacs should tell you that the region has no words, since it is
14096 composed only of the whitespace at the end of the line. Instead,
14097 Emacs displays an error message saying @samp{Search failed}.
14099 The two bugs stem from the same problem.
14101 Consider the first manifestation of the bug, in which the command
14102 tells you that the whitespace at the beginning of the line contains
14103 one word. What happens is this: The @code{M-x count-words-region}
14104 command moves point to the beginning of the region. The @code{while}
14105 tests whether the value of point is smaller than the value of
14106 @code{end}, which it is. Consequently, the regular expression search
14107 looks for and finds the first word. It leaves point after the word.
14108 @code{count} is set to one. The @code{while} loop repeats; but this
14109 time the value of point is larger than the value of @code{end}, the
14110 loop is exited; and the function displays a message saying the number
14111 of words in the region is one. In brief, the regular expression
14112 search looks for and finds the word even though it is outside
14115 In the second manifestation of the bug, the region is whitespace at
14116 the end of the buffer. Emacs says @samp{Search failed}. What happens
14117 is that the true-or-false-test in the @code{while} loop tests true, so
14118 the search expression is executed. But since there are no more words
14119 in the buffer, the search fails.
14121 In both manifestations of the bug, the search extends or attempts to
14122 extend outside of the region.
14124 The solution is to limit the search to the region---this is a fairly
14125 simple action, but as you may have come to expect, it is not quite as
14126 simple as you might think.
14128 As we have seen, the @code{re-search-forward} function takes a search
14129 pattern as its first argument. But in addition to this first,
14130 mandatory argument, it accepts three optional arguments. The optional
14131 second argument bounds the search. The optional third argument, if
14132 @code{t}, causes the function to return @code{nil} rather than signal
14133 an error if the search fails. The optional fourth argument is a
14134 repeat count. (In Emacs, you can see a function's documentation by
14135 typing @kbd{C-h f}, the name of the function, and then @key{RET}.)
14137 In the @code{count-words-region} definition, the value of the end of
14138 the region is held by the variable @code{end} which is passed as an
14139 argument to the function. Thus, we can add @code{end} as an argument
14140 to the regular expression search expression:
14143 (re-search-forward "\\w+\\W*" end)
14146 However, if you make only this change to the @code{count-words-region}
14147 definition and then test the new version of the definition on a
14148 stretch of whitespace, you will receive an error message saying
14149 @samp{Search failed}.
14151 What happens is this: the search is limited to the region, and fails
14152 as you expect because there are no word-constituent characters in the
14153 region. Since it fails, we receive an error message. But we do not
14154 want to receive an error message in this case; we want to receive the
14155 message that "The region does NOT have any words."
14157 The solution to this problem is to provide @code{re-search-forward}
14158 with a third argument of @code{t}, which causes the function to return
14159 @code{nil} rather than signal an error if the search fails.
14161 However, if you make this change and try it, you will see the message
14162 ``Counting words in region ... '' and @dots{} you will keep on seeing
14163 that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}).
14165 Here is what happens: the search is limited to the region, as before,
14166 and it fails because there are no word-constituent characters in the
14167 region, as expected. Consequently, the @code{re-search-forward}
14168 expression returns @code{nil}. It does nothing else. In particular,
14169 it does not move point, which it does as a side effect if it finds the
14170 search target. After the @code{re-search-forward} expression returns
14171 @code{nil}, the next expression in the @code{while} loop is evaluated.
14172 This expression increments the count. Then the loop repeats. The
14173 true-or-false-test tests true because the value of point is still less
14174 than the value of end, since the @code{re-search-forward} expression
14175 did not move point. @dots{} and the cycle repeats @dots{}
14177 The @code{count-words-region} definition requires yet another
14178 modification, to cause the true-or-false-test of the @code{while} loop
14179 to test false if the search fails. Put another way, there are two
14180 conditions that must be satisfied in the true-or-false-test before the
14181 word count variable is incremented: point must still be within the
14182 region and the search expression must have found a word to count.
14184 Since both the first condition and the second condition must be true
14185 together, the two expressions, the region test and the search
14186 expression, can be joined with an @code{and} special form and embedded in
14187 the @code{while} loop as the true-or-false-test, like this:
14190 (and (< (point) end) (re-search-forward "\\w+\\W*" end t))
14193 @c colon in printed section title causes problem in Info cross reference
14194 @c also trouble with an overfull hbox
14197 (For information about @code{and}, see
14198 @ref{kill-new function, , The @code{kill-new} function}.)
14202 (@xref{kill-new function, , The @code{kill-new} function}, for
14203 information about @code{and}.)
14206 The @code{re-search-forward} expression returns @code{t} if the search
14207 succeeds and as a side effect moves point. Consequently, as words are
14208 found, point is moved through the region. When the search expression
14209 fails to find another word, or when point reaches the end of the
14210 region, the true-or-false-test tests false, the @code{while} loop
14211 exits, and the @code{count-words-region} function displays one or
14212 other of its messages.
14214 After incorporating these final changes, the @code{count-words-region}
14215 works without bugs (or at least, without bugs that I have found!).
14216 Here is what it looks like:
14220 ;;; @r{Final version:} @code{while}
14221 (defun count-words-region (beginning end)
14222 "Print number of words in the region."
14224 (message "Counting words in region ... ")
14228 ;;; @r{1. Set up appropriate conditions.}
14231 (goto-char beginning)
14235 ;;; @r{2. Run the} while @r{loop.}
14236 (while (and (< (point) end)
14237 (re-search-forward "\\w+\\W*" end t))
14238 (setq count (1+ count)))
14242 ;;; @r{3. Send a message to the user.}
14243 (cond ((zerop count)
14245 "The region does NOT have any words."))
14248 "The region has 1 word."))
14251 "The region has %d words." count))))))
14255 @node recursive-count-words, Counting Exercise, count-words-region, Counting Words
14256 @comment node-name, next, previous, up
14257 @section Count Words Recursively
14258 @cindex Count words recursively
14259 @cindex Recursively counting words
14260 @cindex Words, counted recursively
14262 You can write the function for counting words recursively as well as
14263 with a @code{while} loop. Let's see how this is done.
14265 First, we need to recognize that the @code{count-words-region}
14266 function has three jobs: it sets up the appropriate conditions for
14267 counting to occur; it counts the words in the region; and it sends a
14268 message to the user telling how many words there are.
14270 If we write a single recursive function to do everything, we will
14271 receive a message for every recursive call. If the region contains 13
14272 words, we will receive thirteen messages, one right after the other.
14273 We don't want this! Instead, we must write two functions to do the
14274 job, one of which (the recursive function) will be used inside of the
14275 other. One function will set up the conditions and display the
14276 message; the other will return the word count.
14278 Let us start with the function that causes the message to be displayed.
14279 We can continue to call this @code{count-words-region}.
14281 This is the function that the user will call. It will be interactive.
14282 Indeed, it will be similar to our previous versions of this
14283 function, except that it will call @code{recursive-count-words} to
14284 determine how many words are in the region.
14287 We can readily construct a template for this function, based on our
14292 ;; @r{Recursive version; uses regular expression search}
14293 (defun count-words-region (beginning end)
14294 "@var{documentation}@dots{}"
14295 (@var{interactive-expression}@dots{})
14299 ;;; @r{1. Set up appropriate conditions.}
14300 (@var{explanatory message})
14301 (@var{set-up functions}@dots{}
14305 ;;; @r{2. Count the words.}
14306 @var{recursive call}
14310 ;;; @r{3. Send a message to the user.}
14311 @var{message providing word count}))
14315 The definition looks straightforward, except that somehow the count
14316 returned by the recursive call must be passed to the message
14317 displaying the word count. A little thought suggests that this can be
14318 done by making use of a @code{let} expression: we can bind a variable
14319 in the varlist of a @code{let} expression to the number of words in
14320 the region, as returned by the recursive call; and then the
14321 @code{cond} expression, using binding, can display the value to the
14324 Often, one thinks of the binding within a @code{let} expression as
14325 somehow secondary to the `primary' work of a function. But in this
14326 case, what you might consider the `primary' job of the function,
14327 counting words, is done within the @code{let} expression.
14330 Using @code{let}, the function definition looks like this:
14334 (defun count-words-region (beginning end)
14335 "Print number of words in the region."
14340 ;;; @r{1. Set up appropriate conditions.}
14341 (message "Counting words in region ... ")
14343 (goto-char beginning)
14347 ;;; @r{2. Count the words.}
14348 (let ((count (recursive-count-words end)))
14352 ;;; @r{3. Send a message to the user.}
14353 (cond ((zerop count)
14355 "The region does NOT have any words."))
14358 "The region has 1 word."))
14361 "The region has %d words." count))))))
14365 Next, we need to write the recursive counting function.
14367 A recursive function has at least three parts: the `do-again-test', the
14368 `next-step-expression', and the recursive call.
14370 The do-again-test determines whether the function will or will not be
14371 called again. Since we are counting words in a region and can use a
14372 function that moves point forward for every word, the do-again-test
14373 can check whether point is still within the region. The do-again-test
14374 should find the value of point and determine whether point is before,
14375 at, or after the value of the end of the region. We can use the
14376 @code{point} function to locate point. Clearly, we must pass the
14377 value of the end of the region to the recursive counting function as an
14380 In addition, the do-again-test should also test whether the search finds a
14381 word. If it does not, the function should not call itself again.
14383 The next-step-expression changes a value so that when the recursive
14384 function is supposed to stop calling itself, it stops. More
14385 precisely, the next-step-expression changes a value so that at the
14386 right time, the do-again-test stops the recursive function from
14387 calling itself again. In this case, the next-step-expression can be
14388 the expression that moves point forward, word by word.
14390 The third part of a recursive function is the recursive call.
14392 Somewhere, also, we also need a part that does the `work' of the
14393 function, a part that does the counting. A vital part!
14396 But already, we have an outline of the recursive counting function:
14400 (defun recursive-count-words (region-end)
14401 "@var{documentation}@dots{}"
14402 @var{do-again-test}
14403 @var{next-step-expression}
14404 @var{recursive call})
14408 Now we need to fill in the slots. Let's start with the simplest cases
14409 first: if point is at or beyond the end of the region, there cannot
14410 be any words in the region, so the function should return zero.
14411 Likewise, if the search fails, there are no words to count, so the
14412 function should return zero.
14414 On the other hand, if point is within the region and the search
14415 succeeds, the function should call itself again.
14418 Thus, the do-again-test should look like this:
14422 (and (< (point) region-end)
14423 (re-search-forward "\\w+\\W*" region-end t))
14427 Note that the search expression is part of the do-again-test---the
14428 function returns @code{t} if its search succeeds and @code{nil} if it
14429 fails. (@xref{Whitespace Bug, , The Whitespace Bug in
14430 @code{count-words-region}}, for an explanation of how
14431 @code{re-search-forward} works.)
14433 The do-again-test is the true-or-false test of an @code{if} clause.
14434 Clearly, if the do-again-test succeeds, the then-part of the @code{if}
14435 clause should call the function again; but if it fails, the else-part
14436 should return zero since either point is outside the region or the
14437 search failed because there were no words to find.
14439 But before considering the recursive call, we need to consider the
14440 next-step-expression. What is it? Interestingly, it is the search
14441 part of the do-again-test.
14443 In addition to returning @code{t} or @code{nil} for the
14444 do-again-test, @code{re-search-forward} moves point forward as a side
14445 effect of a successful search. This is the action that changes the
14446 value of point so that the recursive function stops calling itself
14447 when point completes its movement through the region. Consequently,
14448 the @code{re-search-forward} expression is the next-step-expression.
14451 In outline, then, the body of the @code{recursive-count-words}
14452 function looks like this:
14456 (if @var{do-again-test-and-next-step-combined}
14458 @var{recursive-call-returning-count}
14464 How to incorporate the mechanism that counts?
14466 If you are not used to writing recursive functions, a question like
14467 this can be troublesome. But it can and should be approached
14470 We know that the counting mechanism should be associated in some way
14471 with the recursive call. Indeed, since the next-step-expression moves
14472 point forward by one word, and since a recursive call is made for
14473 each word, the counting mechanism must be an expression that adds one
14474 to the value returned by a call to @code{recursive-count-words}.
14477 Consider several cases:
14481 If there are two words in the region, the function should return
14482 a value resulting from adding one to the value returned when it counts
14483 the first word, plus the number returned when it counts the remaining
14484 words in the region, which in this case is one.
14487 If there is one word in the region, the function should return
14488 a value resulting from adding one to the value returned when it counts
14489 that word, plus the number returned when it counts the remaining
14490 words in the region, which in this case is zero.
14493 If there are no words in the region, the function should return zero.
14496 From the sketch we can see that the else-part of the @code{if} returns
14497 zero for the case of no words. This means that the then-part of the
14498 @code{if} must return a value resulting from adding one to the value
14499 returned from a count of the remaining words.
14502 The expression will look like this, where @code{1+} is a function that
14503 adds one to its argument.
14506 (1+ (recursive-count-words region-end))
14510 The whole @code{recursive-count-words} function will then look like
14515 (defun recursive-count-words (region-end)
14516 "@var{documentation}@dots{}"
14518 ;;; @r{1. do-again-test}
14519 (if (and (< (point) region-end)
14520 (re-search-forward "\\w+\\W*" region-end t))
14524 ;;; @r{2. then-part: the recursive call}
14525 (1+ (recursive-count-words region-end))
14527 ;;; @r{3. else-part}
14533 Let's examine how this works:
14535 If there are no words in the region, the else part of the @code{if}
14536 expression is evaluated and consequently the function returns zero.
14538 If there is one word in the region, the value of point is less than
14539 the value of @code{region-end} and the search succeeds. In this case,
14540 the true-or-false-test of the @code{if} expression tests true, and the
14541 then-part of the @code{if} expression is evaluated. The counting
14542 expression is evaluated. This expression returns a value (which will
14543 be the value returned by the whole function) that is the sum of one
14544 added to the value returned by a recursive call.
14546 Meanwhile, the next-step-expression has caused point to jump over the
14547 first (and in this case only) word in the region. This means that
14548 when @code{(recursive-count-words region-end)} is evaluated a second
14549 time, as a result of the recursive call, the value of point will be
14550 equal to or greater than the value of region end. So this time,
14551 @code{recursive-count-words} will return zero. The zero will be added
14552 to one, and the original evaluation of @code{recursive-count-words}
14553 will return one plus zero, which is one, which is the correct amount.
14555 Clearly, if there are two words in the region, the first call to
14556 @code{recursive-count-words} returns one added to the value returned
14557 by calling @code{recursive-count-words} on a region containing the
14558 remaining word---that is, it adds one to one, producing two, which is
14559 the correct amount.
14561 Similarly, if there are three words in the region, the first call to
14562 @code{recursive-count-words} returns one added to the value returned
14563 by calling @code{recursive-count-words} on a region containing the
14564 remaining two words---and so on and so on.
14568 With full documentation the two functions look like this:
14572 The recursive function:
14574 @findex recursive-count-words
14577 (defun recursive-count-words (region-end)
14578 "Number of words between point and REGION-END."
14582 ;;; @r{1. do-again-test}
14583 (if (and (< (point) region-end)
14584 (re-search-forward "\\w+\\W*" region-end t))
14588 ;;; @r{2. then-part: the recursive call}
14589 (1+ (recursive-count-words region-end))
14591 ;;; @r{3. else-part}
14602 ;;; @r{Recursive version}
14603 (defun count-words-region (beginning end)
14604 "Print number of words in the region.
14608 Words are defined as at least one word-constituent
14609 character followed by at least one character that is
14610 not a word-constituent. The buffer's syntax table
14611 determines which characters these are."
14615 (message "Counting words in region ... ")
14617 (goto-char beginning)
14618 (let ((count (recursive-count-words end)))
14621 (cond ((zerop count)
14623 "The region does NOT have any words."))
14627 (message "The region has 1 word."))
14630 "The region has %d words." count))))))
14634 @node Counting Exercise, , recursive-count-words, Counting Words
14635 @section Exercise: Counting Punctuation
14637 Using a @code{while} loop, write a function to count the number of
14638 punctuation marks in a region---period, comma, semicolon, colon,
14639 exclamation mark, and question mark. Do the same using recursion.
14641 @node Words in a defun, Readying a Graph, Counting Words, Top
14642 @chapter Counting Words in a @code{defun}
14643 @cindex Counting words in a @code{defun}
14644 @cindex Word counting in a @code{defun}
14646 Our next project is to count the number of words in a function
14647 definition. Clearly, this can be done using some variant of
14648 @code{count-word-region}. @xref{Counting Words, , Counting Words:
14649 Repetition and Regexps}. If we are just going to count the words in
14650 one definition, it is easy enough to mark the definition with the
14651 @kbd{C-M-h} (@code{mark-defun}) command, and then call
14652 @code{count-word-region}.
14654 However, I am more ambitious: I want to count the words and symbols in
14655 every definition in the Emacs sources and then print a graph that
14656 shows how many functions there are of each length: how many contain 40
14657 to 49 words or symbols, how many contain 50 to 59 words or symbols,
14658 and so on. I have often been curious how long a typical function is,
14659 and this will tell.
14662 * Divide and Conquer::
14663 * Words and Symbols::
14665 * count-words-in-defun::
14668 * lengths-list-file::
14670 * Several files recursively::
14671 * Prepare the data::
14674 @node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun
14676 @unnumberedsec Divide and Conquer
14679 Described in one phrase, the histogram project is daunting; but
14680 divided into numerous small steps, each of which we can take one at a
14681 time, the project becomes less fearsome. Let us consider what the
14686 First, write a function to count the words in one definition. This
14687 includes the problem of handling symbols as well as words.
14690 Second, write a function to list the numbers of words in each function
14691 in a file. This function can use the @code{count-words-in-defun}
14695 Third, write a function to list the numbers of words in each function
14696 in each of several files. This entails automatically finding the
14697 various files, switching to them, and counting the words in the
14698 definitions within them.
14701 Fourth, write a function to convert the list of numbers that we
14702 created in step three to a form that will be suitable for printing as
14706 Fifth, write a function to print the results as a graph.
14709 This is quite a project! But if we take each step slowly, it will not
14712 @node Words and Symbols, Syntax, Divide and Conquer, Words in a defun
14713 @section What to Count?
14714 @cindex Words and symbols in defun
14716 When we first start thinking about how to count the words in a
14717 function definition, the first question is (or ought to be) what are
14718 we going to count? When we speak of `words' with respect to a Lisp
14719 function definition, we are actually speaking, in large part, of
14720 `symbols'. For example, the following @code{multiply-by-seven}
14721 function contains the five symbols @code{defun},
14722 @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In
14723 addition, in the documentation string, it contains the four words
14724 @samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The
14725 symbol @samp{number} is repeated, so the definition contains a total
14726 of ten words and symbols.
14730 (defun multiply-by-seven (number)
14731 "Multiply NUMBER by seven."
14737 However, if we mark the @code{multiply-by-seven} definition with
14738 @kbd{C-M-h} (@code{mark-defun}), and then call
14739 @code{count-words-region} on it, we will find that
14740 @code{count-words-region} claims the definition has eleven words, not
14741 ten! Something is wrong!
14743 The problem is twofold: @code{count-words-region} does not count the
14744 @samp{*} as a word, and it counts the single symbol,
14745 @code{multiply-by-seven}, as containing three words. The hyphens are
14746 treated as if they were interword spaces rather than intraword
14747 connectors: @samp{multiply-by-seven} is counted as if it were written
14748 @samp{multiply by seven}.
14750 The cause of this confusion is the regular expression search within
14751 the @code{count-words-region} definition that moves point forward word
14752 by word. In the canonical version of @code{count-words-region}, the
14760 This regular expression is a pattern defining one or more word
14761 constituent characters possibly followed by one or more characters
14762 that are not word constituents. What is meant by `word constituent
14763 characters' brings us to the issue of syntax, which is worth a section
14766 @node Syntax, count-words-in-defun, Words and Symbols, Words in a defun
14767 @section What Constitutes a Word or Symbol?
14768 @cindex Syntax categories and tables
14770 Emacs treats different characters as belonging to different
14771 @dfn{syntax categories}. For example, the regular expression,
14772 @samp{\\w+}, is a pattern specifying one or more @emph{word
14773 constituent} characters. Word constituent characters are members of
14774 one syntax category. Other syntax categories include the class of
14775 punctuation characters, such as the period and the comma, and the
14776 class of whitespace characters, such as the blank space and the tab
14777 character. (For more information, see @ref{Syntax, Syntax, The Syntax
14778 Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , Syntax
14779 Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
14781 Syntax tables specify which characters belong to which categories.
14782 Usually, a hyphen is not specified as a `word constituent character'.
14783 Instead, it is specified as being in the `class of characters that are
14784 part of symbol names but not words.' This means that the
14785 @code{count-words-region} function treats it in the same way it treats
14786 an interword white space, which is why @code{count-words-region}
14787 counts @samp{multiply-by-seven} as three words.
14789 There are two ways to cause Emacs to count @samp{multiply-by-seven} as
14790 one symbol: modify the syntax table or modify the regular expression.
14792 We could redefine a hyphen as a word constituent character by
14793 modifying the syntax table that Emacs keeps for each mode. This
14794 action would serve our purpose, except that a hyphen is merely the
14795 most common character within symbols that is not typically a word
14796 constituent character; there are others, too.
14798 Alternatively, we can redefine the regular expression used in the
14799 @code{count-words} definition so as to include symbols. This
14800 procedure has the merit of clarity, but the task is a little tricky.
14803 The first part is simple enough: the pattern must match ``at least one
14804 character that is a word or symbol constituent''. Thus:
14807 "\\(\\w\\|\\s_\\)+"
14811 The @samp{\\(} is the first part of the grouping construct that
14812 includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated
14813 by the @samp{\\|}. The @samp{\\w} matches any word-constituent
14814 character and the @samp{\\s_} matches any character that is part of a
14815 symbol name but not a word-constituent character. The @samp{+}
14816 following the group indicates that the word or symbol constituent
14817 characters must be matched at least once.
14819 However, the second part of the regexp is more difficult to design.
14820 What we want is to follow the first part with ``optionally one or more
14821 characters that are not constituents of a word or symbol''. At first,
14822 I thought I could define this with the following:
14825 "\\(\\W\\|\\S_\\)*"
14829 The upper case @samp{W} and @samp{S} match characters that are
14830 @emph{not} word or symbol constituents. Unfortunately, this
14831 expression matches any character that is either not a word constituent
14832 or not a symbol constituent. This matches any character!
14834 I then noticed that every word or symbol in my test region was
14835 followed by white space (blank space, tab, or newline). So I tried
14836 placing a pattern to match one or more blank spaces after the pattern
14837 for one or more word or symbol constituents. This failed, too. Words
14838 and symbols are often separated by whitespace, but in actual code
14839 parentheses may follow symbols and punctuation may follow words. So
14840 finally, I designed a pattern in which the word or symbol constituents
14841 are followed optionally by characters that are not white space and
14842 then followed optionally by white space.
14845 Here is the full regular expression:
14848 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14851 @node count-words-in-defun, Several defuns, Syntax, Words in a defun
14852 @section The @code{count-words-in-defun} Function
14853 @cindex Counting words in a @code{defun}
14855 We have seen that there are several ways to write a
14856 @code{count-word-region} function. To write a
14857 @code{count-words-in-defun}, we need merely adapt one of these
14860 The version that uses a @code{while} loop is easy to understand, so I
14861 am going to adapt that. Because @code{count-words-in-defun} will be
14862 part of a more complex program, it need not be interactive and it need
14863 not display a message but just return the count. These considerations
14864 simplify the definition a little.
14866 On the other hand, @code{count-words-in-defun} will be used within a
14867 buffer that contains function definitions. Consequently, it is
14868 reasonable to ask that the function determine whether it is called
14869 when point is within a function definition, and if it is, to return
14870 the count for that definition. This adds complexity to the
14871 definition, but saves us from needing to pass arguments to the
14875 These considerations lead us to prepare the following template:
14879 (defun count-words-in-defun ()
14880 "@var{documentation}@dots{}"
14881 (@var{set up}@dots{}
14882 (@var{while loop}@dots{})
14883 @var{return count})
14888 As usual, our job is to fill in the slots.
14892 We are presuming that this function will be called within a buffer
14893 containing function definitions. Point will either be within a
14894 function definition or not. For @code{count-words-in-defun} to work,
14895 point must move to the beginning of the definition, a counter must
14896 start at zero, and the counting loop must stop when point reaches the
14897 end of the definition.
14899 The @code{beginning-of-defun} function searches backwards for an
14900 opening delimiter such as a @samp{(} at the beginning of a line, and
14901 moves point to that position, or else to the limit of the search. In
14902 practice, this means that @code{beginning-of-defun} moves point to the
14903 beginning of an enclosing or preceding function definition, or else to
14904 the beginning of the buffer. We can use @code{beginning-of-defun} to
14905 place point where we wish to start.
14907 The @code{while} loop requires a counter to keep track of the words or
14908 symbols being counted. A @code{let} expression can be used to create
14909 a local variable for this purpose, and bind it to an initial value of zero.
14911 The @code{end-of-defun} function works like @code{beginning-of-defun}
14912 except that it moves point to the end of the definition.
14913 @code{end-of-defun} can be used as part of an expression that
14914 determines the position of the end of the definition.
14916 The set up for @code{count-words-in-defun} takes shape rapidly: first
14917 we move point to the beginning of the definition, then we create a
14918 local variable to hold the count, and finally, we record the position
14919 of the end of the definition so the @code{while} loop will know when to stop
14923 The code looks like this:
14927 (beginning-of-defun)
14929 (end (save-excursion (end-of-defun) (point))))
14934 The code is simple. The only slight complication is likely to concern
14935 @code{end}: it is bound to the position of the end of the definition
14936 by a @code{save-excursion} expression that returns the value of point
14937 after @code{end-of-defun} temporarily moves it to the end of the
14940 The second part of the @code{count-words-in-defun}, after the set up,
14941 is the @code{while} loop.
14943 The loop must contain an expression that jumps point forward word by
14944 word and symbol by symbol, and another expression that counts the
14945 jumps. The true-or-false-test for the @code{while} loop should test
14946 true so long as point should jump forward, and false when point is at
14947 the end of the definition. We have already redefined the regular
14948 expression for this (@pxref{Syntax}), so the loop is straightforward:
14952 (while (and (< (point) end)
14954 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t)
14955 (setq count (1+ count)))
14959 The third part of the function definition returns the count of words
14960 and symbols. This part is the last expression within the body of the
14961 @code{let} expression, and can be, very simply, the local variable
14962 @code{count}, which when evaluated returns the count.
14965 Put together, the @code{count-words-in-defun} definition looks like this:
14967 @findex count-words-in-defun
14970 (defun count-words-in-defun ()
14971 "Return the number of words and symbols in a defun."
14972 (beginning-of-defun)
14974 (end (save-excursion (end-of-defun) (point))))
14978 (and (< (point) end)
14980 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14982 (setq count (1+ count)))
14987 How to test this? The function is not interactive, but it is easy to
14988 put a wrapper around the function to make it interactive; we can use
14989 almost the same code as for the recursive version of
14990 @code{count-words-region}:
14994 ;;; @r{Interactive version.}
14995 (defun count-words-defun ()
14996 "Number of words and symbols in a function definition."
14999 "Counting words and symbols in function definition ... ")
15002 (let ((count (count-words-in-defun)))
15006 "The definition does NOT have any words or symbols."))
15011 "The definition has 1 word or symbol."))
15014 "The definition has %d words or symbols." count)))))
15020 Let's re-use @kbd{C-c =} as a convenient keybinding:
15023 (global-set-key "\C-c=" 'count-words-defun)
15026 Now we can try out @code{count-words-defun}: install both
15027 @code{count-words-in-defun} and @code{count-words-defun}, and set the
15028 keybinding, and then place the cursor within the following definition:
15032 (defun multiply-by-seven (number)
15033 "Multiply NUMBER by seven."
15040 Success! The definition has 10 words and symbols.
15042 The next problem is to count the numbers of words and symbols in
15043 several definitions within a single file.
15045 @node Several defuns, Find a File, count-words-in-defun, Words in a defun
15046 @section Count Several @code{defuns} Within a File
15048 A file such as @file{simple.el} may have a hundred or more function
15049 definitions within it. Our long term goal is to collect statistics on
15050 many files, but as a first step, our immediate goal is to collect
15051 statistics on one file.
15053 The information will be a series of numbers, each number being the
15054 length of a function definition. We can store the numbers in a list.
15056 We know that we will want to incorporate the information regarding one
15057 file with information about many other files; this means that the
15058 function for counting definition lengths within one file need only
15059 return the list of lengths. It need not and should not display any
15062 The word count commands contain one expression to jump point forward
15063 word by word and another expression to count the jumps. The function
15064 to return the lengths of definitions can be designed to work the same
15065 way, with one expression to jump point forward definition by
15066 definition and another expression to construct the lengths' list.
15068 This statement of the problem makes it elementary to write the
15069 function definition. Clearly, we will start the count at the
15070 beginning of the file, so the first command will be @code{(goto-char
15071 (point-min))}. Next, we start the @code{while} loop; and the
15072 true-or-false test of the loop can be a regular expression search for
15073 the next function definition---so long as the search succeeds, point
15074 is moved forward and then the body of the loop is evaluated. The body
15075 needs an expression that constructs the lengths' list. @code{cons},
15076 the list construction command, can be used to create the list. That
15077 is almost all there is to it.
15080 Here is what this fragment of code looks like:
15084 (goto-char (point-min))
15085 (while (re-search-forward "^(defun" nil t)
15087 (cons (count-words-in-defun) lengths-list)))
15091 What we have left out is the mechanism for finding the file that
15092 contains the function definitions.
15094 In previous examples, we either used this, the Info file, or we
15095 switched back and forth to some other buffer, such as the
15096 @file{*scratch*} buffer.
15098 Finding a file is a new process that we have not yet discussed.
15100 @node Find a File, lengths-list-file, Several defuns, Words in a defun
15101 @comment node-name, next, previous, up
15102 @section Find a File
15103 @cindex Find a File
15105 To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file})
15106 command. This command is almost, but not quite right for the lengths
15110 Let's look at the source for @code{find-file}:
15114 (defun find-file (filename)
15115 "Edit file FILENAME.
15116 Switch to a buffer visiting file FILENAME,
15117 creating one if none already exists."
15118 (interactive "FFind file: ")
15119 (switch-to-buffer (find-file-noselect filename)))
15124 (The most recent version of the @code{find-file} function definition
15125 permits you to specify optional wildcards to visit multiple files; that
15126 makes the definition more complex and we will not discuss it here,
15127 since it is not relevant. You can see its source using either
15128 @kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).)
15132 (defun find-file (filename &optional wildcards)
15133 "Edit file FILENAME.
15134 Switch to a buffer visiting file FILENAME,
15135 creating one if none already exists.
15136 Interactively, the default if you just type RET is the current directory,
15137 but the visited file name is available through the minibuffer history:
15138 type M-n to pull it into the minibuffer.
15140 Interactively, or if WILDCARDS is non-nil in a call from Lisp,
15141 expand wildcards (if any) and visit multiple files. You can
15142 suppress wildcard expansion by setting `find-file-wildcards' to nil.
15144 To visit a file without any kind of conversion and without
15145 automatically choosing a major mode, use \\[find-file-literally]."
15146 (interactive (find-file-read-args "Find file: " nil))
15147 (let ((value (find-file-noselect filename nil nil wildcards)))
15149 (mapcar 'switch-to-buffer (nreverse value))
15150 (switch-to-buffer value))))
15153 The definition I am showing possesses short but complete documentation
15154 and an interactive specification that prompts you for a file name when
15155 you use the command interactively. The body of the definition
15156 contains two functions, @code{find-file-noselect} and
15157 @code{switch-to-buffer}.
15159 According to its documentation as shown by @kbd{C-h f} (the
15160 @code{describe-function} command), the @code{find-file-noselect}
15161 function reads the named file into a buffer and returns the buffer.
15162 (Its most recent version includes an optional wildcards argument,
15163 too, as well as another to read a file literally and an other you
15164 suppress warning messages. These optional arguments are irrelevant.)
15166 However, the @code{find-file-noselect} function does not select the
15167 buffer in which it puts the file. Emacs does not switch its attention
15168 (or yours if you are using @code{find-file-noselect}) to the selected
15169 buffer. That is what @code{switch-to-buffer} does: it switches the
15170 buffer to which Emacs attention is directed; and it switches the
15171 buffer displayed in the window to the new buffer. We have discussed
15172 buffer switching elsewhere. (@xref{Switching Buffers}.)
15174 In this histogram project, we do not need to display each file on the
15175 screen as the program determines the length of each definition within
15176 it. Instead of employing @code{switch-to-buffer}, we can work with
15177 @code{set-buffer}, which redirects the attention of the computer
15178 program to a different buffer but does not redisplay it on the screen.
15179 So instead of calling on @code{find-file} to do the job, we must write
15180 our own expression.
15182 The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
15184 @node lengths-list-file, Several files, Find a File, Words in a defun
15185 @section @code{lengths-list-file} in Detail
15187 The core of the @code{lengths-list-file} function is a @code{while}
15188 loop containing a function to move point forward `defun by defun' and
15189 a function to count the number of words and symbols in each defun.
15190 This core must be surrounded by functions that do various other tasks,
15191 including finding the file, and ensuring that point starts out at the
15192 beginning of the file. The function definition looks like this:
15193 @findex lengths-list-file
15197 (defun lengths-list-file (filename)
15198 "Return list of definitions' lengths within FILE.
15199 The returned list is a list of numbers.
15200 Each number is the number of words or
15201 symbols in one function definition."
15204 (message "Working on `%s' ... " filename)
15206 (let ((buffer (find-file-noselect filename))
15208 (set-buffer buffer)
15209 (setq buffer-read-only t)
15211 (goto-char (point-min))
15212 (while (re-search-forward "^(defun" nil t)
15214 (cons (count-words-in-defun) lengths-list)))
15215 (kill-buffer buffer)
15221 The function is passed one argument, the name of the file on which it
15222 will work. It has four lines of documentation, but no interactive
15223 specification. Since people worry that a computer is broken if they
15224 don't see anything going on, the first line of the body is a
15227 The next line contains a @code{save-excursion} that returns Emacs'
15228 attention to the current buffer when the function completes. This is
15229 useful in case you embed this function in another function that
15230 presumes point is restored to the original buffer.
15232 In the varlist of the @code{let} expression, Emacs finds the file and
15233 binds the local variable @code{buffer} to the buffer containing the
15234 file. At the same time, Emacs creates @code{lengths-list} as a local
15237 Next, Emacs switches its attention to the buffer.
15239 In the following line, Emacs makes the buffer read-only. Ideally,
15240 this line is not necessary. None of the functions for counting words
15241 and symbols in a function definition should change the buffer.
15242 Besides, the buffer is not going to be saved, even if it were changed.
15243 This line is entirely the consequence of great, perhaps excessive,
15244 caution. The reason for the caution is that this function and those
15245 it calls work on the sources for Emacs and it is inconvenient if they
15246 are inadvertently modified. It goes without saying that I did not
15247 realize a need for this line until an experiment went awry and started
15248 to modify my Emacs source files @dots{}
15250 Next comes a call to widen the buffer if it is narrowed. This
15251 function is usually not needed---Emacs creates a fresh buffer if none
15252 already exists; but if a buffer visiting the file already exists Emacs
15253 returns that one. In this case, the buffer may be narrowed and must
15254 be widened. If we wanted to be fully `user-friendly', we would
15255 arrange to save the restriction and the location of point, but we
15258 The @code{(goto-char (point-min))} expression moves point to the
15259 beginning of the buffer.
15261 Then comes a @code{while} loop in which the `work' of the function is
15262 carried out. In the loop, Emacs determines the length of each
15263 definition and constructs a lengths' list containing the information.
15265 Emacs kills the buffer after working through it. This is to save
15266 space inside of Emacs. My version of GNU Emacs 19 contained over 300
15267 source files of interest; GNU Emacs 22 contains over a thousand source
15268 files. Another function will apply @code{lengths-list-file} to each
15271 Finally, the last expression within the @code{let} expression is the
15272 @code{lengths-list} variable; its value is returned as the value of
15273 the whole function.
15275 You can try this function by installing it in the usual fashion. Then
15276 place your cursor after the following expression and type @kbd{C-x
15277 C-e} (@code{eval-last-sexp}).
15279 @c !!! 22.1.1 lisp sources location here
15282 "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el")
15286 (You may need to change the pathname of the file; the one here is for
15287 GNU Emacs version 22.1.1. To change the expression, copy it to
15288 the @file{*scratch*} buffer and edit it.
15292 (Also, to see the full length of the list, rather than a truncated
15293 version, you may have to evaluate the following:
15296 (custom-set-variables '(eval-expression-print-length nil))
15300 (@xref{defcustom, , Specifying Variables using @code{defcustom}}.
15301 Then evaluate the @code{lengths-list-file} expression.)
15304 The lengths' list for @file{debug.el} takes less than a second to
15305 produce and looks like this in GNU Emacs 22:
15308 (83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587)
15312 (Using my old machine, the version 19 lengths' list for @file{debug.el}
15313 took seven seconds to produce and looked like this:
15316 (75 41 80 62 20 45 44 68 45 12 34 235)
15319 (The newer version of @file{debug.el} contains more defuns than the
15320 earlier one; and my new machine is much faster than the old one.)
15322 Note that the length of the last definition in the file is first in
15325 @node Several files, Several files recursively, lengths-list-file, Words in a defun
15326 @section Count Words in @code{defuns} in Different Files
15328 In the previous section, we created a function that returns a list of
15329 the lengths of each definition in a file. Now, we want to define a
15330 function to return a master list of the lengths of the definitions in
15333 Working on each of a list of files is a repetitious act, so we can use
15334 either a @code{while} loop or recursion.
15337 * lengths-list-many-files::
15341 @node lengths-list-many-files, append, Several files, Several files
15343 @unnumberedsubsec Determine the lengths of @code{defuns}
15346 The design using a @code{while} loop is routine. The argument passed
15347 the function is a list of files. As we saw earlier (@pxref{Loop
15348 Example}), you can write a @code{while} loop so that the body of the
15349 loop is evaluated if such a list contains elements, but to exit the
15350 loop if the list is empty. For this design to work, the body of the
15351 loop must contain an expression that shortens the list each time the
15352 body is evaluated, so that eventually the list is empty. The usual
15353 technique is to set the value of the list to the value of the @sc{cdr}
15354 of the list each time the body is evaluated.
15357 The template looks like this:
15361 (while @var{test-whether-list-is-empty}
15363 @var{set-list-to-cdr-of-list})
15367 Also, we remember that a @code{while} loop returns @code{nil} (the
15368 result of evaluating the true-or-false-test), not the result of any
15369 evaluation within its body. (The evaluations within the body of the
15370 loop are done for their side effects.) However, the expression that
15371 sets the lengths' list is part of the body---and that is the value
15372 that we want returned by the function as a whole. To do this, we
15373 enclose the @code{while} loop within a @code{let} expression, and
15374 arrange that the last element of the @code{let} expression contains
15375 the value of the lengths' list. (@xref{Incrementing Example, , Loop
15376 Example with an Incrementing Counter}.)
15378 @findex lengths-list-many-files
15380 These considerations lead us directly to the function itself:
15384 ;;; @r{Use @code{while} loop.}
15385 (defun lengths-list-many-files (list-of-files)
15386 "Return list of lengths of defuns in LIST-OF-FILES."
15389 (let (lengths-list)
15391 ;;; @r{true-or-false-test}
15392 (while list-of-files
15397 ;;; @r{Generate a lengths' list.}
15399 (expand-file-name (car list-of-files)))))
15403 ;;; @r{Make files' list shorter.}
15404 (setq list-of-files (cdr list-of-files)))
15406 ;;; @r{Return final value of lengths' list.}
15411 @code{expand-file-name} is a built-in function that converts a file
15412 name to the absolute, long, path name form. The function employs the
15413 name of the directory in which the function is called.
15415 @c !!! 22.1.1 lisp sources location here
15417 Thus, if @code{expand-file-name} is called on @code{debug.el} when
15418 Emacs is visiting the
15419 @file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory,
15429 @c !!! 22.1.1 lisp sources location here
15431 /usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el
15434 The only other new element of this function definition is the as yet
15435 unstudied function @code{append}, which merits a short section for
15438 @node append, , lengths-list-many-files, Several files
15439 @subsection The @code{append} Function
15442 The @code{append} function attaches one list to another. Thus,
15445 (append '(1 2 3 4) '(5 6 7 8))
15456 This is exactly how we want to attach two lengths' lists produced by
15457 @code{lengths-list-file} to each other. The results contrast with
15461 (cons '(1 2 3 4) '(5 6 7 8))
15466 which constructs a new list in which the first argument to @code{cons}
15467 becomes the first element of the new list:
15470 ((1 2 3 4) 5 6 7 8)
15473 @node Several files recursively, Prepare the data, Several files, Words in a defun
15474 @section Recursively Count Words in Different Files
15476 Besides a @code{while} loop, you can work on each of a list of files
15477 with recursion. A recursive version of @code{lengths-list-many-files}
15478 is short and simple.
15480 The recursive function has the usual parts: the `do-again-test', the
15481 `next-step-expression', and the recursive call. The `do-again-test'
15482 determines whether the function should call itself again, which it
15483 will do if the @code{list-of-files} contains any remaining elements;
15484 the `next-step-expression' resets the @code{list-of-files} to the
15485 @sc{cdr} of itself, so eventually the list will be empty; and the
15486 recursive call calls itself on the shorter list. The complete
15487 function is shorter than this description!
15488 @findex recursive-lengths-list-many-files
15492 (defun recursive-lengths-list-many-files (list-of-files)
15493 "Return list of lengths of each defun in LIST-OF-FILES."
15494 (if list-of-files ; @r{do-again-test}
15497 (expand-file-name (car list-of-files)))
15498 (recursive-lengths-list-many-files
15499 (cdr list-of-files)))))
15504 In a sentence, the function returns the lengths' list for the first of
15505 the @code{list-of-files} appended to the result of calling itself on
15506 the rest of the @code{list-of-files}.
15508 Here is a test of @code{recursive-lengths-list-many-files}, along with
15509 the results of running @code{lengths-list-file} on each of the files
15512 Install @code{recursive-lengths-list-many-files} and
15513 @code{lengths-list-file}, if necessary, and then evaluate the
15514 following expressions. You may need to change the files' pathnames;
15515 those here work when this Info file and the Emacs sources are located
15516 in their customary places. To change the expressions, copy them to
15517 the @file{*scratch*} buffer, edit them, and then evaluate them.
15519 The results are shown after the @samp{@result{}}. (These results are
15520 for files from Emacs Version 22.1.1; files from other versions of
15521 Emacs may produce different results.)
15523 @c !!! 22.1.1 lisp sources location here
15526 (cd "/usr/local/share/emacs/22.1.1/")
15528 (lengths-list-file "./lisp/macros.el")
15529 @result{} (283 263 480 90)
15533 (lengths-list-file "./lisp/mail/mailalias.el")
15534 @result{} (38 32 29 95 178 180 321 218 324)
15538 (lengths-list-file "./lisp/makesum.el")
15543 (recursive-lengths-list-many-files
15544 '("./lisp/macros.el"
15545 "./lisp/mail/mailalias.el"
15546 "./lisp/makesum.el"))
15547 @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181)
15551 The @code{recursive-lengths-list-many-files} function produces the
15554 The next step is to prepare the data in the list for display in a graph.
15556 @node Prepare the data, , Several files recursively, Words in a defun
15557 @section Prepare the Data for Display in a Graph
15559 The @code{recursive-lengths-list-many-files} function returns a list
15560 of numbers. Each number records the length of a function definition.
15561 What we need to do now is transform this data into a list of numbers
15562 suitable for generating a graph. The new list will tell how many
15563 functions definitions contain less than 10 words and
15564 symbols, how many contain between 10 and 19 words and symbols, how
15565 many contain between 20 and 29 words and symbols, and so on.
15567 In brief, we need to go through the lengths' list produced by the
15568 @code{recursive-lengths-list-many-files} function and count the number
15569 of defuns within each range of lengths, and produce a list of those
15572 Based on what we have done before, we can readily foresee that it
15573 should not be too hard to write a function that `@sc{cdr}s' down the
15574 lengths' list, looks at each element, determines which length range it
15575 is in, and increments a counter for that range.
15577 However, before beginning to write such a function, we should consider
15578 the advantages of sorting the lengths' list first, so the numbers are
15579 ordered from smallest to largest. First, sorting will make it easier
15580 to count the numbers in each range, since two adjacent numbers will
15581 either be in the same length range or in adjacent ranges. Second, by
15582 inspecting a sorted list, we can discover the highest and lowest
15583 number, and thereby determine the largest and smallest length range
15589 * Counting function definitions::
15592 @node Sorting, Files List, Prepare the data, Prepare the data
15593 @subsection Sorting Lists
15596 Emacs contains a function to sort lists, called (as you might guess)
15597 @code{sort}. The @code{sort} function takes two arguments, the list
15598 to be sorted, and a predicate that determines whether the first of
15599 two list elements is ``less'' than the second.
15601 As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong
15602 Type Object as an Argument}), a predicate is a function that
15603 determines whether some property is true or false. The @code{sort}
15604 function will reorder a list according to whatever property the
15605 predicate uses; this means that @code{sort} can be used to sort
15606 non-numeric lists by non-numeric criteria---it can, for example,
15607 alphabetize a list.
15610 The @code{<} function is used when sorting a numeric list. For example,
15613 (sort '(4 8 21 17 33 7 21 7) '<)
15621 (4 7 7 8 17 21 21 33)
15625 (Note that in this example, both the arguments are quoted so that the
15626 symbols are not evaluated before being passed to @code{sort} as
15629 Sorting the list returned by the
15630 @code{recursive-lengths-list-many-files} function is straightforward;
15631 it uses the @code{<} function:
15635 In GNU Emacs 22, eval
15637 (cd "/usr/local/share/emacs/22.0.50/")
15639 (recursive-lengths-list-many-files
15640 '("./lisp/macros.el"
15641 "./lisp/mail/mailalias.el"
15642 "./lisp/makesum.el"))
15650 (recursive-lengths-list-many-files
15651 '("./lisp/macros.el"
15652 "./lisp/mailalias.el"
15653 "./lisp/makesum.el"))
15663 (29 32 38 85 90 95 178 180 181 218 263 283 321 324 480)
15667 (Note that in this example, the first argument to @code{sort} is not
15668 quoted, since the expression must be evaluated so as to produce the
15669 list that is passed to @code{sort}.)
15671 @node Files List, Counting function definitions, Sorting, Prepare the data
15672 @subsection Making a List of Files
15674 The @code{recursive-lengths-list-many-files} function requires a list
15675 of files as its argument. For our test examples, we constructed such
15676 a list by hand; but the Emacs Lisp source directory is too large for
15677 us to do for that. Instead, we will write a function to do the job
15678 for us. In this function, we will use both a @code{while} loop and a
15681 @findex directory-files
15682 We did not have to write a function like this for older versions of
15683 GNU Emacs, since they placed all the @samp{.el} files in one
15684 directory. Instead, we were able to use the @code{directory-files}
15685 function, which lists the names of files that match a specified
15686 pattern within a single directory.
15688 However, recent versions of Emacs place Emacs Lisp files in
15689 sub-directories of the top level @file{lisp} directory. This
15690 re-arrangement eases navigation. For example, all the mail related
15691 files are in a @file{lisp} sub-directory called @file{mail}. But at
15692 the same time, this arrangement forces us to create a file listing
15693 function that descends into the sub-directories.
15695 @findex files-in-below-directory
15696 We can create this function, called @code{files-in-below-directory},
15697 using familiar functions such as @code{car}, @code{nthcdr}, and
15698 @code{substring} in conjunction with an existing function called
15699 @code{directory-files-and-attributes}. This latter function not only
15700 lists all the filenames in a directory, including the names
15701 of sub-directories, but also their attributes.
15703 To restate our goal: to create a function that will enable us
15704 to feed filenames to @code{recursive-lengths-list-many-files}
15705 as a list that looks like this (but with more elements):
15709 ("./lisp/macros.el"
15710 "./lisp/mail/rmail.el"
15711 "./lisp/makesum.el")
15715 The @code{directory-files-and-attributes} function returns a list of
15716 lists. Each of the lists within the main list consists of 13
15717 elements. The first element is a string that contains the name of the
15718 file -- which, in GNU/Linux, may be a `directory file', that is to
15719 say, a file with the special attributes of a directory. The second
15720 element of the list is @code{t} for a directory, a string
15721 for symbolic link (the string is the name linked to), or @code{nil}.
15723 For example, the first @samp{.el} file in the @file{lisp/} directory
15724 is @file{abbrev.el}. Its name is
15725 @file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a
15726 directory or a symbolic link.
15729 This is how @code{directory-files-and-attributes} lists that file and
15755 On the other hand, @file{mail/} is a directory within the @file{lisp/}
15756 directory. The beginning of its listing looks like this:
15767 (To learn about the different attributes, look at the documentation of
15768 @code{file-attributes}. Bear in mind that the @code{file-attributes}
15769 function does not list the filename, so its first element is
15770 @code{directory-files-and-attributes}'s second element.)
15772 We will want our new function, @code{files-in-below-directory}, to
15773 list the @samp{.el} files in the directory it is told to check, and in
15774 any directories below that directory.
15776 This gives us a hint on how to construct
15777 @code{files-in-below-directory}: within a directory, the function
15778 should add @samp{.el} filenames to a list; and if, within a directory,
15779 the function comes upon a sub-directory, it should go into that
15780 sub-directory and repeat its actions.
15782 However, we should note that every directory contains a name that
15783 refers to itself, called @file{.}, (``dot'') and a name that refers to
15784 its parent directory, called @file{..} (``double dot''). (In
15785 @file{/}, the root directory, @file{..} refers to itself, since
15786 @file{/} has no parent.) Clearly, we do not want our
15787 @code{files-in-below-directory} function to enter those directories,
15788 since they always lead us, directly or indirectly, to the current
15791 Consequently, our @code{files-in-below-directory} function must do
15796 Check to see whether it is looking at a filename that ends in
15797 @samp{.el}; and if so, add its name to a list.
15800 Check to see whether it is looking at a filename that is the name of a
15801 directory; and if so,
15805 Check to see whether it is looking at @file{.} or @file{..}; and if
15809 Or else, go into that directory and repeat the process.
15813 Let's write a function definition to do these tasks. We will use a
15814 @code{while} loop to move from one filename to another within a
15815 directory, checking what needs to be done; and we will use a recursive
15816 call to repeat the actions on each sub-directory. The recursive
15817 pattern is `accumulate'
15818 (@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}),
15819 using @code{append} as the combiner.
15822 (directory-files "/usr/local/src/emacs/lisp/" t "\\.el$")
15823 (shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'")
15825 (directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$")
15826 (shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'")
15829 @c /usr/local/share/emacs/22.1.1/lisp/
15832 Here is the function:
15836 (defun files-in-below-directory (directory)
15837 "List the .el files in DIRECTORY and in its sub-directories."
15838 ;; Although the function will be used non-interactively,
15839 ;; it will be easier to test if we make it interactive.
15840 ;; The directory will have a name such as
15841 ;; "/usr/local/share/emacs/22.1.1/lisp/"
15842 (interactive "DDirectory name: ")
15845 (let (el-files-list
15846 (current-directory-list
15847 (directory-files-and-attributes directory t)))
15848 ;; while we are in the current directory
15849 (while current-directory-list
15853 ;; check to see whether filename ends in `.el'
15854 ;; and if so, append its name to a list.
15855 ((equal ".el" (substring (car (car current-directory-list)) -3))
15856 (setq el-files-list
15857 (cons (car (car current-directory-list)) el-files-list)))
15860 ;; check whether filename is that of a directory
15861 ((eq t (car (cdr (car current-directory-list))))
15862 ;; decide whether to skip or recurse
15865 (substring (car (car current-directory-list)) -1))
15866 ;; then do nothing since filename is that of
15867 ;; current directory or parent, "." or ".."
15871 ;; else descend into the directory and repeat the process
15872 (setq el-files-list
15874 (files-in-below-directory
15875 (car (car current-directory-list)))
15877 ;; move to the next filename in the list; this also
15878 ;; shortens the list so the while loop eventually comes to an end
15879 (setq current-directory-list (cdr current-directory-list)))
15880 ;; return the filenames
15885 @c (files-in-below-directory "/usr/local/src/emacs/lisp/")
15886 @c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
15888 The @code{files-in-below-directory} @code{directory-files} function
15889 takes one argument, the name of a directory.
15892 Thus, on my system,
15894 @c (length (files-in-below-directory "/usr/local/src/emacs/lisp/"))
15896 @c !!! 22.1.1 lisp sources location here
15900 (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/"))
15905 tells me that in and below my Lisp sources directory are 1031
15908 @code{files-in-below-directory} returns a list in reverse alphabetical
15909 order. An expression to sort the list in alphabetical order looks
15915 (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
15922 "Test how long it takes to find lengths of all sorted elisp defuns."
15923 (insert "\n" (current-time-string) "\n")
15926 (recursive-lengths-list-many-files
15927 (files-in-below-directory "/usr/local/src/emacs/lisp/"))
15929 (insert (format "%s" (current-time-string))))
15932 @node Counting function definitions, , Files List, Prepare the data
15933 @subsection Counting function definitions
15935 Our immediate goal is to generate a list that tells us how many
15936 function definitions contain fewer than 10 words and symbols, how many
15937 contain between 10 and 19 words and symbols, how many contain between
15938 20 and 29 words and symbols, and so on.
15940 With a sorted list of numbers, this is easy: count how many elements
15941 of the list are smaller than 10, then, after moving past the numbers
15942 just counted, count how many are smaller than 20, then, after moving
15943 past the numbers just counted, count how many are smaller than 30, and
15944 so on. Each of the numbers, 10, 20, 30, 40, and the like, is one
15945 larger than the top of that range. We can call the list of such
15946 numbers the @code{top-of-ranges} list.
15949 If we wished, we could generate this list automatically, but it is
15950 simpler to write a list manually. Here it is:
15951 @vindex top-of-ranges
15955 (defvar top-of-ranges
15958 110 120 130 140 150
15959 160 170 180 190 200
15960 210 220 230 240 250
15961 260 270 280 290 300)
15962 "List specifying ranges for `defuns-per-range'.")
15966 To change the ranges, we edit this list.
15968 Next, we need to write the function that creates the list of the
15969 number of definitions within each range. Clearly, this function must
15970 take the @code{sorted-lengths} and the @code{top-of-ranges} lists
15973 The @code{defuns-per-range} function must do two things again and
15974 again: it must count the number of definitions within a range
15975 specified by the current top-of-range value; and it must shift to the
15976 next higher value in the @code{top-of-ranges} list after counting the
15977 number of definitions in the current range. Since each of these
15978 actions is repetitive, we can use @code{while} loops for the job.
15979 One loop counts the number of definitions in the range defined by the
15980 current top-of-range value, and the other loop selects each of the
15981 top-of-range values in turn.
15983 Several entries of the @code{sorted-lengths} list are counted for each
15984 range; this means that the loop for the @code{sorted-lengths} list
15985 will be inside the loop for the @code{top-of-ranges} list, like a
15986 small gear inside a big gear.
15988 The inner loop counts the number of definitions within the range. It
15989 is a simple counting loop of the type we have seen before.
15990 (@xref{Incrementing Loop, , A loop with an incrementing counter}.)
15991 The true-or-false test of the loop tests whether the value from the
15992 @code{sorted-lengths} list is smaller than the current value of the
15993 top of the range. If it is, the function increments the counter and
15994 tests the next value from the @code{sorted-lengths} list.
15997 The inner loop looks like this:
16001 (while @var{length-element-smaller-than-top-of-range}
16002 (setq number-within-range (1+ number-within-range))
16003 (setq sorted-lengths (cdr sorted-lengths)))
16007 The outer loop must start with the lowest value of the
16008 @code{top-of-ranges} list, and then be set to each of the succeeding
16009 higher values in turn. This can be done with a loop like this:
16013 (while top-of-ranges
16014 @var{body-of-loop}@dots{}
16015 (setq top-of-ranges (cdr top-of-ranges)))
16020 Put together, the two loops look like this:
16024 (while top-of-ranges
16026 ;; @r{Count the number of elements within the current range.}
16027 (while @var{length-element-smaller-than-top-of-range}
16028 (setq number-within-range (1+ number-within-range))
16029 (setq sorted-lengths (cdr sorted-lengths)))
16031 ;; @r{Move to next range.}
16032 (setq top-of-ranges (cdr top-of-ranges)))
16036 In addition, in each circuit of the outer loop, Emacs should record
16037 the number of definitions within that range (the value of
16038 @code{number-within-range}) in a list. We can use @code{cons} for
16039 this purpose. (@xref{cons, , @code{cons}}.)
16041 The @code{cons} function works fine, except that the list it
16042 constructs will contain the number of definitions for the highest
16043 range at its beginning and the number of definitions for the lowest
16044 range at its end. This is because @code{cons} attaches new elements
16045 of the list to the beginning of the list, and since the two loops are
16046 working their way through the lengths' list from the lower end first,
16047 the @code{defuns-per-range-list} will end up largest number first.
16048 But we will want to print our graph with smallest values first and the
16049 larger later. The solution is to reverse the order of the
16050 @code{defuns-per-range-list}. We can do this using the
16051 @code{nreverse} function, which reverses the order of a list.
16058 (nreverse '(1 2 3 4))
16069 Note that the @code{nreverse} function is ``destructive''---that is,
16070 it changes the list to which it is applied; this contrasts with the
16071 @code{car} and @code{cdr} functions, which are non-destructive. In
16072 this case, we do not want the original @code{defuns-per-range-list},
16073 so it does not matter that it is destroyed. (The @code{reverse}
16074 function provides a reversed copy of a list, leaving the original list
16079 Put all together, the @code{defuns-per-range} looks like this:
16083 (defun defuns-per-range (sorted-lengths top-of-ranges)
16084 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
16085 (let ((top-of-range (car top-of-ranges))
16086 (number-within-range 0)
16087 defuns-per-range-list)
16092 (while top-of-ranges
16098 ;; @r{Need number for numeric test.}
16099 (car sorted-lengths)
16100 (< (car sorted-lengths) top-of-range))
16104 ;; @r{Count number of definitions within current range.}
16105 (setq number-within-range (1+ number-within-range))
16106 (setq sorted-lengths (cdr sorted-lengths)))
16108 ;; @r{Exit inner loop but remain within outer loop.}
16112 (setq defuns-per-range-list
16113 (cons number-within-range defuns-per-range-list))
16114 (setq number-within-range 0) ; @r{Reset count to zero.}
16118 ;; @r{Move to next range.}
16119 (setq top-of-ranges (cdr top-of-ranges))
16120 ;; @r{Specify next top of range value.}
16121 (setq top-of-range (car top-of-ranges)))
16125 ;; @r{Exit outer loop and count the number of defuns larger than}
16126 ;; @r{ the largest top-of-range value.}
16127 (setq defuns-per-range-list
16129 (length sorted-lengths)
16130 defuns-per-range-list))
16134 ;; @r{Return a list of the number of definitions within each range,}
16135 ;; @r{ smallest to largest.}
16136 (nreverse defuns-per-range-list)))
16142 The function is straightforward except for one subtle feature. The
16143 true-or-false test of the inner loop looks like this:
16147 (and (car sorted-lengths)
16148 (< (car sorted-lengths) top-of-range))
16154 instead of like this:
16157 (< (car sorted-lengths) top-of-range)
16160 The purpose of the test is to determine whether the first item in the
16161 @code{sorted-lengths} list is less than the value of the top of the
16164 The simple version of the test works fine unless the
16165 @code{sorted-lengths} list has a @code{nil} value. In that case, the
16166 @code{(car sorted-lengths)} expression function returns
16167 @code{nil}. The @code{<} function cannot compare a number to
16168 @code{nil}, which is an empty list, so Emacs signals an error and
16169 stops the function from attempting to continue to execute.
16171 The @code{sorted-lengths} list always becomes @code{nil} when the
16172 counter reaches the end of the list. This means that any attempt to
16173 use the @code{defuns-per-range} function with the simple version of
16174 the test will fail.
16176 We solve the problem by using the @code{(car sorted-lengths)}
16177 expression in conjunction with the @code{and} expression. The
16178 @code{(car sorted-lengths)} expression returns a non-@code{nil}
16179 value so long as the list has at least one number within it, but
16180 returns @code{nil} if the list is empty. The @code{and} expression
16181 first evaluates the @code{(car sorted-lengths)} expression, and
16182 if it is @code{nil}, returns false @emph{without} evaluating the
16183 @code{<} expression. But if the @code{(car sorted-lengths)}
16184 expression returns a non-@code{nil} value, the @code{and} expression
16185 evaluates the @code{<} expression, and returns that value as the value
16186 of the @code{and} expression.
16188 @c colon in printed section title causes problem in Info cross reference
16189 This way, we avoid an error.
16192 (For information about @code{and}, see
16193 @ref{kill-new function, , The @code{kill-new} function}.)
16197 (@xref{kill-new function, , The @code{kill-new} function}, for
16198 information about @code{and}.)
16201 Here is a short test of the @code{defuns-per-range} function. First,
16202 evaluate the expression that binds (a shortened)
16203 @code{top-of-ranges} list to the list of values, then evaluate the
16204 expression for binding the @code{sorted-lengths} list, and then
16205 evaluate the @code{defuns-per-range} function.
16209 ;; @r{(Shorter list than we will use later.)}
16210 (setq top-of-ranges
16211 '(110 120 130 140 150
16212 160 170 180 190 200))
16214 (setq sorted-lengths
16215 '(85 86 110 116 122 129 154 176 179 200 265 300 300))
16217 (defuns-per-range sorted-lengths top-of-ranges)
16223 The list returned looks like this:
16226 (2 2 2 0 0 1 0 2 0 0 4)
16230 Indeed, there are two elements of the @code{sorted-lengths} list
16231 smaller than 110, two elements between 110 and 119, two elements
16232 between 120 and 129, and so on. There are four elements with a value
16235 @c The next step is to turn this numbers' list into a graph.
16236 @node Readying a Graph, Emacs Initialization, Words in a defun, Top
16237 @chapter Readying a Graph
16238 @cindex Readying a graph
16239 @cindex Graph prototype
16240 @cindex Prototype graph
16241 @cindex Body of graph
16243 Our goal is to construct a graph showing the numbers of function
16244 definitions of various lengths in the Emacs lisp sources.
16246 As a practical matter, if you were creating a graph, you would
16247 probably use a program such as @code{gnuplot} to do the job.
16248 (@code{gnuplot} is nicely integrated into GNU Emacs.) In this case,
16249 however, we create one from scratch, and in the process we will
16250 re-acquaint ourselves with some of what we learned before and learn
16253 In this chapter, we will first write a simple graph printing function.
16254 This first definition will be a @dfn{prototype}, a rapidly written
16255 function that enables us to reconnoiter this unknown graph-making
16256 territory. We will discover dragons, or find that they are myth.
16257 After scouting the terrain, we will feel more confident and enhance
16258 the function to label the axes automatically.
16261 * Columns of a graph::
16262 * graph-body-print::
16263 * recursive-graph-body-print::
16265 * Line Graph Exercise::
16268 @node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph
16270 @unnumberedsec Printing the Columns of a Graph
16273 Since Emacs is designed to be flexible and work with all kinds of
16274 terminals, including character-only terminals, the graph will need to
16275 be made from one of the `typewriter' symbols. An asterisk will do; as
16276 we enhance the graph-printing function, we can make the choice of
16277 symbol a user option.
16279 We can call this function @code{graph-body-print}; it will take a
16280 @code{numbers-list} as its only argument. At this stage, we will not
16281 label the graph, but only print its body.
16283 The @code{graph-body-print} function inserts a vertical column of
16284 asterisks for each element in the @code{numbers-list}. The height of
16285 each line is determined by the value of that element of the
16286 @code{numbers-list}.
16288 Inserting columns is a repetitive act; that means that this function can
16289 be written either with a @code{while} loop or recursively.
16291 Our first challenge is to discover how to print a column of asterisks.
16292 Usually, in Emacs, we print characters onto a screen horizontally,
16293 line by line, by typing. We have two routes we can follow: write our
16294 own column-insertion function or discover whether one exists in Emacs.
16296 To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
16297 command. This command is like the @kbd{C-h a} (@code{command-apropos})
16298 command, except that the latter finds only those functions that are
16299 commands. The @kbd{M-x apropos} command lists all symbols that match
16300 a regular expression, including functions that are not interactive.
16303 What we want to look for is some command that prints or inserts
16304 columns. Very likely, the name of the function will contain either
16305 the word `print' or the word `insert' or the word `column'.
16306 Therefore, we can simply type @kbd{M-x apropos RET
16307 print\|insert\|column RET} and look at the result. On my system, this
16308 command once too takes quite some time, and then produced a list of 79
16309 functions and variables. Now it does not take much time at all and
16310 produces a list of 211 functions and variables. Scanning down the
16311 list, the only function that looks as if it might do the job is
16312 @code{insert-rectangle}.
16315 Indeed, this is the function we want; its documentation says:
16320 Insert text of RECTANGLE with upper left corner at point.
16321 RECTANGLE's first line is inserted at point,
16322 its second line is inserted at a point vertically under point, etc.
16323 RECTANGLE should be a list of strings.
16324 After this command, the mark is at the upper left corner
16325 and point is at the lower right corner.
16329 We can run a quick test, to make sure it does what we expect of it.
16331 Here is the result of placing the cursor after the
16332 @code{insert-rectangle} expression and typing @kbd{C-u C-x C-e}
16333 (@code{eval-last-sexp}). The function inserts the strings
16334 @samp{"first"}, @samp{"second"}, and @samp{"third"} at and below
16335 point. Also the function returns @code{nil}.
16339 (insert-rectangle '("first" "second" "third"))first
16346 Of course, we won't be inserting the text of the
16347 @code{insert-rectangle} expression itself into the buffer in which we
16348 are making the graph, but will call the function from our program. We
16349 shall, however, have to make sure that point is in the buffer at the
16350 place where the @code{insert-rectangle} function will insert its
16353 If you are reading this in Info, you can see how this works by
16354 switching to another buffer, such as the @file{*scratch*} buffer,
16355 placing point somewhere in the buffer, typing @kbd{M-:}, typing the
16356 @code{insert-rectangle} expression into the minibuffer at the prompt,
16357 and then typing @key{RET}. This causes Emacs to evaluate the
16358 expression in the minibuffer, but to use as the value of point the
16359 position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the
16360 keybinding for @code{eval-expression}. Also, @code{nil} does not
16361 appear in the @file{*scratch*} buffer since the expression is
16362 evaluated in the minibuffer.)
16364 We find when we do this that point ends up at the end of the last
16365 inserted line---that is to say, this function moves point as a
16366 side-effect. If we were to repeat the command, with point at this
16367 position, the next insertion would be below and to the right of the
16368 previous insertion. We don't want this! If we are going to make a
16369 bar graph, the columns need to be beside each other.
16371 So we discover that each cycle of the column-inserting @code{while}
16372 loop must reposition point to the place we want it, and that place
16373 will be at the top, not the bottom, of the column. Moreover, we
16374 remember that when we print a graph, we do not expect all the columns
16375 to be the same height. This means that the top of each column may be
16376 at a different height from the previous one. We cannot simply
16377 reposition point to the same line each time, but moved over to the
16378 right---or perhaps we can@dots{}
16380 We are planning to make the columns of the bar graph out of asterisks.
16381 The number of asterisks in the column is the number specified by the
16382 current element of the @code{numbers-list}. We need to construct a
16383 list of asterisks of the right length for each call to
16384 @code{insert-rectangle}. If this list consists solely of the requisite
16385 number of asterisks, then we will have position point the right number
16386 of lines above the base for the graph to print correctly. This could
16389 Alternatively, if we can figure out some way to pass
16390 @code{insert-rectangle} a list of the same length each time, then we
16391 can place point on the same line each time, but move it over one
16392 column to the right for each new column. If we do this, however, some
16393 of the entries in the list passed to @code{insert-rectangle} must be
16394 blanks rather than asterisks. For example, if the maximum height of
16395 the graph is 5, but the height of the column is 3, then
16396 @code{insert-rectangle} requires an argument that looks like this:
16399 (" " " " "*" "*" "*")
16402 This last proposal is not so difficult, so long as we can determine
16403 the column height. There are two ways for us to specify the column
16404 height: we can arbitrarily state what it will be, which would work
16405 fine for graphs of that height; or we can search through the list of
16406 numbers and use the maximum height of the list as the maximum height
16407 of the graph. If the latter operation were difficult, then the former
16408 procedure would be easiest, but there is a function built into Emacs
16409 that determines the maximum of its arguments. We can use that
16410 function. The function is called @code{max} and it returns the
16411 largest of all its arguments, which must be numbers. Thus, for
16419 returns 7. (A corresponding function called @code{min} returns the
16420 smallest of all its arguments.)
16424 However, we cannot simply call @code{max} on the @code{numbers-list};
16425 the @code{max} function expects numbers as its argument, not a list of
16426 numbers. Thus, the following expression,
16429 (max '(3 4 6 5 7 3))
16434 produces the following error message;
16437 Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3)
16441 We need a function that passes a list of arguments to a function.
16442 This function is @code{apply}. This function `applies' its first
16443 argument (a function) to its remaining arguments, the last of which
16450 (apply 'max 3 4 7 3 '(4 8 5))
16456 (Incidentally, I don't know how you would learn of this function
16457 without a book such as this. It is possible to discover other
16458 functions, like @code{search-forward} or @code{insert-rectangle}, by
16459 guessing at a part of their names and then using @code{apropos}. Even
16460 though its base in metaphor is clear---`apply' its first argument to
16461 the rest---I doubt a novice would come up with that particular word
16462 when using @code{apropos} or other aid. Of course, I could be wrong;
16463 after all, the function was first named by someone who had to invent
16466 The second and subsequent arguments to @code{apply} are optional, so
16467 we can use @code{apply} to call a function and pass the elements of a
16468 list to it, like this, which also returns 8:
16471 (apply 'max '(4 8 5))
16474 This latter way is how we will use @code{apply}. The
16475 @code{recursive-lengths-list-many-files} function returns a numbers'
16476 list to which we can apply @code{max} (we could also apply @code{max} to
16477 the sorted numbers' list; it does not matter whether the list is
16481 Hence, the operation for finding the maximum height of the graph is this:
16484 (setq max-graph-height (apply 'max numbers-list))
16487 Now we can return to the question of how to create a list of strings
16488 for a column of the graph. Told the maximum height of the graph
16489 and the number of asterisks that should appear in the column, the
16490 function should return a list of strings for the
16491 @code{insert-rectangle} command to insert.
16493 Each column is made up of asterisks or blanks. Since the function is
16494 passed the value of the height of the column and the number of
16495 asterisks in the column, the number of blanks can be found by
16496 subtracting the number of asterisks from the height of the column.
16497 Given the number of blanks and the number of asterisks, two
16498 @code{while} loops can be used to construct the list:
16502 ;;; @r{First version.}
16503 (defun column-of-graph (max-graph-height actual-height)
16504 "Return list of strings that is one column of a graph."
16505 (let ((insert-list nil)
16506 (number-of-top-blanks
16507 (- max-graph-height actual-height)))
16511 ;; @r{Fill in asterisks.}
16512 (while (> actual-height 0)
16513 (setq insert-list (cons "*" insert-list))
16514 (setq actual-height (1- actual-height)))
16518 ;; @r{Fill in blanks.}
16519 (while (> number-of-top-blanks 0)
16520 (setq insert-list (cons " " insert-list))
16521 (setq number-of-top-blanks
16522 (1- number-of-top-blanks)))
16526 ;; @r{Return whole list.}
16531 If you install this function and then evaluate the following
16532 expression you will see that it returns the list as desired:
16535 (column-of-graph 5 3)
16543 (" " " " "*" "*" "*")
16546 As written, @code{column-of-graph} contains a major flaw: the symbols
16547 used for the blank and for the marked entries in the column are
16548 `hard-coded' as a space and asterisk. This is fine for a prototype,
16549 but you, or another user, may wish to use other symbols. For example,
16550 in testing the graph function, you many want to use a period in place
16551 of the space, to make sure the point is being repositioned properly
16552 each time the @code{insert-rectangle} function is called; or you might
16553 want to substitute a @samp{+} sign or other symbol for the asterisk.
16554 You might even want to make a graph-column that is more than one
16555 display column wide. The program should be more flexible. The way to
16556 do that is to replace the blank and the asterisk with two variables
16557 that we can call @code{graph-blank} and @code{graph-symbol} and define
16558 those variables separately.
16560 Also, the documentation is not well written. These considerations
16561 lead us to the second version of the function:
16565 (defvar graph-symbol "*"
16566 "String used as symbol in graph, usually an asterisk.")
16570 (defvar graph-blank " "
16571 "String used as blank in graph, usually a blank space.
16572 graph-blank must be the same number of columns wide
16578 (For an explanation of @code{defvar}, see
16579 @ref{defvar, , Initializing a Variable with @code{defvar}}.)
16583 ;;; @r{Second version.}
16584 (defun column-of-graph (max-graph-height actual-height)
16585 "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols.
16589 The graph-symbols are contiguous entries at the end
16591 The list will be inserted as one column of a graph.
16592 The strings are either graph-blank or graph-symbol."
16596 (let ((insert-list nil)
16597 (number-of-top-blanks
16598 (- max-graph-height actual-height)))
16602 ;; @r{Fill in @code{graph-symbols}.}
16603 (while (> actual-height 0)
16604 (setq insert-list (cons graph-symbol insert-list))
16605 (setq actual-height (1- actual-height)))
16609 ;; @r{Fill in @code{graph-blanks}.}
16610 (while (> number-of-top-blanks 0)
16611 (setq insert-list (cons graph-blank insert-list))
16612 (setq number-of-top-blanks
16613 (1- number-of-top-blanks)))
16615 ;; @r{Return whole list.}
16620 If we wished, we could rewrite @code{column-of-graph} a third time to
16621 provide optionally for a line graph as well as for a bar graph. This
16622 would not be hard to do. One way to think of a line graph is that it
16623 is no more than a bar graph in which the part of each bar that is
16624 below the top is blank. To construct a column for a line graph, the
16625 function first constructs a list of blanks that is one shorter than
16626 the value, then it uses @code{cons} to attach a graph symbol to the
16627 list; then it uses @code{cons} again to attach the `top blanks' to
16630 It is easy to see how to write such a function, but since we don't
16631 need it, we will not do it. But the job could be done, and if it were
16632 done, it would be done with @code{column-of-graph}. Even more
16633 important, it is worth noting that few changes would have to be made
16634 anywhere else. The enhancement, if we ever wish to make it, is
16637 Now, finally, we come to our first actual graph printing function.
16638 This prints the body of a graph, not the labels for the vertical and
16639 horizontal axes, so we can call this @code{graph-body-print}.
16641 @node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph
16642 @section The @code{graph-body-print} Function
16643 @findex graph-body-print
16645 After our preparation in the preceding section, the
16646 @code{graph-body-print} function is straightforward. The function
16647 will print column after column of asterisks and blanks, using the
16648 elements of a numbers' list to specify the number of asterisks in each
16649 column. This is a repetitive act, which means we can use a
16650 decrementing @code{while} loop or recursive function for the job. In
16651 this section, we will write the definition using a @code{while} loop.
16653 The @code{column-of-graph} function requires the height of the graph
16654 as an argument, so we should determine and record that as a local variable.
16656 This leads us to the following template for the @code{while} loop
16657 version of this function:
16661 (defun graph-body-print (numbers-list)
16662 "@var{documentation}@dots{}"
16663 (let ((height @dots{}
16668 (while numbers-list
16669 @var{insert-columns-and-reposition-point}
16670 (setq numbers-list (cdr numbers-list)))))
16675 We need to fill in the slots of the template.
16677 Clearly, we can use the @code{(apply 'max numbers-list)} expression to
16678 determine the height of the graph.
16680 The @code{while} loop will cycle through the @code{numbers-list} one
16681 element at a time. As it is shortened by the @code{(setq numbers-list
16682 (cdr numbers-list))} expression, the @sc{car} of each instance of the
16683 list is the value of the argument for @code{column-of-graph}.
16685 At each cycle of the @code{while} loop, the @code{insert-rectangle}
16686 function inserts the list returned by @code{column-of-graph}. Since
16687 the @code{insert-rectangle} function moves point to the lower right of
16688 the inserted rectangle, we need to save the location of point at the
16689 time the rectangle is inserted, move back to that position after the
16690 rectangle is inserted, and then move horizontally to the next place
16691 from which @code{insert-rectangle} is called.
16693 If the inserted columns are one character wide, as they will be if
16694 single blanks and asterisks are used, the repositioning command is
16695 simply @code{(forward-char 1)}; however, the width of a column may be
16696 greater than one. This means that the repositioning command should be
16697 written @code{(forward-char symbol-width)}. The @code{symbol-width}
16698 itself is the length of a @code{graph-blank} and can be found using
16699 the expression @code{(length graph-blank)}. The best place to bind
16700 the @code{symbol-width} variable to the value of the width of graph
16701 column is in the varlist of the @code{let} expression.
16704 These considerations lead to the following function definition:
16708 (defun graph-body-print (numbers-list)
16709 "Print a bar graph of the NUMBERS-LIST.
16710 The numbers-list consists of the Y-axis values."
16712 (let ((height (apply 'max numbers-list))
16713 (symbol-width (length graph-blank))
16718 (while numbers-list
16719 (setq from-position (point))
16721 (column-of-graph height (car numbers-list)))
16722 (goto-char from-position)
16723 (forward-char symbol-width)
16726 ;; @r{Draw graph column by column.}
16728 (setq numbers-list (cdr numbers-list)))
16731 ;; @r{Place point for X axis labels.}
16732 (forward-line height)
16739 The one unexpected expression in this function is the
16740 @w{@code{(sit-for 0)}} expression in the @code{while} loop. This
16741 expression makes the graph printing operation more interesting to
16742 watch than it would be otherwise. The expression causes Emacs to
16743 `sit' or do nothing for a zero length of time and then redraw the
16744 screen. Placed here, it causes Emacs to redraw the screen column by
16745 column. Without it, Emacs would not redraw the screen until the
16748 We can test @code{graph-body-print} with a short list of numbers.
16752 Install @code{graph-symbol}, @code{graph-blank},
16753 @code{column-of-graph}, which are in
16755 @ref{Readying a Graph, , Readying a Graph},
16758 @ref{Columns of a graph},
16760 and @code{graph-body-print}.
16764 Copy the following expression:
16767 (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3))
16771 Switch to the @file{*scratch*} buffer and place the cursor where you
16772 want the graph to start.
16775 Type @kbd{M-:} (@code{eval-expression}).
16778 Yank the @code{graph-body-print} expression into the minibuffer
16779 with @kbd{C-y} (@code{yank)}.
16782 Press @key{RET} to evaluate the @code{graph-body-print} expression.
16786 Emacs will print a graph like this:
16800 @node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph
16801 @section The @code{recursive-graph-body-print} Function
16802 @findex recursive-graph-body-print
16804 The @code{graph-body-print} function may also be written recursively.
16805 The recursive solution is divided into two parts: an outside `wrapper'
16806 that uses a @code{let} expression to determine the values of several
16807 variables that need only be found once, such as the maximum height of
16808 the graph, and an inside function that is called recursively to print
16812 The `wrapper' is uncomplicated:
16816 (defun recursive-graph-body-print (numbers-list)
16817 "Print a bar graph of the NUMBERS-LIST.
16818 The numbers-list consists of the Y-axis values."
16819 (let ((height (apply 'max numbers-list))
16820 (symbol-width (length graph-blank))
16822 (recursive-graph-body-print-internal
16829 The recursive function is a little more difficult. It has four parts:
16830 the `do-again-test', the printing code, the recursive call, and the
16831 `next-step-expression'. The `do-again-test' is a @code{when}
16832 expression that determines whether the @code{numbers-list} contains
16833 any remaining elements; if it does, the function prints one column of
16834 the graph using the printing code and calls itself again. The
16835 function calls itself again according to the value produced by the
16836 `next-step-expression' which causes the call to act on a shorter
16837 version of the @code{numbers-list}.
16841 (defun recursive-graph-body-print-internal
16842 (numbers-list height symbol-width)
16843 "Print a bar graph.
16844 Used within recursive-graph-body-print function."
16849 (setq from-position (point))
16851 (column-of-graph height (car numbers-list)))
16854 (goto-char from-position)
16855 (forward-char symbol-width)
16856 (sit-for 0) ; @r{Draw graph column by column.}
16857 (recursive-graph-body-print-internal
16858 (cdr numbers-list) height symbol-width)))
16863 After installation, this expression can be tested; here is a sample:
16866 (recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1))
16870 Here is what @code{recursive-graph-body-print} produces:
16884 Either of these two functions, @code{graph-body-print} or
16885 @code{recursive-graph-body-print}, create the body of a graph.
16887 @node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph
16888 @section Need for Printed Axes
16890 A graph needs printed axes, so you can orient yourself. For a do-once
16891 project, it may be reasonable to draw the axes by hand using Emacs'
16892 Picture mode; but a graph drawing function may be used more than once.
16894 For this reason, I have written enhancements to the basic
16895 @code{print-graph-body} function that automatically print labels for
16896 the horizontal and vertical axes. Since the label printing functions
16897 do not contain much new material, I have placed their description in
16898 an appendix. @xref{Full Graph, , A Graph with Labelled Axes}.
16900 @node Line Graph Exercise, , Printed Axes, Readying a Graph
16903 Write a line graph version of the graph printing functions.
16905 @node Emacs Initialization, Debugging, Readying a Graph, Top
16906 @chapter Your @file{.emacs} File
16907 @cindex @file{.emacs} file
16908 @cindex Customizing your @file{.emacs} file
16909 @cindex Initialization file
16911 ``You don't have to like Emacs to like it'' -- this seemingly
16912 paradoxical statement is the secret of GNU Emacs. The plain, `out of
16913 the box' Emacs is a generic tool. Most people who use it, customize
16914 it to suit themselves.
16916 GNU Emacs is mostly written in Emacs Lisp; this means that by writing
16917 expressions in Emacs Lisp you can change or extend Emacs.
16920 * Default Configuration::
16923 * Beginning a .emacs File::
16924 * Text and Auto-fill::
16926 * Indent Tabs Mode::
16931 * Simple Extension::
16937 @node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization
16939 @unnumberedsec Emacs' Default Configuration
16942 There are those who appreciate Emacs' default configuration. After
16943 all, Emacs starts you in C mode when you edit a C file, starts you in
16944 Fortran mode when you edit a Fortran file, and starts you in
16945 Fundamental mode when you edit an unadorned file. This all makes
16946 sense, if you do not know who is going to use Emacs. Who knows what a
16947 person hopes to do with an unadorned file? Fundamental mode is the
16948 right default for such a file, just as C mode is the right default for
16949 editing C code. (Enough programming languages have syntaxes
16950 that enable them to share or nearly share features, so C mode is
16951 now provided by by CC mode, the `C Collection'.)
16953 But when you do know who is going to use Emacs---you,
16954 yourself---then it makes sense to customize Emacs.
16956 For example, I seldom want Fundamental mode when I edit an
16957 otherwise undistinguished file; I want Text mode. This is why I
16958 customize Emacs: so it suits me.
16960 You can customize and extend Emacs by writing or adapting a
16961 @file{~/.emacs} file. This is your personal initialization file; its
16962 contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You
16963 may also add @file{.el} to @file{~/.emacs} and call it a
16964 @file{~/.emacs.el} file. In the past, you were forbidden to type the
16965 extra keystrokes that the name @file{~/.emacs.el} requires, but now
16966 you may. The new format is consistent with the Emacs Lisp file
16967 naming conventions; the old format saves typing.}
16969 A @file{~/.emacs} file contains Emacs Lisp code. You can write this
16970 code yourself; or you can use Emacs' @code{customize} feature to write
16971 the code for you. You can combine your own expressions and
16972 auto-written Customize expressions in your @file{.emacs} file.
16974 (I myself prefer to write my own expressions, except for those,
16975 particularly fonts, that I find easier to manipulate using the
16976 @code{customize} command. I combine the two methods.)
16978 Most of this chapter is about writing expressions yourself. It
16979 describes a simple @file{.emacs} file; for more information, see
16980 @ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and
16981 @ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference
16984 @node Site-wide Init, defcustom, Default Configuration, Emacs Initialization
16985 @section Site-wide Initialization Files
16987 @cindex @file{default.el} init file
16988 @cindex @file{site-init.el} init file
16989 @cindex @file{site-load.el} init file
16990 In addition to your personal initialization file, Emacs automatically
16991 loads various site-wide initialization files, if they exist. These
16992 have the same form as your @file{.emacs} file, but are loaded by
16995 Two site-wide initialization files, @file{site-load.el} and
16996 @file{site-init.el}, are loaded into Emacs and then `dumped' if a
16997 `dumped' version of Emacs is created, as is most common. (Dumped
16998 copies of Emacs load more quickly. However, once a file is loaded and
16999 dumped, a change to it does not lead to a change in Emacs unless you
17000 load it yourself or re-dump Emacs. @xref{Building Emacs, , Building
17001 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the
17002 @file{INSTALL} file.)
17004 Three other site-wide initialization files are loaded automatically
17005 each time you start Emacs, if they exist. These are
17006 @file{site-start.el}, which is loaded @emph{before} your @file{.emacs}
17007 file, and @file{default.el}, and the terminal type file, which are both
17008 loaded @emph{after} your @file{.emacs} file.
17010 Settings and definitions in your @file{.emacs} file will overwrite
17011 conflicting settings and definitions in a @file{site-start.el} file,
17012 if it exists; but the settings and definitions in a @file{default.el}
17013 or terminal type file will overwrite those in your @file{.emacs} file.
17014 (You can prevent interference from a terminal type file by setting
17015 @code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A
17016 Simple Extension}.)
17018 @c Rewritten to avoid overfull hbox.
17019 The @file{INSTALL} file that comes in the distribution contains
17020 descriptions of the @file{site-init.el} and @file{site-load.el} files.
17022 The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files
17023 control loading. These files are in the @file{lisp} directory of the
17024 Emacs distribution and are worth perusing.
17026 The @file{loaddefs.el} file contains a good many suggestions as to
17027 what to put into your own @file{.emacs} file, or into a site-wide
17028 initialization file.
17030 @node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization
17031 @section Specifying Variables using @code{defcustom}
17034 You can specify variables using @code{defcustom} so that you and
17035 others can then use Emacs' @code{customize} feature to set their
17036 values. (You cannot use @code{customize} to write function
17037 definitions; but you can write @code{defuns} in your @file{.emacs}
17038 file. Indeed, you can write any Lisp expression in your @file{.emacs}
17041 The @code{customize} feature depends on the @code{defcustom} special
17042 form. Although you can use @code{defvar} or @code{setq} for variables
17043 that users set, the @code{defcustom} special form is designed for the
17046 You can use your knowledge of @code{defvar} for writing the
17047 first three arguments for @code{defcustom}. The first argument to
17048 @code{defcustom} is the name of the variable. The second argument is
17049 the variable's initial value, if any; and this value is set only if
17050 the value has not already been set. The third argument is the
17053 The fourth and subsequent arguments to @code{defcustom} specify types
17054 and options; these are not featured in @code{defvar}. (These
17055 arguments are optional.)
17057 Each of these arguments consists of a keyword followed by a value.
17058 Each keyword starts with the colon character @samp{:}.
17061 For example, the customizable user option variable
17062 @code{text-mode-hook} looks like this:
17066 (defcustom text-mode-hook nil
17067 "Normal hook run when entering Text mode and many related modes."
17069 :options '(turn-on-auto-fill flyspell-mode)
17075 The name of the variable is @code{text-mode-hook}; it has no default
17076 value; and its documentation string tells you what it does.
17078 The @code{:type} keyword tells Emacs the kind of data to which
17079 @code{text-mode-hook} should be set and how to display the value in a
17080 Customization buffer.
17082 The @code{:options} keyword specifies a suggested list of values for
17083 the variable. Usually, @code{:options} applies to a hook.
17084 The list is only a suggestion; it is not exclusive; a person who sets
17085 the variable may set it to other values; the list shown following the
17086 @code{:options} keyword is intended to offer convenient choices to a
17089 Finally, the @code{:group} keyword tells the Emacs Customization
17090 command in which group the variable is located. This tells where to
17093 The @code{defcustom} function recognizes more than a dozen keywords.
17094 For more information, see @ref{Customization, , Writing Customization
17095 Definitions, elisp, The GNU Emacs Lisp Reference Manual}.
17097 Consider @code{text-mode-hook} as an example.
17099 There are two ways to customize this variable. You can use the
17100 customization command or write the appropriate expressions yourself.
17103 Using the customization command, you can type:
17110 and find that the group for editing files of data is called `data'.
17111 Enter that group. Text Mode Hook is the first member. You can click
17112 on its various options, such as @code{turn-on-auto-fill}, to set the
17113 values. After you click on the button to
17116 Save for Future Sessions
17120 Emacs will write an expression into your @file{.emacs} file.
17121 It will look like this:
17125 (custom-set-variables
17126 ;; custom-set-variables was added by Custom.
17127 ;; If you edit it by hand, you could mess it up, so be careful.
17128 ;; Your init file should contain only one such instance.
17129 ;; If there is more than one, they won't work right.
17130 '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
17135 (The @code{text-mode-hook-identify} function tells
17136 @code{toggle-text-mode-auto-fill} which buffers are in Text mode.
17137 It comes on automatically.)
17139 The @code{custom-set-variables} function works somewhat differently
17140 than a @code{setq}. While I have never learned the differences, I
17141 modify the @code{custom-set-variables} expressions in my @file{.emacs}
17142 file by hand: I make the changes in what appears to me to be a
17143 reasonable manner and have not had any problems. Others prefer to use
17144 the Customization command and let Emacs do the work for them.
17146 Another @code{custom-set-@dots{}} function is @code{custom-set-faces}.
17147 This function sets the various font faces. Over time, I have set a
17148 considerable number of faces. Some of the time, I re-set them using
17149 @code{customize}; other times, I simply edit the
17150 @code{custom-set-faces} expression in my @file{.emacs} file itself.
17152 The second way to customize your @code{text-mode-hook} is to set it
17153 yourself in your @file{.emacs} file using code that has nothing to do
17154 with the @code{custom-set-@dots{}} functions.
17157 When you do this, and later use @code{customize}, you will see a
17161 CHANGED outside Customize; operating on it here may be unreliable.
17165 This message is only a warning. If you click on the button to
17168 Save for Future Sessions
17172 Emacs will write a @code{custom-set-@dots{}} expression near the end
17173 of your @file{.emacs} file that will be evaluated after your
17174 hand-written expression. It will, therefore, overrule your
17175 hand-written expression. No harm will be done. When you do this,
17176 however, be careful to remember which expression is active; if you
17177 forget, you may confuse yourself.
17179 So long as you remember where the values are set, you will have no
17180 trouble. In any event, the values are always set in your
17181 initialization file, which is usually called @file{.emacs}.
17183 I myself use @code{customize} for hardly anything. Mostly, I write
17184 expressions myself.
17188 Incidentally, to be more complete concerning defines: @code{defsubst}
17189 defines an inline function. The syntax is just like that of
17190 @code{defun}. @code{defconst} defines a symbol as a constant. The
17191 intent is that neither programs nor users should ever change a value
17192 set by @code{defconst}. (You can change it; the value set is a
17193 variable; but please do not.)
17195 @node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization
17196 @section Beginning a @file{.emacs} File
17197 @cindex @file{.emacs} file, beginning of
17199 When you start Emacs, it loads your @file{.emacs} file unless you tell
17200 it not to by specifying @samp{-q} on the command line. (The
17201 @code{emacs -q} command gives you a plain, out-of-the-box Emacs.)
17203 A @file{.emacs} file contains Lisp expressions. Often, these are no
17204 more than expressions to set values; sometimes they are function
17207 @xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs
17208 Manual}, for a short description of initialization files.
17210 This chapter goes over some of the same ground, but is a walk among
17211 extracts from a complete, long-used @file{.emacs} file---my own.
17213 The first part of the file consists of comments: reminders to myself.
17214 By now, of course, I remember these things, but when I started, I did
17220 ;;;; Bob's .emacs file
17221 ; Robert J. Chassell
17222 ; 26 September 1985
17227 Look at that date! I started this file a long time ago. I have been
17228 adding to it ever since.
17232 ; Each section in this file is introduced by a
17233 ; line beginning with four semicolons; and each
17234 ; entry is introduced by a line beginning with
17235 ; three semicolons.
17240 This describes the usual conventions for comments in Emacs Lisp.
17241 Everything on a line that follows a semicolon is a comment. Two,
17242 three, and four semicolons are used as subsection and section markers.
17243 (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for
17244 more about comments.)
17249 ; Control-h is the help key;
17250 ; after typing control-h, type a letter to
17251 ; indicate the subject about which you want help.
17252 ; For an explanation of the help facility,
17253 ; type control-h two times in a row.
17258 Just remember: type @kbd{C-h} two times for help.
17262 ; To find out about any mode, type control-h m
17263 ; while in that mode. For example, to find out
17264 ; about mail mode, enter mail mode and then type
17270 `Mode help', as I call this, is very helpful. Usually, it tells you
17271 all you need to know.
17273 Of course, you don't need to include comments like these in your
17274 @file{.emacs} file. I included them in mine because I kept forgetting
17275 about Mode help or the conventions for comments---but I was able to
17276 remember to look here to remind myself.
17278 @node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization
17279 @section Text and Auto Fill Mode
17281 Now we come to the part that `turns on' Text mode and
17286 ;;; Text mode and Auto Fill mode
17287 ; The next two lines put Emacs into Text mode
17288 ; and Auto Fill mode, and are for writers who
17289 ; want to start writing prose rather than code.
17290 (setq default-major-mode 'text-mode)
17291 (add-hook 'text-mode-hook 'turn-on-auto-fill)
17295 Here is the first part of this @file{.emacs} file that does something
17296 besides remind a forgetful human!
17298 The first of the two lines in parentheses tells Emacs to turn on Text
17299 mode when you find a file, @emph{unless} that file should go into some
17300 other mode, such as C mode.
17302 @cindex Per-buffer, local variables list
17303 @cindex Local variables list, per-buffer,
17304 @cindex Automatic mode selection
17305 @cindex Mode selection, automatic
17306 When Emacs reads a file, it looks at the extension to the file name,
17307 if any. (The extension is the part that comes after a @samp{.}.) If
17308 the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns
17309 on C mode. Also, Emacs looks at first nonblank line of the file; if
17310 the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs
17311 possesses a list of extensions and specifications that it uses
17312 automatically. In addition, Emacs looks near the last page for a
17313 per-buffer, ``local variables list'', if any.
17316 @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU
17319 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
17323 See sections ``How Major Modes are Chosen'' and ``Local Variables in
17324 Files'' in @cite{The GNU Emacs Manual}.
17327 Now, back to the @file{.emacs} file.
17330 Here is the line again; how does it work?
17332 @cindex Text Mode turned on
17334 (setq default-major-mode 'text-mode)
17338 This line is a short, but complete Emacs Lisp expression.
17340 We are already familiar with @code{setq}. It sets the following variable,
17341 @code{default-major-mode}, to the subsequent value, which is
17342 @code{text-mode}. The single quote mark before @code{text-mode} tells
17343 Emacs to deal directly with the @code{text-mode} variable, not with
17344 whatever it might stand for. @xref{set & setq, , Setting the Value of
17345 a Variable}, for a reminder of how @code{setq} works. The main point
17346 is that there is no difference between the procedure you use to set
17347 a value in your @file{.emacs} file and the procedure you use anywhere
17351 Here is the next line:
17353 @cindex Auto Fill mode turned on
17356 (add-hook 'text-mode-hook 'turn-on-auto-fill)
17360 In this line, the @code{add-hook} command adds
17361 @code{turn-on-auto-fill} to the variable.
17363 @code{turn-on-auto-fill} is the name of a program, that, you guessed
17364 it!, turns on Auto Fill mode.
17366 Every time Emacs turns on Text mode, Emacs runs the commands `hooked'
17367 onto Text mode. So every time Emacs turns on Text mode, Emacs also
17368 turns on Auto Fill mode.
17370 In brief, the first line causes Emacs to enter Text mode when you edit a
17371 file, unless the file name extension, a first non-blank line, or local
17372 variables to tell Emacs otherwise.
17374 Text mode among other actions, sets the syntax table to work
17375 conveniently for writers. In Text mode, Emacs considers an apostrophe
17376 as part of a word like a letter; but Emacs does not consider a period
17377 or a space as part of a word. Thus, @kbd{M-f} moves you over
17378 @samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after
17379 the @samp{t} of @samp{it's}.
17381 The second line causes Emacs to turn on Auto Fill mode when it turns
17382 on Text mode. In Auto Fill mode, Emacs automatically breaks a line
17383 that is too wide and brings the excessively wide part of the line down
17384 to the next line. Emacs breaks lines between words, not within them.
17386 When Auto Fill mode is turned off, lines continue to the right as you
17387 type them. Depending on how you set the value of
17388 @code{truncate-lines}, the words you type either disappear off the
17389 right side of the screen, or else are shown, in a rather ugly and
17390 unreadable manner, as a continuation line on the screen.
17393 In addition, in this part of my @file{.emacs} file, I tell the Emacs
17394 fill commands to insert two spaces after a colon:
17397 (setq colon-double-space t)
17400 @node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization
17401 @section Mail Aliases
17403 Here is a @code{setq} that `turns on' mail aliases, along with more
17409 ; To enter mail mode, type `C-x m'
17410 ; To enter RMAIL (for reading mail),
17412 (setq mail-aliases t)
17416 @cindex Mail aliases
17418 This @code{setq} command sets the value of the variable
17419 @code{mail-aliases} to @code{t}. Since @code{t} means true, the line
17420 says, in effect, ``Yes, use mail aliases.''
17422 Mail aliases are convenient short names for long email addresses or
17423 for lists of email addresses. The file where you keep your `aliases'
17424 is @file{~/.mailrc}. You write an alias like this:
17427 alias geo george@@foobar.wiz.edu
17431 When you write a message to George, address it to @samp{geo}; the
17432 mailer will automatically expand @samp{geo} to the full address.
17434 @node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization
17435 @section Indent Tabs Mode
17436 @cindex Tabs, preventing
17437 @findex indent-tabs-mode
17439 By default, Emacs inserts tabs in place of multiple spaces when it
17440 formats a region. (For example, you might indent many lines of text
17441 all at once with the @code{indent-region} command.) Tabs look fine on
17442 a terminal or with ordinary printing, but they produce badly indented
17443 output when you use @TeX{} or Texinfo since @TeX{} ignores tabs.
17446 The following turns off Indent Tabs mode:
17450 ;;; Prevent Extraneous Tabs
17451 (setq-default indent-tabs-mode nil)
17455 Note that this line uses @code{setq-default} rather than the
17456 @code{setq} command that we have seen before. The @code{setq-default}
17457 command sets values only in buffers that do not have their own local
17458 values for the variable.
17461 @xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}.
17463 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
17467 See sections ``Tabs vs.@: Spaces'' and ``Local Variables in
17468 Files'' in @cite{The GNU Emacs Manual}.
17472 @node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization
17473 @section Some Keybindings
17475 Now for some personal keybindings:
17479 ;;; Compare windows
17480 (global-set-key "\C-cw" 'compare-windows)
17484 @findex compare-windows
17485 @code{compare-windows} is a nifty command that compares the text in
17486 your current window with text in the next window. It makes the
17487 comparison by starting at point in each window, moving over text in
17488 each window as far as they match. I use this command all the time.
17490 This also shows how to set a key globally, for all modes.
17492 @cindex Setting a key globally
17493 @cindex Global set key
17494 @cindex Key setting globally
17495 @findex global-set-key
17496 The command is @code{global-set-key}. It is followed by the
17497 keybinding. In a @file{.emacs} file, the keybinding is written as
17498 shown: @code{\C-c} stands for `control-c', which means `press the
17499 control key and the @key{c} key at the same time'. The @code{w} means
17500 `press the @key{w} key'. The keybinding is surrounded by double
17501 quotation marks. In documentation, you would write this as
17502 @w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as
17503 @kbd{M-c}, rather than a @key{CTRL} key, you would write
17504 @w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, ,
17505 Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for
17508 The command invoked by the keys is @code{compare-windows}. Note that
17509 @code{compare-windows} is preceded by a single quote; otherwise, Emacs
17510 would first try to evaluate the symbol to determine its value.
17512 These three things, the double quotation marks, the backslash before
17513 the @samp{C}, and the single quote mark are necessary parts of
17514 keybinding that I tend to forget. Fortunately, I have come to
17515 remember that I should look at my existing @file{.emacs} file, and
17516 adapt what is there.
17518 As for the keybinding itself: @kbd{C-c w}. This combines the prefix
17519 key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This
17520 set of keys, @kbd{C-c} followed by a single character, is strictly
17521 reserved for individuals' own use. (I call these `own' keys, since
17522 these are for my own use.) You should always be able to create such a
17523 keybinding for your own use without stomping on someone else's
17524 keybinding. If you ever write an extension to Emacs, please avoid
17525 taking any of these keys for public use. Create a key like @kbd{C-c
17526 C-w} instead. Otherwise, we will run out of `own' keys.
17529 Here is another keybinding, with a comment:
17533 ;;; Keybinding for `occur'
17534 ; I use occur a lot, so let's bind it to a key:
17535 (global-set-key "\C-co" 'occur)
17540 The @code{occur} command shows all the lines in the current buffer
17541 that contain a match for a regular expression. Matching lines are
17542 shown in a buffer called @file{*Occur*}. That buffer serves as a menu
17543 to jump to occurrences.
17545 @findex global-unset-key
17546 @cindex Unbinding key
17547 @cindex Key unbinding
17549 Here is how to unbind a key, so it does not
17555 (global-unset-key "\C-xf")
17559 There is a reason for this unbinding: I found I inadvertently typed
17560 @w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a
17561 file, as I intended, I accidentally set the width for filled text,
17562 almost always to a width I did not want. Since I hardly ever reset my
17563 default width, I simply unbound the key.
17565 @findex list-buffers, @r{rebound}
17566 @findex buffer-menu, @r{bound to key}
17568 The following rebinds an existing key:
17572 ;;; Rebind `C-x C-b' for `buffer-menu'
17573 (global-set-key "\C-x\C-b" 'buffer-menu)
17577 By default, @kbd{C-x C-b} runs the
17578 @code{list-buffers} command. This command lists
17579 your buffers in @emph{another} window. Since I
17580 almost always want to do something in that
17581 window, I prefer the @code{buffer-menu}
17582 command, which not only lists the buffers,
17583 but moves point into that window.
17585 @node Keymaps, Loading Files, Keybindings, Emacs Initialization
17588 @cindex Rebinding keys
17590 Emacs uses @dfn{keymaps} to record which keys call which commands.
17591 When you use @code{global-set-key} to set the keybinding for a single
17592 command in all parts of Emacs, you are specifying the keybinding in
17593 @code{current-global-map}.
17595 Specific modes, such as C mode or Text mode, have their own keymaps;
17596 the mode-specific keymaps override the global map that is shared by
17599 The @code{global-set-key} function binds, or rebinds, the global
17600 keymap. For example, the following binds the key @kbd{C-x C-b} to the
17601 function @code{buffer-menu}:
17604 (global-set-key "\C-x\C-b" 'buffer-menu)
17607 Mode-specific keymaps are bound using the @code{define-key} function,
17608 which takes a specific keymap as an argument, as well as the key and
17609 the command. For example, my @file{.emacs} file contains the
17610 following expression to bind the @code{texinfo-insert-@@group} command
17611 to @kbd{C-c C-c g}:
17615 (define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group)
17620 The @code{texinfo-insert-@@group} function itself is a little extension
17621 to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I
17622 use this command all the time and prefer to type the three strokes
17623 @kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}.
17624 (@samp{@@group} and its matching @samp{@@end group} are commands that
17625 keep all enclosed text together on one page; many multi-line examples
17626 in this book are surrounded by @samp{@@group @dots{} @@end group}.)
17629 Here is the @code{texinfo-insert-@@group} function definition:
17633 (defun texinfo-insert-@@group ()
17634 "Insert the string @@group in a Texinfo buffer."
17636 (beginning-of-line)
17637 (insert "@@group\n"))
17641 (Of course, I could have used Abbrev mode to save typing, rather than
17642 write a function to insert a word; but I prefer key strokes consistent
17643 with other Texinfo mode key bindings.)
17645 You will see numerous @code{define-key} expressions in
17646 @file{loaddefs.el} as well as in the various mode libraries, such as
17647 @file{cc-mode.el} and @file{lisp-mode.el}.
17649 @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs
17650 Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp
17651 Reference Manual}, for more information about keymaps.
17653 @node Loading Files, Autoload, Keymaps, Emacs Initialization
17654 @section Loading Files
17655 @cindex Loading files
17658 Many people in the GNU Emacs community have written extensions to
17659 Emacs. As time goes by, these extensions are often included in new
17660 releases. For example, the Calendar and Diary packages are now part
17661 of the standard GNU Emacs, as is Calc.
17663 You can use a @code{load} command to evaluate a complete file and
17664 thereby install all the functions and variables in the file into Emacs.
17667 @c (auto-compression-mode t)
17670 (load "~/emacs/slowsplit")
17673 This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it
17674 exists, the faster, byte compiled @file{slowsplit.elc} file from the
17675 @file{emacs} sub-directory of your home directory. The file contains
17676 the function @code{split-window-quietly}, which John Robinson wrote in
17679 The @code{split-window-quietly} function splits a window with the
17680 minimum of redisplay. I installed it in 1989 because it worked well
17681 with the slow 1200 baud terminals I was then using. Nowadays, I only
17682 occasionally come across such a slow connection, but I continue to use
17683 the function because I like the way it leaves the bottom half of a
17684 buffer in the lower of the new windows and the top half in the upper
17688 To replace the key binding for the default
17689 @code{split-window-vertically}, you must also unset that key and bind
17690 the keys to @code{split-window-quietly}, like this:
17694 (global-unset-key "\C-x2")
17695 (global-set-key "\C-x2" 'split-window-quietly)
17700 If you load many extensions, as I do, then instead of specifying the
17701 exact location of the extension file, as shown above, you can specify
17702 that directory as part of Emacs' @code{load-path}. Then, when Emacs
17703 loads a file, it will search that directory as well as its default
17704 list of directories. (The default list is specified in @file{paths.h}
17705 when Emacs is built.)
17708 The following command adds your @file{~/emacs} directory to the
17709 existing load path:
17713 ;;; Emacs Load Path
17714 (setq load-path (cons "~/emacs" load-path))
17718 Incidentally, @code{load-library} is an interactive interface to the
17719 @code{load} function. The complete function looks like this:
17721 @findex load-library
17724 (defun load-library (library)
17725 "Load the library named LIBRARY.
17726 This is an interface to the function `load'."
17728 (list (completing-read "Load library: "
17729 'locate-file-completion
17730 (cons load-path (get-load-suffixes)))))
17735 The name of the function, @code{load-library}, comes from the use of
17736 `library' as a conventional synonym for `file'. The source for the
17737 @code{load-library} command is in the @file{files.el} library.
17739 Another interactive command that does a slightly different job is
17740 @code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for
17741 Emacs, emacs, The GNU Emacs Manual}, for information on the
17742 distinction between @code{load-library} and this command.
17744 @node Autoload, Simple Extension, Loading Files, Emacs Initialization
17745 @section Autoloading
17748 Instead of installing a function by loading the file that contains it,
17749 or by evaluating the function definition, you can make the function
17750 available but not actually install it until it is first called. This
17751 is called @dfn{autoloading}.
17753 When you execute an autoloaded function, Emacs automatically evaluates
17754 the file that contains the definition, and then calls the function.
17756 Emacs starts quicker with autoloaded functions, since their libraries
17757 are not loaded right away; but you need to wait a moment when you
17758 first use such a function, while its containing file is evaluated.
17760 Rarely used functions are frequently autoloaded. The
17761 @file{loaddefs.el} library contains hundreds of autoloaded functions,
17762 from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may
17763 come to use a `rare' function frequently. When you do, you should
17764 load that function's file with a @code{load} expression in your
17765 @file{.emacs} file.
17767 In my @file{.emacs} file for Emacs version 22, I load 14 libraries
17768 that contain functions that would otherwise be autoloaded. (Actually,
17769 it would have been better to include these files in my `dumped' Emacs,
17770 but I forgot. @xref{Building Emacs, , Building Emacs, elisp, The GNU
17771 Emacs Lisp Reference Manual}, and the @file{INSTALL} file for more
17774 You may also want to include autoloaded expressions in your @file{.emacs}
17775 file. @code{autoload} is a built-in function that takes up to five
17776 arguments, the final three of which are optional. The first argument
17777 is the name of the function to be autoloaded; the second is the name
17778 of the file to be loaded. The third argument is documentation for the
17779 function, and the fourth tells whether the function can be called
17780 interactively. The fifth argument tells what type of
17781 object---@code{autoload} can handle a keymap or macro as well as a
17782 function (the default is a function).
17785 Here is a typical example:
17789 (autoload 'html-helper-mode
17790 "html-helper-mode" "Edit HTML documents" t)
17795 (@code{html-helper-mode} is an older alternative to @code{html-mode},
17796 which is a standard part of the distribution.)
17799 This expression autoloads the @code{html-helper-mode} function. It
17800 takes it from the @file{html-helper-mode.el} file (or from the byte
17801 compiled file @file{html-helper-mode.elc}, if it exists.) The file
17802 must be located in a directory specified by @code{load-path}. The
17803 documentation says that this is a mode to help you edit documents
17804 written in the HyperText Markup Language. You can call this mode
17805 interactively by typing @kbd{M-x html-helper-mode}. (You need to
17806 duplicate the function's regular documentation in the autoload
17807 expression because the regular function is not yet loaded, so its
17808 documentation is not available.)
17810 @xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference
17811 Manual}, for more information.
17813 @node Simple Extension, X11 Colors, Autoload, Emacs Initialization
17814 @section A Simple Extension: @code{line-to-top-of-window}
17815 @findex line-to-top-of-window
17816 @cindex Simple extension in @file{.emacs} file
17818 Here is a simple extension to Emacs that moves the line point is on to
17819 the top of the window. I use this all the time, to make text easier
17822 You can put the following code into a separate file and then load it
17823 from your @file{.emacs} file, or you can include it within your
17824 @file{.emacs} file.
17827 Here is the definition:
17831 ;;; Line to top of window;
17832 ;;; replace three keystroke sequence C-u 0 C-l
17833 (defun line-to-top-of-window ()
17834 "Move the line point is on to top of window."
17841 Now for the keybinding.
17843 Nowadays, function keys as well as mouse button events and
17844 non-@sc{ascii} characters are written within square brackets, without
17845 quotation marks. (In Emacs version 18 and before, you had to write
17846 different function key bindings for each different make of terminal.)
17848 I bind @code{line-to-top-of-window} to my @key{F6} function key like
17852 (global-set-key [f6] 'line-to-top-of-window)
17855 For more information, see @ref{Init Rebinding, , Rebinding Keys in
17856 Your Init File, emacs, The GNU Emacs Manual}.
17858 @cindex Conditional 'twixt two versions of Emacs
17859 @cindex Version of Emacs, choosing
17860 @cindex Emacs version, choosing
17861 If you run two versions of GNU Emacs, such as versions 21 and 22, and
17862 use one @file{.emacs} file, you can select which code to evaluate with
17863 the following conditional:
17868 (= 21 emacs-major-version)
17869 ;; evaluate version 21 code
17871 (= 22 emacs-major-version)
17872 ;; evaluate version 22 code
17877 For example, in contrast to version 20, more recent versions blink
17878 their cursors by default. I hate such blinking, as well as other
17879 features, so I placed the following in my @file{.emacs}
17880 file@footnote{When I start instances of Emacs that do not load my
17881 @file{.emacs} file or any site file, I also turn off blinking:
17884 emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
17886 @exdent Or nowadays, using an even more sophisticated set of options,
17894 (when (or (= 21 emacs-major-version)
17895 (= 22 emacs-major-version))
17896 (blink-cursor-mode 0)
17897 ;; Insert newline when you press `C-n' (next-line)
17898 ;; at the end of the buffer
17899 (setq next-line-add-newlines t)
17902 ;; Turn on image viewing
17903 (auto-image-file-mode t)
17906 ;; Turn on menu bar (this bar has text)
17907 ;; (Use numeric argument to turn on)
17911 ;; Turn off tool bar (this bar has icons)
17912 ;; (Use numeric argument to turn on)
17913 (tool-bar-mode nil)
17916 ;; Turn off tooltip mode for tool bar
17917 ;; (This mode causes icon explanations to pop up)
17918 ;; (Use numeric argument to turn on)
17920 ;; If tooltips turned on, make tips appear promptly
17921 (setq tooltip-delay 0.1) ; default is 0.7 second
17926 @node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization
17927 @section X11 Colors
17929 You can specify colors when you use Emacs with the MIT X Windowing
17932 I dislike the default colors and specify my own.
17935 Here are the expressions in my @file{.emacs}
17936 file that set values:
17940 ;; Set cursor color
17941 (set-cursor-color "white")
17944 (set-mouse-color "white")
17946 ;; Set foreground and background
17947 (set-foreground-color "white")
17948 (set-background-color "darkblue")
17952 ;;; Set highlighting colors for isearch and drag
17953 (set-face-foreground 'highlight "white")
17954 (set-face-background 'highlight "blue")
17958 (set-face-foreground 'region "cyan")
17959 (set-face-background 'region "blue")
17963 (set-face-foreground 'secondary-selection "skyblue")
17964 (set-face-background 'secondary-selection "darkblue")
17968 ;; Set calendar highlighting colors
17969 (setq calendar-load-hook
17971 (set-face-foreground 'diary-face "skyblue")
17972 (set-face-background 'holiday-face "slate blue")
17973 (set-face-foreground 'holiday-face "white")))
17977 The various shades of blue soothe my eye and prevent me from seeing
17978 the screen flicker.
17980 Alternatively, I could have set my specifications in various X
17981 initialization files. For example, I could set the foreground,
17982 background, cursor, and pointer (i.e., mouse) colors in my
17983 @file{~/.Xresources} file like this:
17987 Emacs*foreground: white
17988 Emacs*background: darkblue
17989 Emacs*cursorColor: white
17990 Emacs*pointerColor: white
17994 In any event, since it is not part of Emacs, I set the root color of
17995 my X window in my @file{~/.xinitrc} file, like this@footnote{I also
17996 run more modern window managers, such as Enlightenment, Gnome, or KDE;
17997 in those cases, I often specify an image rather than a plain color.}:
18000 xsetroot -solid Navy -fg white &
18004 @node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization
18005 @section Miscellaneous Settings for a @file{.emacs} File
18008 Here are a few miscellaneous settings:
18013 Set the shape and color of the mouse cursor:
18017 ; Cursor shapes are defined in
18018 ; `/usr/include/X11/cursorfont.h';
18019 ; for example, the `target' cursor is number 128;
18020 ; the `top_left_arrow' cursor is number 132.
18024 (let ((mpointer (x-get-resource "*mpointer"
18025 "*emacs*mpointer")))
18026 ;; If you have not set your mouse pointer
18027 ;; then set it, otherwise leave as is:
18028 (if (eq mpointer nil)
18029 (setq mpointer "132")) ; top_left_arrow
18032 (setq x-pointer-shape (string-to-int mpointer))
18033 (set-mouse-color "white"))
18038 Or you can set the values of a variety of features in an alist, like
18044 default-frame-alist
18045 '((cursor-color . "white")
18046 (mouse-color . "white")
18047 (foreground-color . "white")
18048 (background-color . "DodgerBlue4")
18049 ;; (cursor-type . bar)
18050 (cursor-type . box)
18053 (tool-bar-lines . 0)
18054 (menu-bar-lines . 1)
18058 "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1")
18064 Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL}
18065 into @kbd{@key{CTRL}-h}.@*
18066 (Some older keyboards needed this, although I have not seen the
18071 ;; Translate `C-h' to <DEL>.
18072 ; (keyboard-translate ?\C-h ?\C-?)
18074 ;; Translate <DEL> to `C-h'.
18075 (keyboard-translate ?\C-? ?\C-h)
18079 @item Turn off a blinking cursor!
18083 (if (fboundp 'blink-cursor-mode)
18084 (blink-cursor-mode -1))
18089 or start GNU Emacs with the command @code{emacs -nbc}.
18092 @item When using `grep'@*
18093 @samp{-i}@w{ } Ignore case distinctions@*
18094 @samp{-n}@w{ } Prefix each line of output with line number@*
18095 @samp{-H}@w{ } Print the filename for each match.@*
18096 @samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-}
18099 (setq grep-command "grep -i -nH -e ")
18103 @c Evidently, no longer needed in GNU Emacs 22
18105 item Automatically uncompress compressed files when visiting them
18108 (load "uncompress")
18113 @item Find an existing buffer, even if it has a different name@*
18114 This avoids problems with symbolic links.
18117 (setq find-file-existing-other-name t)
18120 @item Set your language environment and default input method
18124 (set-language-environment "latin-1")
18125 ;; Remember you can enable or disable multilingual text input
18126 ;; with the @code{toggle-input-method'} (@kbd{C-\}) command
18127 (setq default-input-method "latin-1-prefix")
18131 If you want to write with Chinese `GB' characters, set this instead:
18135 (set-language-environment "Chinese-GB")
18136 (setq default-input-method "chinese-tonepy")
18141 @subsubheading Fixing Unpleasant Key Bindings
18142 @cindex Key bindings, fixing
18143 @cindex Bindings, key, fixing unpleasant
18145 Some systems bind keys unpleasantly. Sometimes, for example, the
18146 @key{CTRL} key appears in an awkward spot rather than at the far left
18149 Usually, when people fix these sorts of keybindings, they do not
18150 change their @file{~/.emacs} file. Instead, they bind the proper keys
18151 on their consoles with the @code{loadkeys} or @code{install-keymap}
18152 commands in their boot script and then include @code{xmodmap} commands
18153 in their @file{.xinitrc} or @file{.Xsession} file for X Windows.
18161 loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz
18163 install-keymap emacs2
18169 For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps
18170 Lock} key is at the far left of the home row:
18174 # Bind the key labeled `Caps Lock' to `Control'
18175 # (Such a broken user interface suggests that keyboard manufacturers
18176 # think that computers are typewriters from 1885.)
18178 xmodmap -e "clear Lock"
18179 xmodmap -e "add Control = Caps_Lock"
18185 In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT}
18186 key to a @key{META} key:
18190 # Some ill designed keyboards have a key labeled ALT and no Meta
18191 xmodmap -e "keysym Alt_L = Meta_L Alt_L"
18196 @node Mode Line, , Miscellaneous, Emacs Initialization
18197 @section A Modified Mode Line
18198 @vindex default-mode-line-format
18199 @cindex Mode line format
18201 Finally, a feature I really like: a modified mode line.
18203 When I work over a network, I forget which machine I am using. Also,
18204 I tend to I lose track of where I am, and which line point is on.
18206 So I reset my mode line to look like this:
18209 -:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top
18212 I am visiting a file called @file{foo.texi}, on my machine
18213 @file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in
18214 Texinfo mode, and am at the top of the buffer.
18217 My @file{.emacs} file has a section that looks like this:
18221 ;; Set a Mode Line that tells me which machine, which directory,
18222 ;; and which line I am on, plus the other customary information.
18223 (setq default-mode-line-format
18227 "mouse-1: select window, mouse-2: delete others ..."))
18228 mode-line-mule-info
18230 mode-line-frame-identification
18234 mode-line-buffer-identification
18237 (system-name) 0 (string-match "\\..+" (system-name))))
18242 "mouse-1: select window, mouse-2: delete others ..."))
18243 (line-number-mode " Line %l ")
18249 "mouse-1: select window, mouse-2: delete others ..."))
18250 (:eval (mode-line-mode-name))
18253 #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
18262 Here, I redefine the default mode line. Most of the parts are from
18263 the original; but I make a few changes. I set the @emph{default} mode
18264 line format so as to permit various modes, such as Info, to override
18267 Many elements in the list are self-explanatory:
18268 @code{mode-line-modified} is a variable that tells whether the buffer
18269 has been modified, @code{mode-name} tells the name of the mode, and so
18270 on. However, the format looks complicated because of two features we
18271 have not discussed.
18273 @cindex Properties, in mode line example
18274 The first string in the mode line is a dash or hyphen, @samp{-}. In
18275 the old days, it would have been specified simply as @code{"-"}. But
18276 nowadays, Emacs can add properties to a string, such as highlighting
18277 or, as in this case, a help feature. If you place your mouse cursor
18278 over the hyphen, some help information appears (By default, you must
18279 wait seven-tenths of a second before the information appears. You can
18280 change that timing by changing the value of @code{tooltip-delay}.)
18283 The new string format has a special syntax:
18286 #("-" 0 1 (help-echo "mouse-1: select window, ..."))
18290 The @code{#(} begins a list. The first element of the list is the
18291 string itself, just one @samp{-}. The second and third
18292 elements specify the range over which the fourth element applies. A
18293 range starts @emph{after} a character, so a zero means the range
18294 starts just before the first character; a 1 means that the range ends
18295 just after the first character. The third element is the property for
18296 the range. It consists of a property list, a
18297 property name, in this case, @samp{help-echo}, followed by a value, in this
18298 case, a string. The second, third, and fourth elements of this new
18299 string format can be repeated.
18301 @xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp
18302 Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format,
18303 elisp, The GNU Emacs Lisp Reference Manual}, for more information.
18305 @code{mode-line-buffer-identification}
18306 displays the current buffer name. It is a list
18307 beginning @code{(#("%12b" 0 4 @dots{}}.
18308 The @code{#(} begins the list.
18310 The @samp{"%12b"} displays the current buffer name, using the
18311 @code{buffer-name} function with which we are familiar; the `12'
18312 specifies the maximum number of characters that will be displayed.
18313 When a name has fewer characters, whitespace is added to fill out to
18314 this number. (Buffer names can and often should be longer than 12
18315 characters; this length works well in a typical 80 column wide
18318 @code{:eval} says to evaluate the following form and use the result as
18319 a string to display. In this case, the expression displays the first
18320 component of the full system name. The end of the first component is
18321 a @samp{.} (`period'), so I use the @code{string-match} function to
18322 tell me the length of the first component. The substring from the
18323 zeroth character to that length is the name of the machine.
18326 This is the expression:
18331 (system-name) 0 (string-match "\\..+" (system-name))))
18335 @samp{%[} and @samp{%]} cause a pair of square brackets
18336 to appear for each recursive editing level. @samp{%n} says `Narrow'
18337 when narrowing is in effect. @samp{%P} tells you the percentage of
18338 the buffer that is above the bottom of the window, or `Top', `Bottom',
18339 or `All'. (A lower case @samp{p} tell you the percentage above the
18340 @emph{top} of the window.) @samp{%-} inserts enough dashes to fill
18343 Remember, ``You don't have to like Emacs to like it'' --- your own
18344 Emacs can have different colors, different commands, and different
18345 keys than a default Emacs.
18347 On the other hand, if you want to bring up a plain `out of the box'
18348 Emacs, with no customization, type:
18355 This will start an Emacs that does @emph{not} load your
18356 @file{~/.emacs} initialization file. A plain, default Emacs. Nothing
18359 @node Debugging, Conclusion, Emacs Initialization, Top
18363 GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The
18364 first is built into the internals of Emacs and is always with you;
18365 the second requires that you instrument a function before you can use it.
18367 Both debuggers are described extensively in @ref{Debugging, ,
18368 Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}.
18369 In this chapter, I will walk through a short example of each.
18376 * Debugging Exercises::
18379 @node debug, debug-on-entry, Debugging, Debugging
18380 @section @code{debug}
18383 Suppose you have written a function definition that is intended to
18384 return the sum of the numbers 1 through a given number. (This is the
18385 @code{triangle} function discussed earlier. @xref{Decrementing
18386 Example, , Example with Decrementing Counter}, for a discussion.)
18387 @c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.)
18389 However, your function definition has a bug. You have mistyped
18390 @samp{1=} for @samp{1-}. Here is the broken definition:
18392 @findex triangle-bugged
18395 (defun triangle-bugged (number)
18396 "Return sum of numbers 1 through NUMBER inclusive."
18398 (while (> number 0)
18399 (setq total (+ total number))
18400 (setq number (1= number))) ; @r{Error here.}
18405 If you are reading this in Info, you can evaluate this definition in
18406 the normal fashion. You will see @code{triangle-bugged} appear in the
18410 Now evaluate the @code{triangle-bugged} function with an
18414 (triangle-bugged 4)
18418 In a recent GNU Emacs, you will create and enter a @file{*Backtrace*}
18424 ---------- Buffer: *Backtrace* ----------
18425 Debugger entered--Lisp error: (void-function 1=)
18427 (setq number (1= number))
18428 (while (> number 0) (setq total (+ total number))
18429 (setq number (1= number)))
18430 (let ((total 0)) (while (> number 0) (setq total ...)
18431 (setq number ...)) total)
18435 eval((triangle-bugged 4))
18436 eval-last-sexp-1(nil)
18437 eval-last-sexp(nil)
18438 call-interactively(eval-last-sexp)
18439 ---------- Buffer: *Backtrace* ----------
18444 (I have reformatted this example slightly; the debugger does not fold
18445 long lines. As usual, you can quit the debugger by typing @kbd{q} in
18446 the @file{*Backtrace*} buffer.)
18448 In practice, for a bug as simple as this, the `Lisp error' line will
18449 tell you what you need to know to correct the definition. The
18450 function @code{1=} is `void'.
18454 In GNU Emacs 20 and before, you will see:
18457 Symbol's function definition is void:@: 1=
18461 which has the same meaning as the @file{*Backtrace*} buffer line in
18465 However, suppose you are not quite certain what is going on?
18466 You can read the complete backtrace.
18468 In this case, you need to run a recent GNU Emacs, which automatically
18469 starts the debugger that puts you in the @file{*Backtrace*} buffer; or
18470 else, you need to start the debugger manually as described below.
18472 Read the @file{*Backtrace*} buffer from the bottom up; it tells you
18473 what Emacs did that led to the error. Emacs made an interactive call
18474 to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation
18475 of the @code{triangle-bugged} expression. Each line above tells you
18476 what the Lisp interpreter evaluated next.
18479 The third line from the top of the buffer is
18482 (setq number (1= number))
18486 Emacs tried to evaluate this expression; in order to do so, it tried
18487 to evaluate the inner expression shown on the second line from the
18496 This is where the error occurred; as the top line says:
18499 Debugger entered--Lisp error: (void-function 1=)
18503 You can correct the mistake, re-evaluate the function definition, and
18504 then run your test again.
18506 @node debug-on-entry, debug-on-quit, debug, Debugging
18507 @section @code{debug-on-entry}
18508 @findex debug-on-entry
18510 A recent GNU Emacs starts the debugger automatically when your
18511 function has an error.
18514 GNU Emacs version 20 and before did not; it simply
18515 presented you with an error message. You had to start the debugger
18519 Incidentally, you can start the debugger manually for all versions of
18520 Emacs; the advantage is that the debugger runs even if you do not have
18521 a bug in your code. Sometimes your code will be free of bugs!
18523 You can enter the debugger when you call the function by calling
18524 @code{debug-on-entry}.
18531 M-x debug-on-entry RET triangle-bugged RET
18536 Now, evaluate the following:
18539 (triangle-bugged 5)
18543 All versions of Emacs will create a @file{*Backtrace*} buffer and tell
18544 you that it is beginning to evaluate the @code{triangle-bugged}
18549 ---------- Buffer: *Backtrace* ----------
18550 Debugger entered--entering a function:
18551 * triangle-bugged(5)
18552 eval((triangle-bugged 5))
18555 eval-last-sexp-1(nil)
18556 eval-last-sexp(nil)
18557 call-interactively(eval-last-sexp)
18558 ---------- Buffer: *Backtrace* ----------
18562 In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate
18563 the first expression in @code{triangle-bugged}; the buffer will look
18568 ---------- Buffer: *Backtrace* ----------
18569 Debugger entered--beginning evaluation of function call form:
18570 * (let ((total 0)) (while (> number 0) (setq total ...)
18571 (setq number ...)) total)
18572 * triangle-bugged(5)
18573 eval((triangle-bugged 5))
18576 eval-last-sexp-1(nil)
18577 eval-last-sexp(nil)
18578 call-interactively(eval-last-sexp)
18579 ---------- Buffer: *Backtrace* ----------
18584 Now, type @kbd{d} again, eight times, slowly. Each time you type
18585 @kbd{d}, Emacs will evaluate another expression in the function
18589 Eventually, the buffer will look like this:
18593 ---------- Buffer: *Backtrace* ----------
18594 Debugger entered--beginning evaluation of function call form:
18595 * (setq number (1= number))
18596 * (while (> number 0) (setq total (+ total number))
18597 (setq number (1= number)))
18600 * (let ((total 0)) (while (> number 0) (setq total ...)
18601 (setq number ...)) total)
18602 * triangle-bugged(5)
18603 eval((triangle-bugged 5))
18606 eval-last-sexp-1(nil)
18607 eval-last-sexp(nil)
18608 call-interactively(eval-last-sexp)
18609 ---------- Buffer: *Backtrace* ----------
18615 Finally, after you type @kbd{d} two more times, Emacs will reach the
18616 error, and the top two lines of the @file{*Backtrace*} buffer will look
18621 ---------- Buffer: *Backtrace* ----------
18622 Debugger entered--Lisp error: (void-function 1=)
18625 ---------- Buffer: *Backtrace* ----------
18629 By typing @kbd{d}, you were able to step through the function.
18631 You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this
18632 quits the trace, but does not cancel @code{debug-on-entry}.
18634 @findex cancel-debug-on-entry
18635 To cancel the effect of @code{debug-on-entry}, call
18636 @code{cancel-debug-on-entry} and the name of the function, like this:
18639 M-x cancel-debug-on-entry RET triangle-bugged RET
18643 (If you are reading this in Info, cancel @code{debug-on-entry} now.)
18645 @node debug-on-quit, edebug, debug-on-entry, Debugging
18646 @section @code{debug-on-quit} and @code{(debug)}
18648 In addition to setting @code{debug-on-error} or calling @code{debug-on-entry},
18649 there are two other ways to start @code{debug}.
18651 @findex debug-on-quit
18652 You can start @code{debug} whenever you type @kbd{C-g}
18653 (@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to
18654 @code{t}. This is useful for debugging infinite loops.
18657 @cindex @code{(debug)} in code
18658 Or, you can insert a line that says @code{(debug)} into your code
18659 where you want the debugger to start, like this:
18663 (defun triangle-bugged (number)
18664 "Return sum of numbers 1 through NUMBER inclusive."
18666 (while (> number 0)
18667 (setq total (+ total number))
18668 (debug) ; @r{Start debugger.}
18669 (setq number (1= number))) ; @r{Error here.}
18674 The @code{debug} function is described in detail in @ref{Debugger, ,
18675 The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}.
18677 @node edebug, Debugging Exercises, debug-on-quit, Debugging
18678 @section The @code{edebug} Source Level Debugger
18679 @cindex Source level debugger
18682 Edebug is a source level debugger. Edebug normally displays the
18683 source of the code you are debugging, with an arrow at the left that
18684 shows which line you are currently executing.
18686 You can walk through the execution of a function, line by line, or run
18687 quickly until reaching a @dfn{breakpoint} where execution stops.
18689 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
18690 Lisp Reference Manual}.
18693 Here is a bugged function definition for @code{triangle-recursively}.
18694 @xref{Recursive triangle function, , Recursion in place of a counter},
18695 for a review of it.
18699 (defun triangle-recursively-bugged (number)
18700 "Return sum of numbers 1 through NUMBER inclusive.
18705 (triangle-recursively-bugged
18706 (1= number))))) ; @r{Error here.}
18711 Normally, you would install this definition by positioning your cursor
18712 after the function's closing parenthesis and typing @kbd{C-x C-e}
18713 (@code{eval-last-sexp}) or else by positioning your cursor within the
18714 definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default,
18715 the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp
18719 However, to prepare this function definition for Edebug, you must
18720 first @dfn{instrument} the code using a different command. You can do
18721 this by positioning your cursor within or just after the definition
18725 M-x edebug-defun RET
18729 This will cause Emacs to load Edebug automatically if it is not
18730 already loaded, and properly instrument the function.
18732 After instrumenting the function, place your cursor after the
18733 following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}):
18736 (triangle-recursively-bugged 3)
18740 You will be jumped back to the source for
18741 @code{triangle-recursively-bugged} and the cursor positioned at the
18742 beginning of the @code{if} line of the function. Also, you will see
18743 an arrowhead at the left hand side of that line. The arrowhead marks
18744 the line where the function is executing. (In the following examples,
18745 we show the arrowhead with @samp{=>}; in a windowing system, you may
18746 see the arrowhead as a solid triangle in the window `fringe'.)
18749 =>@point{}(if (= number 1)
18754 In the example, the location of point is displayed with a star,
18755 @samp{@point{}} (in Info, it is displayed as @samp{-!-}).
18758 In the example, the location of point is displayed as @samp{@point{}}
18759 (in a printed book, it is displayed with a five pointed star).
18762 If you now press @key{SPC}, point will move to the next expression to
18763 be executed; the line will look like this:
18766 =>(if @point{}(= number 1)
18770 As you continue to press @key{SPC}, point will move from expression to
18771 expression. At the same time, whenever an expression returns a value,
18772 that value will be displayed in the echo area. For example, after you
18773 move point past @code{number}, you will see the following:
18776 Result: 3 (#o3, #x3, ?\C-c)
18780 This means the value of @code{number} is 3, which is octal three,
18781 hexadecimal three, and @sc{ascii} `control-c' (the third letter of the
18782 alphabet, in case you need to know this information).
18784 You can continue moving through the code until you reach the line with
18785 the error. Before evaluation, that line looks like this:
18788 => @point{}(1= number))))) ; @r{Error here.}
18793 When you press @key{SPC} once again, you will produce an error message
18797 Symbol's function definition is void:@: 1=
18803 Press @kbd{q} to quit Edebug.
18805 To remove instrumentation from a function definition, simply
18806 re-evaluate it with a command that does not instrument it.
18807 For example, you could place your cursor after the definition's
18808 closing parenthesis and type @kbd{C-x C-e}.
18810 Edebug does a great deal more than walk with you through a function.
18811 You can set it so it races through on its own, stopping only at an
18812 error or at specified stopping points; you can cause it to display the
18813 changing values of various expressions; you can find out how many
18814 times a function is called, and more.
18816 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
18817 Lisp Reference Manual}.
18820 @node Debugging Exercises, , edebug, Debugging
18821 @section Debugging Exercises
18825 Install the @code{count-words-region} function and then cause it to
18826 enter the built-in debugger when you call it. Run the command on a
18827 region containing two words. You will need to press @kbd{d} a
18828 remarkable number of times. On your system, is a `hook' called after
18829 the command finishes? (For information on hooks, see @ref{Command
18830 Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference
18834 Copy @code{count-words-region} into the @file{*scratch*} buffer,
18835 instrument the function for Edebug, and walk through its execution.
18836 The function does not need to have a bug, although you can introduce
18837 one if you wish. If the function lacks a bug, the walk-through
18838 completes without problems.
18841 While running Edebug, type @kbd{?} to see a list of all the Edebug commands.
18842 (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@:
18843 @kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix
18844 for commands made outside of the Edebug debugging buffer.)
18847 In the Edebug debugging buffer, use the @kbd{p}
18848 (@code{edebug-bounce-point}) command to see where in the region the
18849 @code{count-words-region} is working.
18852 Move point to some spot further down the function and then type the
18853 @kbd{h} (@code{edebug-goto-here}) command to jump to that location.
18856 Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to
18857 walk through the function on its own; use an upper case @kbd{T} for
18858 @code{edebug-Trace-fast-mode}.
18861 Set a breakpoint, then run Edebug in Trace mode until it reaches the
18865 @node Conclusion, the-the, Debugging, Top
18866 @chapter Conclusion
18868 We have now reached the end of this Introduction. You have now
18869 learned enough about programming in Emacs Lisp to set values, to write
18870 simple @file{.emacs} files for yourself and your friends, and write
18871 simple customizations and extensions to Emacs.
18873 This is a place to stop. Or, if you wish, you can now go onward, and
18876 You have learned some of the basic nuts and bolts of programming. But
18877 only some. There are a great many more brackets and hinges that are
18878 easy to use that we have not touched.
18880 A path you can follow right now lies among the sources to GNU Emacs
18883 @cite{The GNU Emacs Lisp Reference Manual}.
18886 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
18887 Emacs Lisp Reference Manual}.
18890 The Emacs Lisp sources are an adventure. When you read the sources and
18891 come across a function or expression that is unfamiliar, you need to
18892 figure out or find out what it does.
18894 Go to the Reference Manual. It is a thorough, complete, and fairly
18895 easy-to-read description of Emacs Lisp. It is written not only for
18896 experts, but for people who know what you know. (The @cite{Reference
18897 Manual} comes with the standard GNU Emacs distribution. Like this
18898 introduction, it comes as a Texinfo source file, so you can read it
18899 on-line and as a typeset, printed book.)
18901 Go to the other on-line help that is part of GNU Emacs: the on-line
18902 documentation for all functions and variables, and @code{find-tags},
18903 the program that takes you to sources.
18905 Here is an example of how I explore the sources. Because of its name,
18906 @file{simple.el} is the file I looked at first, a long time ago. As
18907 it happens some of the functions in @file{simple.el} are complicated,
18908 or at least look complicated at first sight. The @code{open-line}
18909 function, for example, looks complicated.
18911 You may want to walk through this function slowly, as we did with the
18912 @code{forward-sentence} function. (@xref{forward-sentence, The
18913 @code{forward-sentence} function}.) Or you may want to skip that
18914 function and look at another, such as @code{split-line}. You don't
18915 need to read all the functions. According to
18916 @code{count-words-in-defun}, the @code{split-line} function contains
18917 102 words and symbols.
18919 Even though it is short, @code{split-line} contains expressions
18920 we have not studied: @code{skip-chars-forward}, @code{indent-to},
18921 @code{current-column} and @code{insert-and-inherit}.
18923 Consider the @code{skip-chars-forward} function. (It is part of the
18924 function definition for @code{back-to-indentation}, which is shown in
18925 @ref{Review, , Review}.)
18927 In GNU Emacs, you can find out more about @code{skip-chars-forward} by
18928 typing @kbd{C-h f} (@code{describe-function}) and the name of the
18929 function. This gives you the function documentation.
18931 You may be able to guess what is done by a well named function such as
18932 @code{indent-to}; or you can look it up, too. Incidentally, the
18933 @code{describe-function} function itself is in @file{help.el}; it is
18934 one of those long, but decipherable functions. You can look up
18935 @code{describe-function} using the @kbd{C-h f} command!
18937 In this instance, since the code is Lisp, the @file{*Help*} buffer
18938 contains the name of the library containing the function's source.
18939 You can put point over the name of the library and press the RET key,
18940 which in this situation is bound to @code{help-follow}, and be taken
18941 directly to the source, in the same way as @kbd{M-.}
18944 The definition for @code{describe-function} illustrates how to
18945 customize the @code{interactive} expression without using the standard
18946 character codes; and it shows how to create a temporary buffer.
18948 (The @code{indent-to} function is written in C rather than Emacs Lisp;
18949 it is a `built-in' function. @code{help-follow} takes you to its
18950 source as does @code{find-tag}, when properly set up.)
18952 You can look at a function's source using @code{find-tag}, which is
18953 bound to @kbd{M-.} Finally, you can find out what the Reference
18954 Manual has to say by visiting the manual in Info, and typing @kbd{i}
18955 (@code{Info-index}) and the name of the function, or by looking up the
18956 function in the index to a printed copy of the manual.
18958 Similarly, you can find out what is meant by
18959 @code{insert-and-inherit}.
18961 Other interesting source files include @file{paragraphs.el},
18962 @file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el}
18963 file includes short, easily understood functions as well as longer
18964 ones. The @file{loaddefs.el} file contains the many standard
18965 autoloads and many keymaps. I have never looked at it all; only at
18966 parts. @file{loadup.el} is the file that loads the standard parts of
18967 Emacs; it tells you a great deal about how Emacs is built.
18968 (@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
18969 Reference Manual}, for more about building.)
18971 As I said, you have learned some nuts and bolts; however, and very
18972 importantly, we have hardly touched major aspects of programming; I
18973 have said nothing about how to sort information, except to use the
18974 predefined @code{sort} function; I have said nothing about how to store
18975 information, except to use variables and lists; I have said nothing
18976 about how to write programs that write programs. These are topics for
18977 another, and different kind of book, a different kind of learning.
18979 What you have done is learn enough for much practical work with GNU
18980 Emacs. What you have done is get started. This is the end of a
18983 @c ================ Appendix ================
18985 @node the-the, Kill Ring, Conclusion, Top
18986 @appendix The @code{the-the} Function
18988 @cindex Duplicated words function
18989 @cindex Words, duplicated
18991 Sometimes when you you write text, you duplicate words---as with ``you
18992 you'' near the beginning of this sentence. I find that most
18993 frequently, I duplicate ``the''; hence, I call the function for
18994 detecting duplicated words, @code{the-the}.
18997 As a first step, you could use the following regular expression to
18998 search for duplicates:
19001 \\(\\w+[ \t\n]+\\)\\1
19005 This regexp matches one or more word-constituent characters followed
19006 by one or more spaces, tabs, or newlines. However, it does not detect
19007 duplicated words on different lines, since the ending of the first
19008 word, the end of the line, is different from the ending of the second
19009 word, a space. (For more information about regular expressions, see
19010 @ref{Regexp Search, , Regular Expression Searches}, as well as
19011 @ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
19012 Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp,
19013 The GNU Emacs Lisp Reference Manual}.)
19015 You might try searching just for duplicated word-constituent
19016 characters but that does not work since the pattern detects doubles
19017 such as the two occurrences of `th' in `with the'.
19019 Another possible regexp searches for word-constituent characters
19020 followed by non-word-constituent characters, reduplicated. Here,
19021 @w{@samp{\\w+}} matches one or more word-constituent characters and
19022 @w{@samp{\\W*}} matches zero or more non-word-constituent characters.
19025 \\(\\(\\w+\\)\\W*\\)\\1
19031 Here is the pattern that I use. It is not perfect, but good enough.
19032 @w{@samp{\\b}} matches the empty string, provided it is at the beginning
19033 or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of
19034 any characters that are @emph{not} an @@-sign, space, newline, or tab.
19037 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
19040 One can write more complicated expressions, but I found that this
19041 expression is good enough, so I use it.
19043 Here is the @code{the-the} function, as I include it in my
19044 @file{.emacs} file, along with a handy global key binding:
19049 "Search forward for for a duplicated word."
19051 (message "Searching for for duplicated words ...")
19055 ;; This regexp is not perfect
19056 ;; but is fairly good over all:
19057 (if (re-search-forward
19058 "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move)
19059 (message "Found duplicated word.")
19060 (message "End of buffer")))
19064 ;; Bind `the-the' to C-c \
19065 (global-set-key "\C-c\\" 'the-the)
19074 one two two three four five
19079 You can substitute the other regular expressions shown above in the
19080 function definition and try each of them on this list.
19082 @node Kill Ring, Full Graph, the-the, Top
19083 @appendix Handling the Kill Ring
19084 @cindex Kill ring handling
19085 @cindex Handling the kill ring
19086 @cindex Ring, making a list like a
19088 The kill ring is a list that is transformed into a ring by the
19089 workings of the @code{current-kill} function. The @code{yank} and
19090 @code{yank-pop} commands use the @code{current-kill} function.
19092 This appendix describes the @code{current-kill} function as well as
19093 both the @code{yank} and the @code{yank-pop} commands, but first,
19094 consider the workings of the kill ring.
19097 The kill ring has a default maximum length of sixty items; this number
19098 is too large for an explanation. Instead, set it to four. Please
19099 evaluate the following:
19103 (setq old-kill-ring-max kill-ring-max)
19104 (setq kill-ring-max 4)
19109 Then, please copy each line of the following indented example into the
19110 kill ring. You may kill each line with @kbd{C-k} or mark it and copy
19114 (In a read-only buffer, such as the @file{*info*} buffer, the kill
19115 command, @kbd{C-k} (@code{kill-line}), will not remove the text,
19116 merely copy it to the kill ring. However, your machine may beep at
19117 you. Alternatively, for silence, you may copy the region of each line
19118 with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark
19119 each line for this command to succeed, but it does not matter at which
19120 end you put point or mark.)
19124 Please invoke the calls in order, so that five elements attempt to
19125 fill the kill ring:
19130 second piece of text
19132 fourth line of text
19139 Then find the value of @code{kill-ring} by evaluating
19151 ("fifth bit of text" "fourth line of text"
19152 "third line" "second piece of text")
19157 The first element, @samp{first some text}, was dropped.
19160 To return to the old value for the length of the kill ring, evaluate:
19163 (setq kill-ring-max old-kill-ring-max)
19173 @node current-kill, yank, Kill Ring, Kill Ring
19174 @comment node-name, next, previous, up
19175 @appendixsec The @code{current-kill} Function
19176 @findex current-kill
19178 The @code{current-kill} function changes the element in the kill ring
19179 to which @code{kill-ring-yank-pointer} points. (Also, the
19180 @code{kill-new} function sets @code{kill-ring-yank-pointer} to point
19181 to the latest element of the the kill ring. The @code{kill-new}
19182 function is used directly or indirectly by @code{kill-append},
19183 @code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line},
19184 and @code{kill-region}.)
19187 The @code{current-kill} function is used by @code{yank} and by
19188 @code{yank-pop}. Here is the code for @code{current-kill}:
19192 (defun current-kill (n &optional do-not-move)
19193 "Rotate the yanking point by N places, and then return that kill.
19194 If N is zero, `interprogram-paste-function' is set, and calling it
19195 returns a string, then that string is added to the front of the
19196 kill ring and returned as the latest kill.
19199 If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
19200 yanking point; just return the Nth kill forward."
19201 (let ((interprogram-paste (and (= n 0)
19202 interprogram-paste-function
19203 (funcall interprogram-paste-function))))
19206 (if interprogram-paste
19208 ;; Disable the interprogram cut function when we add the new
19209 ;; text to the kill ring, so Emacs doesn't try to own the
19210 ;; selection, with identical text.
19211 (let ((interprogram-cut-function nil))
19212 (kill-new interprogram-paste))
19213 interprogram-paste)
19216 (or kill-ring (error "Kill ring is empty"))
19217 (let ((ARGth-kill-element
19218 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19219 (length kill-ring))
19222 (setq kill-ring-yank-pointer ARGth-kill-element))
19223 (car ARGth-kill-element)))))
19227 Remember also that the @code{kill-new} function sets
19228 @code{kill-ring-yank-pointer} to the latest element of the the kill
19229 ring, which means that all the functions that call it set the value
19230 indirectly: @code{kill-append}, @code{copy-region-as-kill},
19231 @code{kill-ring-save}, @code{kill-line}, and @code{kill-region}.
19234 Here is the line in @code{kill-new}, which is explained in
19235 @ref{kill-new function, , The @code{kill-new} function}.
19238 (setq kill-ring-yank-pointer kill-ring)
19242 * Understanding current-kill::
19245 @node Understanding current-kill, , current-kill, current-kill
19247 @unnumberedsubsec @code{current-kill} in Outline
19250 The @code{current-kill} function looks complex, but as usual, it can
19251 be understood by taking it apart piece by piece. First look at it in
19256 (defun current-kill (n &optional do-not-move)
19257 "Rotate the yanking point by N places, and then return that kill."
19263 This function takes two arguments, one of which is optional. It has a
19264 documentation string. It is @emph{not} interactive.
19266 The body of the function definition is a @code{let} expression, which
19267 itself has a body as well as a @var{varlist}.
19269 The @code{let} expression declares a variable that will be only usable
19270 within the bounds of this function. This variable is called
19271 @code{interprogram-paste} and is for copying to another program. It
19272 is not for copying within this instance of GNU Emacs. Most window
19273 systems provide a facility for interprogram pasting. Sadly, that
19274 facility usually provides only for the last element. Most windowing
19275 systems have not adopted a ring of many possibilities, even though
19276 Emacs has provided it for decades.
19278 The @code{if} expression has two parts, one if there exists
19279 @code{interprogram-paste} and one if not.
19282 Let us consider the `if not' or else-part of the @code{current-kill}
19283 function. (The then-part uses the the @code{kill-new} function, which
19284 we have already described. @xref{kill-new function, , The
19285 @code{kill-new} function}.)
19289 (or kill-ring (error "Kill ring is empty"))
19290 (let ((ARGth-kill-element
19291 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19292 (length kill-ring))
19295 (setq kill-ring-yank-pointer ARGth-kill-element))
19296 (car ARGth-kill-element))
19301 The code first checks whether the kill ring has content; otherwise it
19305 Note that the @code{or} expression is very similar to testing length
19312 (if (zerop (length kill-ring)) ; @r{if-part}
19313 (error "Kill ring is empty")) ; @r{then-part}
19319 If there is not anything in the kill ring, its length must be zero and
19320 an error message sent to the user: @samp{Kill ring is empty}. The
19321 @code{current-kill} function uses an @code{or} expression which is
19322 simpler. But an @code{if} expression reminds us what goes on.
19324 This @code{if} expression uses the function @code{zerop} which returns
19325 true if the value it is testing is zero. When @code{zerop} tests
19326 true, the then-part of the @code{if} is evaluated. The then-part is a
19327 list starting with the function @code{error}, which is a function that
19328 is similar to the @code{message} function
19329 (@pxref{message, , The @code{message} Function}) in that
19330 it prints a one-line message in the echo area. However, in addition
19331 to printing a message, @code{error} also stops evaluation of the
19332 function within which it is embedded. This means that the rest of the
19333 function will not be evaluated if the length of the kill ring is zero.
19335 Then the @code{current-kill} function selects the element to return.
19336 The selection depends on the number of places that @code{current-kill}
19337 rotates and on where @code{kill-ring-yank-pointer} points.
19339 Next, either the optional @code{do-not-move} argument is true or the
19340 current value of @code{kill-ring-yank-pointer} is set to point to the
19341 list. Finally, another expression returns the first element of the
19342 list even if the @code{do-not-move} argument is true.
19345 * Digression concerning error::
19346 * Determining the Element ::
19349 @node Digression concerning error, Determining the Element , Understanding current-kill, Understanding current-kill
19351 @unnumberedsubsubsec Digression about the word `error'
19354 In my opinion, it is slightly misleading, at least to humans, to use
19355 the term `error' as the name of the @code{error} function. A better
19356 term would be `cancel'. Strictly speaking, of course, you cannot
19357 point to, much less rotate a pointer to a list that has no length, so
19358 from the point of view of the computer, the word `error' is correct.
19359 But a human expects to attempt this sort of thing, if only to find out
19360 whether the kill ring is full or empty. This is an act of
19363 From the human point of view, the act of exploration and discovery is
19364 not necessarily an error, and therefore should not be labelled as one,
19365 even in the bowels of a computer. As it is, the code in Emacs implies
19366 that a human who is acting virtuously, by exploring his or her
19367 environment, is making an error. This is bad. Even though the computer
19368 takes the same steps as it does when there is an `error', a term such as
19369 `cancel' would have a clearer connotation.
19371 @node Determining the Element , , Digression concerning error, Understanding current-kill
19373 @unnumberedsubsubsec Determining the Element
19376 Among other actions, the else-part of the @code{if} expression sets
19377 the value of @code{kill-ring-yank-pointer} to
19378 @code{ARGth-kill-element} when the kill ring has something in it and
19379 the value of @code{do-not-move} is @code{nil}.
19382 The code looks like this:
19386 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19387 (length kill-ring))
19392 This needs some examination. Unless it is not supposed to move the
19393 pointer, the @code{current-kill} function changes where
19394 @code{kill-ring-yank-pointer} points.
19396 @w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}}
19397 expression does. Also, clearly, @code{ARGth-kill-element} is being
19398 set to be equal to some @sc{cdr} of the kill ring, using the
19399 @code{nthcdr} function that is described in an earlier section.
19400 (@xref{copy-region-as-kill}.) How does it do this?
19402 As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function
19403 works by repeatedly taking the @sc{cdr} of a list---it takes the
19404 @sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{}
19407 The two following expressions produce the same result:
19411 (setq kill-ring-yank-pointer (cdr kill-ring))
19413 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
19417 However, the @code{nthcdr} expression is more complicated. It uses
19418 the @code{mod} function to determine which @sc{cdr} to select.
19420 (You will remember to look at inner functions first; indeed, we will
19421 have to go inside the @code{mod}.)
19423 The @code{mod} function returns the value of its first argument modulo
19424 the second; that is to say, it returns the remainder after dividing
19425 the first argument by the second. The value returned has the same
19426 sign as the second argument.
19434 @result{} 0 ;; @r{because there is no remainder}
19441 In this case, the first argument is often smaller than the second.
19453 We can guess what the @code{-} function does. It is like @code{+} but
19454 subtracts instead of adds; the @code{-} function subtracts its second
19455 argument from its first. Also, we already know what the @code{length}
19456 function does (@pxref{length}). It returns the length of a list.
19458 And @code{n} is the name of the required argument to the
19459 @code{current-kill} function.
19462 So when the first argument to @code{nthcdr} is zero, the @code{nthcdr}
19463 expression returns the whole list, as you can see by evaluating the
19468 ;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four}
19469 ;; @r{and} (mod (- 0 4) 4) @result{} 0
19470 (nthcdr (mod (- 0 4) 4)
19471 '("fourth line of text"
19473 "second piece of text"
19474 "first some text"))
19479 When the first argument to the @code{current-kill} function is one,
19480 the @code{nthcdr} expression returns the list without its first
19485 (nthcdr (mod (- 1 4) 4)
19486 '("fourth line of text"
19488 "second piece of text"
19489 "first some text"))
19493 @cindex @samp{global variable} defined
19494 @cindex @samp{variable, global}, defined
19495 Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer}
19496 are @dfn{global variables}. That means that any expression in Emacs
19497 Lisp can access them. They are not like the local variables set by
19498 @code{let} or like the symbols in an argument list.
19499 Local variables can only be accessed
19500 within the @code{let} that defines them or the function that specifies
19501 them in an argument list (and within expressions called by them).
19504 @c texi2dvi fails when the name of the section is within ifnottex ...
19505 (@xref{Prevent confusion, , @code{let} Prevents Confusion}, and
19506 @ref{defun, , The @code{defun} Special Form}.)
19509 @node yank, yank-pop, current-kill, Kill Ring
19510 @comment node-name, next, previous, up
19511 @appendixsec @code{yank}
19514 After learning about @code{current-kill}, the code for the
19515 @code{yank} function is almost easy.
19517 The @code{yank} function does not use the
19518 @code{kill-ring-yank-pointer} variable directly. It calls
19519 @code{insert-for-yank} which calls @code{current-kill} which sets the
19520 @code{kill-ring-yank-pointer} variable.
19523 The code looks like this:
19528 (defun yank (&optional arg)
19529 "Reinsert (\"paste\") the last stretch of killed text.
19530 More precisely, reinsert the stretch of killed text most recently
19531 killed OR yanked. Put point at end, and set mark at beginning.
19532 With just \\[universal-argument] as argument, same but put point at
19533 beginning (and mark at end). With argument N, reinsert the Nth most
19534 recently killed stretch of killed text.
19536 When this command inserts killed text into the buffer, it honors
19537 `yank-excluded-properties' and `yank-handler' as described in the
19538 doc string for `insert-for-yank-1', which see.
19540 See also the command \\[yank-pop]."
19544 (setq yank-window-start (window-start))
19545 ;; If we don't get all the way thru, make last-command indicate that
19546 ;; for the following command.
19547 (setq this-command t)
19548 (push-mark (point))
19551 (insert-for-yank (current-kill (cond
19556 ;; This is like exchange-point-and-mark,
19557 ;; but doesn't activate the mark.
19558 ;; It is cleaner to avoid activation, even though the command
19559 ;; loop would deactivate the mark because we inserted text.
19560 (goto-char (prog1 (mark t)
19561 (set-marker (mark-marker) (point) (current-buffer)))))
19564 ;; If we do get all the way thru, make this-command indicate that.
19565 (if (eq this-command t)
19566 (setq this-command 'yank))
19571 The key expression is @code{insert-for-yank}, which inserts the string
19572 returned by @code{current-kill}, but removes some text properties from
19575 However, before getting to that expression, the function sets the value
19576 of @code{yank-window-start} to the position returned by the
19577 @code{(window-start)} expression, the position at which the display
19578 currently starts. The @code{yank} function also sets
19579 @code{this-command} and pushes the mark.
19581 After it yanks the appropriate element, if the optional argument is a
19582 @sc{cons} rather than a number or nothing, it puts point at beginning
19583 of the yanked text and mark at its end.
19585 (The @code{prog1} function is like @code{progn} but returns the value
19586 of its first argument rather than the value of its last argument. Its
19587 first argument is forced to return the buffer's mark as an integer.
19588 You can see the documentation for these functions by placing point
19589 over them in this buffer and then typing @kbd{C-h f}
19590 (@code{describe-function}) followed by a @kbd{RET}; the default is the
19593 The last part of the function tells what to do when it succeeds.
19595 @node yank-pop, ring file, yank, Kill Ring
19596 @comment node-name, next, previous, up
19597 @appendixsec @code{yank-pop}
19600 After understanding @code{yank} and @code{current-kill}, you know how
19601 to approach the @code{yank-pop} function. Leaving out the
19602 documentation to save space, it looks like this:
19607 (defun yank-pop (&optional arg)
19610 (if (not (eq last-command 'yank))
19611 (error "Previous command was not a yank"))
19614 (setq this-command 'yank)
19615 (unless arg (setq arg 1))
19616 (let ((inhibit-read-only t)
19617 (before (< (point) (mark t))))
19621 (funcall (or yank-undo-function 'delete-region) (point) (mark t))
19622 (funcall (or yank-undo-function 'delete-region) (mark t) (point)))
19623 (setq yank-undo-function nil)
19626 (set-marker (mark-marker) (point) (current-buffer))
19627 (insert-for-yank (current-kill arg))
19628 ;; Set the window start back where it was in the yank command,
19630 (set-window-start (selected-window) yank-window-start t)
19634 ;; This is like exchange-point-and-mark,
19635 ;; but doesn't activate the mark.
19636 ;; It is cleaner to avoid activation, even though the command
19637 ;; loop would deactivate the mark because we inserted text.
19638 (goto-char (prog1 (mark t)
19639 (set-marker (mark-marker)
19641 (current-buffer))))))
19646 The function is interactive with a small @samp{p} so the prefix
19647 argument is processed and passed to the function. The command can
19648 only be used after a previous yank; otherwise an error message is
19649 sent. This check uses the variable @code{last-command} which is set
19650 by @code{yank} and is discussed elsewhere.
19651 (@xref{copy-region-as-kill}.)
19653 The @code{let} clause sets the variable @code{before} to true or false
19654 depending whether point is before or after mark and then the region
19655 between point and mark is deleted. This is the region that was just
19656 inserted by the previous yank and it is this text that will be
19659 @code{funcall} calls its first argument as a function, passing
19660 remaining arguments to it. The first argument is whatever the
19661 @code{or} expression returns. The two remaining arguments are the
19662 positions of point and mark set by the preceding @code{yank} command.
19664 There is more, but that is the hardest part.
19666 @node ring file, , yank-pop, Kill Ring
19667 @comment node-name, next, previous, up
19668 @appendixsec The @file{ring.el} File
19669 @cindex @file{ring.el} file
19671 Interestingly, GNU Emacs posses a file called @file{ring.el} that
19672 provides many of the features we just discussed. But functions such
19673 as @code{kill-ring-yank-pointer} do not use this library, possibly
19674 because they were written earlier.
19676 @node Full Graph, Free Software and Free Manuals, Kill Ring, Top
19677 @appendix A Graph with Labelled Axes
19679 Printed axes help you understand a graph. They convey scale. In an
19680 earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we
19681 wrote the code to print the body of a graph. Here we write the code
19682 for printing and labelling vertical and horizontal axes, along with the
19686 * Labelled Example::
19687 * print-graph Varlist::
19690 * Print Whole Graph::
19693 @node Labelled Example, print-graph Varlist, Full Graph, Full Graph
19695 @unnumberedsec Labelled Example Graph
19698 Since insertions fill a buffer to the right and below point, the new
19699 graph printing function should first print the Y or vertical axis,
19700 then the body of the graph, and finally the X or horizontal axis.
19701 This sequence lays out for us the contents of the function:
19711 Print body of graph.
19718 Here is an example of how a finished graph should look:
19731 1 - ****************
19738 In this graph, both the vertical and the horizontal axes are labelled
19739 with numbers. However, in some graphs, the horizontal axis is time
19740 and would be better labelled with months, like this:
19754 Indeed, with a little thought, we can easily come up with a variety of
19755 vertical and horizontal labelling schemes. Our task could become
19756 complicated. But complications breed confusion. Rather than permit
19757 this, it is better choose a simple labelling scheme for our first
19758 effort, and to modify or replace it later.
19761 These considerations suggest the following outline for the
19762 @code{print-graph} function:
19766 (defun print-graph (numbers-list)
19767 "@var{documentation}@dots{}"
19768 (let ((height @dots{}
19772 (print-Y-axis height @dots{} )
19773 (graph-body-print numbers-list)
19774 (print-X-axis @dots{} )))
19778 We can work on each part of the @code{print-graph} function definition
19781 @node print-graph Varlist, print-Y-axis, Labelled Example, Full Graph
19782 @comment node-name, next, previous, up
19783 @appendixsec The @code{print-graph} Varlist
19784 @cindex @code{print-graph} varlist
19786 In writing the @code{print-graph} function, the first task is to write
19787 the varlist in the @code{let} expression. (We will leave aside for the
19788 moment any thoughts about making the function interactive or about the
19789 contents of its documentation string.)
19791 The varlist should set several values. Clearly, the top of the label
19792 for the vertical axis must be at least the height of the graph, which
19793 means that we must obtain this information here. Note that the
19794 @code{print-graph-body} function also requires this information. There
19795 is no reason to calculate the height of the graph in two different
19796 places, so we should change @code{print-graph-body} from the way we
19797 defined it earlier to take advantage of the calculation.
19799 Similarly, both the function for printing the X axis labels and the
19800 @code{print-graph-body} function need to learn the value of the width of
19801 each symbol. We can perform the calculation here and change the
19802 definition for @code{print-graph-body} from the way we defined it in the
19805 The length of the label for the horizontal axis must be at least as long
19806 as the graph. However, this information is used only in the function
19807 that prints the horizontal axis, so it does not need to be calculated here.
19809 These thoughts lead us directly to the following form for the varlist
19810 in the @code{let} for @code{print-graph}:
19814 (let ((height (apply 'max numbers-list)) ; @r{First version.}
19815 (symbol-width (length graph-blank)))
19820 As we shall see, this expression is not quite right.
19823 @node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph
19824 @comment node-name, next, previous, up
19825 @appendixsec The @code{print-Y-axis} Function
19826 @cindex Axis, print vertical
19827 @cindex Y axis printing
19828 @cindex Vertical axis printing
19829 @cindex Print vertical axis
19831 The job of the @code{print-Y-axis} function is to print a label for
19832 the vertical axis that looks like this:
19850 The function should be passed the height of the graph, and then should
19851 construct and insert the appropriate numbers and marks.
19853 It is easy enough to see in the figure what the Y axis label should
19854 look like; but to say in words, and then to write a function
19855 definition to do the job is another matter. It is not quite true to
19856 say that we want a number and a tic every five lines: there are only
19857 three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4),
19858 but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8,
19859 and 9). It is better to say that we want a number and a tic mark on
19860 the base line (number 1) and then that we want a number and a tic on
19861 the fifth line from the bottom and on every line that is a multiple of
19865 * Height of label::
19866 * Compute a Remainder::
19869 * print-Y-axis Penultimate::
19872 @node Height of label, Compute a Remainder, print-Y-axis, print-Y-axis
19874 @unnumberedsubsec What height should the label be?
19877 The next issue is what height the label should be? Suppose the maximum
19878 height of tallest column of the graph is seven. Should the highest
19879 label on the Y axis be @samp{5 -}, and should the graph stick up above
19880 the label? Or should the highest label be @samp{7 -}, and mark the peak
19881 of the graph? Or should the highest label be @code{10 -}, which is a
19882 multiple of five, and be higher than the topmost value of the graph?
19884 The latter form is preferred. Most graphs are drawn within rectangles
19885 whose sides are an integral number of steps long---5, 10, 15, and so
19886 on for a step distance of five. But as soon as we decide to use a
19887 step height for the vertical axis, we discover that the simple
19888 expression in the varlist for computing the height is wrong. The
19889 expression is @code{(apply 'max numbers-list)}. This returns the
19890 precise height, not the maximum height plus whatever is necessary to
19891 round up to the nearest multiple of five. A more complex expression
19894 As usual in cases like this, a complex problem becomes simpler if it is
19895 divided into several smaller problems.
19897 First, consider the case when the highest value of the graph is an
19898 integral multiple of five---when it is 5, 10, 15, or some higher
19899 multiple of five. We can use this value as the Y axis height.
19901 A fairly simply way to determine whether a number is a multiple of
19902 five is to divide it by five and see if the division results in a
19903 remainder. If there is no remainder, the number is a multiple of
19904 five. Thus, seven divided by five has a remainder of two, and seven
19905 is not an integral multiple of five. Put in slightly different
19906 language, more reminiscent of the classroom, five goes into seven
19907 once, with a remainder of two. However, five goes into ten twice,
19908 with no remainder: ten is an integral multiple of five.
19910 @node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis
19911 @appendixsubsec Side Trip: Compute a Remainder
19913 @findex % @r{(remainder function)}
19914 @cindex Remainder function, @code{%}
19915 In Lisp, the function for computing a remainder is @code{%}. The
19916 function returns the remainder of its first argument divided by its
19917 second argument. As it happens, @code{%} is a function in Emacs Lisp
19918 that you cannot discover using @code{apropos}: you find nothing if you
19919 type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to
19920 learn of the existence of @code{%} is to read about it in a book such
19921 as this or in the Emacs Lisp sources.
19923 You can try the @code{%} function by evaluating the following two
19935 The first expression returns 2 and the second expression returns 0.
19937 To test whether the returned value is zero or some other number, we
19938 can use the @code{zerop} function. This function returns @code{t} if
19939 its argument, which must be a number, is zero.
19951 Thus, the following expression will return @code{t} if the height
19952 of the graph is evenly divisible by five:
19955 (zerop (% height 5))
19959 (The value of @code{height}, of course, can be found from @code{(apply
19960 'max numbers-list)}.)
19962 On the other hand, if the value of @code{height} is not a multiple of
19963 five, we want to reset the value to the next higher multiple of five.
19964 This is straightforward arithmetic using functions with which we are
19965 already familiar. First, we divide the value of @code{height} by five
19966 to determine how many times five goes into the number. Thus, five
19967 goes into twelve twice. If we add one to this quotient and multiply by
19968 five, we will obtain the value of the next multiple of five that is
19969 larger than the height. Five goes into twelve twice. Add one to two,
19970 and multiply by five; the result is fifteen, which is the next multiple
19971 of five that is higher than twelve. The Lisp expression for this is:
19974 (* (1+ (/ height 5)) 5)
19978 For example, if you evaluate the following, the result is 15:
19981 (* (1+ (/ 12 5)) 5)
19984 All through this discussion, we have been using `five' as the value
19985 for spacing labels on the Y axis; but we may want to use some other
19986 value. For generality, we should replace `five' with a variable to
19987 which we can assign a value. The best name I can think of for this
19988 variable is @code{Y-axis-label-spacing}.
19991 Using this term, and an @code{if} expression, we produce the
19996 (if (zerop (% height Y-axis-label-spacing))
19999 (* (1+ (/ height Y-axis-label-spacing))
20000 Y-axis-label-spacing))
20005 This expression returns the value of @code{height} itself if the height
20006 is an even multiple of the value of the @code{Y-axis-label-spacing} or
20007 else it computes and returns a value of @code{height} that is equal to
20008 the next higher multiple of the value of the @code{Y-axis-label-spacing}.
20010 We can now include this expression in the @code{let} expression of the
20011 @code{print-graph} function (after first setting the value of
20012 @code{Y-axis-label-spacing}):
20013 @vindex Y-axis-label-spacing
20017 (defvar Y-axis-label-spacing 5
20018 "Number of lines from one Y axis label to next.")
20023 (let* ((height (apply 'max numbers-list))
20024 (height-of-top-line
20025 (if (zerop (% height Y-axis-label-spacing))
20030 (* (1+ (/ height Y-axis-label-spacing))
20031 Y-axis-label-spacing)))
20032 (symbol-width (length graph-blank))))
20038 (Note use of the @code{let*} function: the initial value of height is
20039 computed once by the @code{(apply 'max numbers-list)} expression and
20040 then the resulting value of @code{height} is used to compute its
20041 final value. @xref{fwd-para let, , The @code{let*} expression}, for
20042 more about @code{let*}.)
20044 @node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis
20045 @appendixsubsec Construct a Y Axis Element
20047 When we print the vertical axis, we want to insert strings such as
20048 @w{@samp{5 -}} and @w{@samp{10 - }} every five lines.
20049 Moreover, we want the numbers and dashes to line up, so shorter
20050 numbers must be padded with leading spaces. If some of the strings
20051 use two digit numbers, the strings with single digit numbers must
20052 include a leading blank space before the number.
20054 @findex number-to-string
20055 To figure out the length of the number, the @code{length} function is
20056 used. But the @code{length} function works only with a string, not with
20057 a number. So the number has to be converted from being a number to
20058 being a string. This is done with the @code{number-to-string} function.
20063 (length (number-to-string 35))
20066 (length (number-to-string 100))
20072 (@code{number-to-string} is also called @code{int-to-string}; you will
20073 see this alternative name in various sources.)
20075 In addition, in each label, each number is followed by a string such
20076 as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker.
20077 This variable is defined with @code{defvar}:
20082 (defvar Y-axis-tic " - "
20083 "String that follows number in a Y axis label.")
20087 The length of the Y label is the sum of the length of the Y axis tic
20088 mark and the length of the number of the top of the graph.
20091 (length (concat (number-to-string height) Y-axis-tic)))
20094 This value will be calculated by the @code{print-graph} function in
20095 its varlist as @code{full-Y-label-width} and passed on. (Note that we
20096 did not think to include this in the varlist when we first proposed it.)
20098 To make a complete vertical axis label, a tic mark is concatenated
20099 with a number; and the two together may be preceded by one or more
20100 spaces depending on how long the number is. The label consists of
20101 three parts: the (optional) leading spaces, the number, and the tic
20102 mark. The function is passed the value of the number for the specific
20103 row, and the value of the width of the top line, which is calculated
20104 (just once) by @code{print-graph}.
20108 (defun Y-axis-element (number full-Y-label-width)
20109 "Construct a NUMBERed label element.
20110 A numbered element looks like this ` 5 - ',
20111 and is padded as needed so all line up with
20112 the element for the largest number."
20115 (let* ((leading-spaces
20116 (- full-Y-label-width
20118 (concat (number-to-string number)
20123 (make-string leading-spaces ? )
20124 (number-to-string number)
20129 The @code{Y-axis-element} function concatenates together the leading
20130 spaces, if any; the number, as a string; and the tic mark.
20132 To figure out how many leading spaces the label will need, the
20133 function subtracts the actual length of the label---the length of the
20134 number plus the length of the tic mark---from the desired label width.
20136 @findex make-string
20137 Blank spaces are inserted using the @code{make-string} function. This
20138 function takes two arguments: the first tells it how long the string
20139 will be and the second is a symbol for the character to insert, in a
20140 special format. The format is a question mark followed by a blank
20141 space, like this, @samp{? }. @xref{Character Type, , Character Type,
20142 elisp, The GNU Emacs Lisp Reference Manual}, for a description of the
20143 syntax for characters. (Of course, you might want to replace the
20144 blank space by some other character @dots{} You know what to do.)
20146 The @code{number-to-string} function is used in the concatenation
20147 expression, to convert the number to a string that is concatenated
20148 with the leading spaces and the tic mark.
20150 @node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis
20151 @appendixsubsec Create a Y Axis Column
20153 The preceding functions provide all the tools needed to construct a
20154 function that generates a list of numbered and blank strings to insert
20155 as the label for the vertical axis:
20157 @findex Y-axis-column
20160 (defun Y-axis-column (height width-of-label)
20161 "Construct list of Y axis labels and blank strings.
20162 For HEIGHT of line above base and WIDTH-OF-LABEL."
20166 (while (> height 1)
20167 (if (zerop (% height Y-axis-label-spacing))
20168 ;; @r{Insert label.}
20171 (Y-axis-element height width-of-label)
20175 ;; @r{Else, insert blanks.}
20178 (make-string width-of-label ? )
20180 (setq height (1- height)))
20181 ;; @r{Insert base line.}
20183 (cons (Y-axis-element 1 width-of-label) Y-axis))
20184 (nreverse Y-axis)))
20188 In this function, we start with the value of @code{height} and
20189 repetitively subtract one from its value. After each subtraction, we
20190 test to see whether the value is an integral multiple of the
20191 @code{Y-axis-label-spacing}. If it is, we construct a numbered label
20192 using the @code{Y-axis-element} function; if not, we construct a
20193 blank label using the @code{make-string} function. The base line
20194 consists of the number one followed by a tic mark.
20197 @node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis
20198 @appendixsubsec The Not Quite Final Version of @code{print-Y-axis}
20200 The list constructed by the @code{Y-axis-column} function is passed to
20201 the @code{print-Y-axis} function, which inserts the list as a column.
20203 @findex print-Y-axis
20206 (defun print-Y-axis (height full-Y-label-width)
20207 "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH.
20208 Height must be the maximum height of the graph.
20209 Full width is the width of the highest label element."
20210 ;; Value of height and full-Y-label-width
20211 ;; are passed by `print-graph'.
20214 (let ((start (point)))
20216 (Y-axis-column height full-Y-label-width))
20217 ;; @r{Place point ready for inserting graph.}
20219 ;; @r{Move point forward by value of} full-Y-label-width
20220 (forward-char full-Y-label-width)))
20224 The @code{print-Y-axis} uses the @code{insert-rectangle} function to
20225 insert the Y axis labels created by the @code{Y-axis-column} function.
20226 In addition, it places point at the correct position for printing the body of
20229 You can test @code{print-Y-axis}:
20237 Y-axis-label-spacing
20246 Copy the following expression:
20249 (print-Y-axis 12 5)
20253 Switch to the @file{*scratch*} buffer and place the cursor where you
20254 want the axis labels to start.
20257 Type @kbd{M-:} (@code{eval-expression}).
20260 Yank the @code{graph-body-print} expression into the minibuffer
20261 with @kbd{C-y} (@code{yank)}.
20264 Press @key{RET} to evaluate the expression.
20267 Emacs will print labels vertically, the top one being @w{@samp{10 -@w{
20268 }}}. (The @code{print-graph} function will pass the value of
20269 @code{height-of-top-line}, which in this case will end up as 15,
20270 thereby getting rid of what might appear as a bug.)
20273 @node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph
20274 @appendixsec The @code{print-X-axis} Function
20275 @cindex Axis, print horizontal
20276 @cindex X axis printing
20277 @cindex Print horizontal axis
20278 @cindex Horizontal axis printing
20280 X axis labels are much like Y axis labels, except that the ticks are on a
20281 line above the numbers. Labels should look like this:
20290 The first tic is under the first column of the graph and is preceded by
20291 several blank spaces. These spaces provide room in rows above for the Y
20292 axis labels. The second, third, fourth, and subsequent ticks are all
20293 spaced equally, according to the value of @code{X-axis-label-spacing}.
20295 The second row of the X axis consists of numbers, preceded by several
20296 blank spaces and also separated according to the value of the variable
20297 @code{X-axis-label-spacing}.
20299 The value of the variable @code{X-axis-label-spacing} should itself be
20300 measured in units of @code{symbol-width}, since you may want to change
20301 the width of the symbols that you are using to print the body of the
20302 graph without changing the ways the graph is labelled.
20305 * Similarities differences::
20306 * X Axis Tic Marks::
20309 @node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis
20311 @unnumberedsubsec Similarities and differences
20314 The @code{print-X-axis} function is constructed in more or less the
20315 same fashion as the @code{print-Y-axis} function except that it has
20316 two lines: the line of tic marks and the numbers. We will write a
20317 separate function to print each line and then combine them within the
20318 @code{print-X-axis} function.
20320 This is a three step process:
20324 Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}.
20327 Write a function to print the X numbers, @code{print-X-axis-numbered-line}.
20330 Write a function to print both lines, the @code{print-X-axis} function,
20331 using @code{print-X-axis-tic-line} and
20332 @code{print-X-axis-numbered-line}.
20335 @node X Axis Tic Marks, , Similarities differences, print-X-axis
20336 @appendixsubsec X Axis Tic Marks
20338 The first function should print the X axis tic marks. We must specify
20339 the tic marks themselves and their spacing:
20343 (defvar X-axis-label-spacing
20344 (if (boundp 'graph-blank)
20345 (* 5 (length graph-blank)) 5)
20346 "Number of units from one X axis label to next.")
20351 (Note that the value of @code{graph-blank} is set by another
20352 @code{defvar}. The @code{boundp} predicate checks whether it has
20353 already been set; @code{boundp} returns @code{nil} if it has not. If
20354 @code{graph-blank} were unbound and we did not use this conditional
20355 construction, in a recent GNU Emacs, we would enter the debugger and
20356 see an error message saying @samp{@w{Debugger entered--Lisp error:}
20357 @w{(void-variable graph-blank)}}.)
20360 Here is the @code{defvar} for @code{X-axis-tic-symbol}:
20364 (defvar X-axis-tic-symbol "|"
20365 "String to insert to point to a column in X axis.")
20370 The goal is to make a line that looks like this:
20376 The first tic is indented so that it is under the first column, which is
20377 indented to provide space for the Y axis labels.
20379 A tic element consists of the blank spaces that stretch from one tic to
20380 the next plus a tic symbol. The number of blanks is determined by the
20381 width of the tic symbol and the @code{X-axis-label-spacing}.
20384 The code looks like this:
20388 ;;; X-axis-tic-element
20392 ;; @r{Make a string of blanks.}
20393 (- (* symbol-width X-axis-label-spacing)
20394 (length X-axis-tic-symbol))
20396 ;; @r{Concatenate blanks with tic symbol.}
20402 Next, we determine how many blanks are needed to indent the first tic
20403 mark to the first column of the graph. This uses the value of
20404 @code{full-Y-label-width} passed it by the @code{print-graph} function.
20407 The code to make @code{X-axis-leading-spaces}
20412 ;; X-axis-leading-spaces
20414 (make-string full-Y-label-width ? )
20419 We also need to determine the length of the horizontal axis, which is
20420 the length of the numbers list, and the number of ticks in the horizontal
20427 (length numbers-list)
20433 (* symbol-width X-axis-label-spacing)
20437 ;; number-of-X-ticks
20438 (if (zerop (% (X-length tic-width)))
20439 (/ (X-length tic-width))
20440 (1+ (/ (X-length tic-width))))
20445 All this leads us directly to the function for printing the X axis tic line:
20447 @findex print-X-axis-tic-line
20450 (defun print-X-axis-tic-line
20451 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
20452 "Print ticks for X axis."
20453 (insert X-axis-leading-spaces)
20454 (insert X-axis-tic-symbol) ; @r{Under first column.}
20457 ;; @r{Insert second tic in the right spot.}
20460 (- (* symbol-width X-axis-label-spacing)
20461 ;; @r{Insert white space up to second tic symbol.}
20462 (* 2 (length X-axis-tic-symbol)))
20464 X-axis-tic-symbol))
20467 ;; @r{Insert remaining ticks.}
20468 (while (> number-of-X-tics 1)
20469 (insert X-axis-tic-element)
20470 (setq number-of-X-tics (1- number-of-X-tics))))
20474 The line of numbers is equally straightforward:
20477 First, we create a numbered element with blank spaces before each number:
20479 @findex X-axis-element
20482 (defun X-axis-element (number)
20483 "Construct a numbered X axis element."
20484 (let ((leading-spaces
20485 (- (* symbol-width X-axis-label-spacing)
20486 (length (number-to-string number)))))
20487 (concat (make-string leading-spaces ? )
20488 (number-to-string number))))
20492 Next, we create the function to print the numbered line, starting with
20493 the number ``1'' under the first column:
20495 @findex print-X-axis-numbered-line
20498 (defun print-X-axis-numbered-line
20499 (number-of-X-tics X-axis-leading-spaces)
20500 "Print line of X-axis numbers"
20501 (let ((number X-axis-label-spacing))
20502 (insert X-axis-leading-spaces)
20508 ;; @r{Insert white space up to next number.}
20509 (- (* symbol-width X-axis-label-spacing) 2)
20511 (number-to-string number)))
20514 ;; @r{Insert remaining numbers.}
20515 (setq number (+ number X-axis-label-spacing))
20516 (while (> number-of-X-tics 1)
20517 (insert (X-axis-element number))
20518 (setq number (+ number X-axis-label-spacing))
20519 (setq number-of-X-tics (1- number-of-X-tics)))))
20523 Finally, we need to write the @code{print-X-axis} that uses
20524 @code{print-X-axis-tic-line} and
20525 @code{print-X-axis-numbered-line}.
20527 The function must determine the local values of the variables used by both
20528 @code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and
20529 then it must call them. Also, it must print the carriage return that
20530 separates the two lines.
20532 The function consists of a varlist that specifies five local variables,
20533 and calls to each of the two line printing functions:
20535 @findex print-X-axis
20538 (defun print-X-axis (numbers-list)
20539 "Print X axis labels to length of NUMBERS-LIST."
20540 (let* ((leading-spaces
20541 (make-string full-Y-label-width ? ))
20544 ;; symbol-width @r{is provided by} graph-body-print
20545 (tic-width (* symbol-width X-axis-label-spacing))
20546 (X-length (length numbers-list))
20554 ;; @r{Make a string of blanks.}
20555 (- (* symbol-width X-axis-label-spacing)
20556 (length X-axis-tic-symbol))
20560 ;; @r{Concatenate blanks with tic symbol.}
20561 X-axis-tic-symbol))
20565 (if (zerop (% X-length tic-width))
20566 (/ X-length tic-width)
20567 (1+ (/ X-length tic-width)))))
20570 (print-X-axis-tic-line tic-number leading-spaces X-tic)
20572 (print-X-axis-numbered-line tic-number leading-spaces)))
20577 You can test @code{print-X-axis}:
20581 Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing},
20582 @code{print-X-axis-tic-line}, as well as @code{X-axis-element},
20583 @code{print-X-axis-numbered-line}, and @code{print-X-axis}.
20586 Copy the following expression:
20591 (let ((full-Y-label-width 5)
20594 '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16))))
20599 Switch to the @file{*scratch*} buffer and place the cursor where you
20600 want the axis labels to start.
20603 Type @kbd{M-:} (@code{eval-expression}).
20606 Yank the test expression into the minibuffer
20607 with @kbd{C-y} (@code{yank)}.
20610 Press @key{RET} to evaluate the expression.
20614 Emacs will print the horizontal axis like this:
20624 @node Print Whole Graph, , print-X-axis, Full Graph
20625 @appendixsec Printing the Whole Graph
20626 @cindex Printing the whole graph
20627 @cindex Whole graph printing
20628 @cindex Graph, printing all
20630 Now we are nearly ready to print the whole graph.
20632 The function to print the graph with the proper labels follows the
20633 outline we created earlier (@pxref{Full Graph, , A Graph with Labelled
20634 Axes}), but with additions.
20637 Here is the outline:
20641 (defun print-graph (numbers-list)
20642 "@var{documentation}@dots{}"
20643 (let ((height @dots{}
20647 (print-Y-axis height @dots{} )
20648 (graph-body-print numbers-list)
20649 (print-X-axis @dots{} )))
20654 * The final version::
20655 * Test print-graph::
20656 * Graphing words in defuns::
20660 * Final printed graph::
20663 @node The final version, Test print-graph, Print Whole Graph, Print Whole Graph
20665 @unnumberedsubsec Changes for the Final Version
20668 The final version is different from what we planned in two ways:
20669 first, it contains additional values calculated once in the varlist;
20670 second, it carries an option to specify the labels' increment per row.
20671 This latter feature turns out to be essential; otherwise, a graph may
20672 have more rows than fit on a display or on a sheet of paper.
20675 This new feature requires a change to the @code{Y-axis-column}
20676 function, to add @code{vertical-step} to it. The function looks like
20679 @findex Y-axis-column @r{Final version.}
20682 ;;; @r{Final version.}
20683 (defun Y-axis-column
20684 (height width-of-label &optional vertical-step)
20685 "Construct list of labels for Y axis.
20686 HEIGHT is maximum height of graph.
20687 WIDTH-OF-LABEL is maximum width of label.
20688 VERTICAL-STEP, an option, is a positive integer
20689 that specifies how much a Y axis label increments
20690 for each line. For example, a step of 5 means
20691 that each line is five units of the graph."
20695 (number-per-line (or vertical-step 1)))
20696 (while (> height 1)
20697 (if (zerop (% height Y-axis-label-spacing))
20700 ;; @r{Insert label.}
20704 (* height number-per-line)
20709 ;; @r{Else, insert blanks.}
20712 (make-string width-of-label ? )
20714 (setq height (1- height)))
20717 ;; @r{Insert base line.}
20718 (setq Y-axis (cons (Y-axis-element
20719 (or vertical-step 1)
20722 (nreverse Y-axis)))
20726 The values for the maximum height of graph and the width of a symbol
20727 are computed by @code{print-graph} in its @code{let} expression; so
20728 @code{graph-body-print} must be changed to accept them.
20730 @findex graph-body-print @r{Final version.}
20733 ;;; @r{Final version.}
20734 (defun graph-body-print (numbers-list height symbol-width)
20735 "Print a bar graph of the NUMBERS-LIST.
20736 The numbers-list consists of the Y-axis values.
20737 HEIGHT is maximum height of graph.
20738 SYMBOL-WIDTH is number of each column."
20741 (let (from-position)
20742 (while numbers-list
20743 (setq from-position (point))
20745 (column-of-graph height (car numbers-list)))
20746 (goto-char from-position)
20747 (forward-char symbol-width)
20750 ;; @r{Draw graph column by column.}
20752 (setq numbers-list (cdr numbers-list)))
20753 ;; @r{Place point for X axis labels.}
20754 (forward-line height)
20760 Finally, the code for the @code{print-graph} function:
20762 @findex print-graph @r{Final version.}
20765 ;;; @r{Final version.}
20767 (numbers-list &optional vertical-step)
20768 "Print labelled bar graph of the NUMBERS-LIST.
20769 The numbers-list consists of the Y-axis values.
20773 Optionally, VERTICAL-STEP, a positive integer,
20774 specifies how much a Y axis label increments for
20775 each line. For example, a step of 5 means that
20776 each row is five units."
20779 (let* ((symbol-width (length graph-blank))
20780 ;; @code{height} @r{is both the largest number}
20781 ;; @r{and the number with the most digits.}
20782 (height (apply 'max numbers-list))
20785 (height-of-top-line
20786 (if (zerop (% height Y-axis-label-spacing))
20789 (* (1+ (/ height Y-axis-label-spacing))
20790 Y-axis-label-spacing)))
20793 (vertical-step (or vertical-step 1))
20794 (full-Y-label-width
20800 (* height-of-top-line vertical-step))
20806 height-of-top-line full-Y-label-width vertical-step)
20810 numbers-list height-of-top-line symbol-width)
20811 (print-X-axis numbers-list)))
20815 @node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph
20816 @appendixsubsec Testing @code{print-graph}
20819 We can test the @code{print-graph} function with a short list of numbers:
20823 Install the final versions of @code{Y-axis-column},
20824 @code{graph-body-print}, and @code{print-graph} (in addition to the
20828 Copy the following expression:
20831 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1))
20835 Switch to the @file{*scratch*} buffer and place the cursor where you
20836 want the axis labels to start.
20839 Type @kbd{M-:} (@code{eval-expression}).
20842 Yank the test expression into the minibuffer
20843 with @kbd{C-y} (@code{yank)}.
20846 Press @key{RET} to evaluate the expression.
20850 Emacs will print a graph that looks like this:
20871 On the other hand, if you pass @code{print-graph} a
20872 @code{vertical-step} value of 2, by evaluating this expression:
20875 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2)
20880 The graph looks like this:
20901 (A question: is the `2' on the bottom of the vertical axis a bug or a
20902 feature? If you think it is a bug, and should be a `1' instead, (or
20903 even a `0'), you can modify the sources.)
20905 @node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph
20906 @appendixsubsec Graphing Numbers of Words and Symbols
20908 Now for the graph for which all this code was written: a graph that
20909 shows how many function definitions contain fewer than 10 words and
20910 symbols, how many contain between 10 and 19 words and symbols, how
20911 many contain between 20 and 29 words and symbols, and so on.
20913 This is a multi-step process. First make sure you have loaded all the
20917 It is a good idea to reset the value of @code{top-of-ranges} in case
20918 you have set it to some different value. You can evaluate the
20923 (setq top-of-ranges
20926 110 120 130 140 150
20927 160 170 180 190 200
20928 210 220 230 240 250
20929 260 270 280 290 300)
20934 Next create a list of the number of words and symbols in each range.
20938 Evaluate the following:
20942 (setq list-for-graph
20945 (recursive-lengths-list-many-files
20946 (directory-files "/usr/local/emacs/lisp"
20954 On my old machine, this took about an hour. It looked though 303 Lisp
20955 files in my copy of Emacs version 19.23. After all that computing,
20956 the @code{list-for-graph} had this value:
20960 (537 1027 955 785 594 483 349 292 224 199 166 120 116 99
20961 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220)
20966 This means that my copy of Emacs had 537 function definitions with
20967 fewer than 10 words or symbols in them, 1,027 function definitions
20968 with 10 to 19 words or symbols in them, 955 function definitions with
20969 20 to 29 words or symbols in them, and so on.
20971 Clearly, just by looking at this list we can see that most function
20972 definitions contain ten to thirty words and symbols.
20974 Now for printing. We do @emph{not} want to print a graph that is
20975 1,030 lines high @dots{} Instead, we should print a graph that is
20976 fewer than twenty-five lines high. A graph that height can be
20977 displayed on almost any monitor, and easily printed on a sheet of paper.
20979 This means that each value in @code{list-for-graph} must be reduced to
20980 one-fiftieth its present value.
20982 Here is a short function to do just that, using two functions we have
20983 not yet seen, @code{mapcar} and @code{lambda}.
20987 (defun one-fiftieth (full-range)
20988 "Return list, each number one-fiftieth of previous."
20989 (mapcar '(lambda (arg) (/ arg 50)) full-range))
20993 @node lambda, mapcar, Graphing words in defuns, Print Whole Graph
20994 @appendixsubsec A @code{lambda} Expression: Useful Anonymity
20995 @cindex Anonymous function
20998 @code{lambda} is the symbol for an anonymous function, a function
20999 without a name. Every time you use an anonymous function, you need to
21000 include its whole body.
21007 (lambda (arg) (/ arg 50))
21011 is a function definition that says `return the value resulting from
21012 dividing whatever is passed to me as @code{arg} by 50'.
21015 Earlier, for example, we had a function @code{multiply-by-seven}; it
21016 multiplied its argument by 7. This function is similar, except it
21017 divides its argument by 50; and, it has no name. The anonymous
21018 equivalent of @code{multiply-by-seven} is:
21021 (lambda (number) (* 7 number))
21025 (@xref{defun, , The @code{defun} Special Form}.)
21029 If we want to multiply 3 by 7, we can write:
21031 @c !!! Clear print-postscript-figures if the computer formatting this
21032 @c document is too small and cannot handle all the diagrams and figures.
21033 @c clear print-postscript-figures
21034 @c set print-postscript-figures
21035 @c lambda example diagram #1
21039 (multiply-by-seven 3)
21040 \_______________/ ^
21046 @ifset print-postscript-figures
21049 @center @image{lambda-1}
21050 %%%% old method of including an image
21051 % \input /usr/local/lib/tex/inputs/psfig.tex
21052 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}}
21057 @ifclear print-postscript-figures
21061 (multiply-by-seven 3)
21062 \_______________/ ^
21071 This expression returns 21.
21075 Similarly, we can write:
21077 @c lambda example diagram #2
21081 ((lambda (number) (* 7 number)) 3)
21082 \____________________________/ ^
21084 anonymous function argument
21088 @ifset print-postscript-figures
21091 @center @image{lambda-2}
21092 %%%% old method of including an image
21093 % \input /usr/local/lib/tex/inputs/psfig.tex
21094 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}}
21099 @ifclear print-postscript-figures
21103 ((lambda (number) (* 7 number)) 3)
21104 \____________________________/ ^
21106 anonymous function argument
21114 If we want to divide 100 by 50, we can write:
21116 @c lambda example diagram #3
21120 ((lambda (arg) (/ arg 50)) 100)
21121 \______________________/ \_/
21123 anonymous function argument
21127 @ifset print-postscript-figures
21130 @center @image{lambda-3}
21131 %%%% old method of including an image
21132 % \input /usr/local/lib/tex/inputs/psfig.tex
21133 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}}
21138 @ifclear print-postscript-figures
21142 ((lambda (arg) (/ arg 50)) 100)
21143 \______________________/ \_/
21145 anonymous function argument
21152 This expression returns 2. The 100 is passed to the function, which
21153 divides that number by 50.
21155 @xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs
21156 Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda
21157 expressions derive from the Lambda Calculus.
21159 @node mapcar, Another Bug, lambda, Print Whole Graph
21160 @appendixsubsec The @code{mapcar} Function
21163 @code{mapcar} is a function that calls its first argument with each
21164 element of its second argument, in turn. The second argument must be
21167 The @samp{map} part of the name comes from the mathematical phrase,
21168 `mapping over a domain', meaning to apply a function to each of the
21169 elements in a domain. The mathematical phrase is based on the
21170 metaphor of a surveyor walking, one step at a time, over an area he is
21171 mapping. And @samp{car}, of course, comes from the Lisp notion of the
21180 (mapcar '1+ '(2 4 6))
21186 The function @code{1+} which adds one to its argument, is executed on
21187 @emph{each} element of the list, and a new list is returned.
21189 Contrast this with @code{apply}, which applies its first argument to
21191 (@xref{Readying a Graph, , Readying a Graph}, for a explanation of
21195 In the definition of @code{one-fiftieth}, the first argument is the
21196 anonymous function:
21199 (lambda (arg) (/ arg 50))
21203 and the second argument is @code{full-range}, which will be bound to
21204 @code{list-for-graph}.
21207 The whole expression looks like this:
21210 (mapcar '(lambda (arg) (/ arg 50)) full-range))
21213 @xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs
21214 Lisp Reference Manual}, for more about @code{mapcar}.
21216 Using the @code{one-fiftieth} function, we can generate a list in
21217 which each element is one-fiftieth the size of the corresponding
21218 element in @code{list-for-graph}.
21222 (setq fiftieth-list-for-graph
21223 (one-fiftieth list-for-graph))
21228 The resulting list looks like this:
21232 (10 20 19 15 11 9 6 5 4 3 3 2 2
21233 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4)
21238 This, we are almost ready to print! (We also notice the loss of
21239 information: many of the higher ranges are 0, meaning that fewer than
21240 50 defuns had that many words or symbols---but not necessarily meaning
21241 that none had that many words or symbols.)
21243 @node Another Bug, Final printed graph, mapcar, Print Whole Graph
21244 @appendixsubsec Another Bug @dots{} Most Insidious
21245 @cindex Bug, most insidious type
21246 @cindex Insidious type of bug
21248 I said `almost ready to print'! Of course, there is a bug in the
21249 @code{print-graph} function @dots{} It has a @code{vertical-step}
21250 option, but not a @code{horizontal-step} option. The
21251 @code{top-of-range} scale goes from 10 to 300 by tens. But the
21252 @code{print-graph} function will print only by ones.
21254 This is a classic example of what some consider the most insidious
21255 type of bug, the bug of omission. This is not the kind of bug you can
21256 find by studying the code, for it is not in the code; it is an omitted
21257 feature. Your best actions are to try your program early and often;
21258 and try to arrange, as much as you can, to write code that is easy to
21259 understand and easy to change. Try to be aware, whenever you can,
21260 that whatever you have written, @emph{will} be rewritten, if not soon,
21261 eventually. A hard maxim to follow.
21263 It is the @code{print-X-axis-numbered-line} function that needs the
21264 work; and then the @code{print-X-axis} and the @code{print-graph}
21265 functions need to be adapted. Not much needs to be done; there is one
21266 nicety: the numbers ought to line up under the tic marks. This takes
21270 Here is the corrected @code{print-X-axis-numbered-line}:
21274 (defun print-X-axis-numbered-line
21275 (number-of-X-tics X-axis-leading-spaces
21276 &optional horizontal-step)
21277 "Print line of X-axis numbers"
21278 (let ((number X-axis-label-spacing)
21279 (horizontal-step (or horizontal-step 1)))
21282 (insert X-axis-leading-spaces)
21283 ;; @r{Delete extra leading spaces.}
21286 (length (number-to-string horizontal-step)))))
21291 ;; @r{Insert white space.}
21293 X-axis-label-spacing)
21296 (number-to-string horizontal-step)))
21300 (* number horizontal-step))))
21303 ;; @r{Insert remaining numbers.}
21304 (setq number (+ number X-axis-label-spacing))
21305 (while (> number-of-X-tics 1)
21306 (insert (X-axis-element
21307 (* number horizontal-step)))
21308 (setq number (+ number X-axis-label-spacing))
21309 (setq number-of-X-tics (1- number-of-X-tics)))))
21314 If you are reading this in Info, you can see the new versions of
21315 @code{print-X-axis} @code{print-graph} and evaluate them. If you are
21316 reading this in a printed book, you can see the changed lines here
21317 (the full text is too much to print).
21322 (defun print-X-axis (numbers-list horizontal-step)
21324 (print-X-axis-numbered-line
21325 tic-number leading-spaces horizontal-step))
21333 &optional vertical-step horizontal-step)
21335 (print-X-axis numbers-list horizontal-step))
21343 (defun print-X-axis (numbers-list horizontal-step)
21344 "Print X axis labels to length of NUMBERS-LIST.
21345 Optionally, HORIZONTAL-STEP, a positive integer,
21346 specifies how much an X axis label increments for
21350 ;; Value of symbol-width and full-Y-label-width
21351 ;; are passed by `print-graph'.
21352 (let* ((leading-spaces
21353 (make-string full-Y-label-width ? ))
21354 ;; symbol-width @r{is provided by} graph-body-print
21355 (tic-width (* symbol-width X-axis-label-spacing))
21356 (X-length (length numbers-list))
21362 ;; @r{Make a string of blanks.}
21363 (- (* symbol-width X-axis-label-spacing)
21364 (length X-axis-tic-symbol))
21368 ;; @r{Concatenate blanks with tic symbol.}
21369 X-axis-tic-symbol))
21371 (if (zerop (% X-length tic-width))
21372 (/ X-length tic-width)
21373 (1+ (/ X-length tic-width)))))
21377 (print-X-axis-tic-line
21378 tic-number leading-spaces X-tic)
21380 (print-X-axis-numbered-line
21381 tic-number leading-spaces horizontal-step)))
21388 (numbers-list &optional vertical-step horizontal-step)
21389 "Print labelled bar graph of the NUMBERS-LIST.
21390 The numbers-list consists of the Y-axis values.
21394 Optionally, VERTICAL-STEP, a positive integer,
21395 specifies how much a Y axis label increments for
21396 each line. For example, a step of 5 means that
21397 each row is five units.
21401 Optionally, HORIZONTAL-STEP, a positive integer,
21402 specifies how much an X axis label increments for
21404 (let* ((symbol-width (length graph-blank))
21405 ;; @code{height} @r{is both the largest number}
21406 ;; @r{and the number with the most digits.}
21407 (height (apply 'max numbers-list))
21410 (height-of-top-line
21411 (if (zerop (% height Y-axis-label-spacing))
21414 (* (1+ (/ height Y-axis-label-spacing))
21415 Y-axis-label-spacing)))
21418 (vertical-step (or vertical-step 1))
21419 (full-Y-label-width
21423 (* height-of-top-line vertical-step))
21428 height-of-top-line full-Y-label-width vertical-step)
21430 numbers-list height-of-top-line symbol-width)
21431 (print-X-axis numbers-list horizontal-step)))
21438 Graphing Definitions Re-listed
21441 Here are all the graphing definitions in their final form:
21445 (defvar top-of-ranges
21448 110 120 130 140 150
21449 160 170 180 190 200
21450 210 220 230 240 250)
21451 "List specifying ranges for `defuns-per-range'.")
21455 (defvar graph-symbol "*"
21456 "String used as symbol in graph, usually an asterisk.")
21460 (defvar graph-blank " "
21461 "String used as blank in graph, usually a blank space.
21462 graph-blank must be the same number of columns wide
21467 (defvar Y-axis-tic " - "
21468 "String that follows number in a Y axis label.")
21472 (defvar Y-axis-label-spacing 5
21473 "Number of lines from one Y axis label to next.")
21477 (defvar X-axis-tic-symbol "|"
21478 "String to insert to point to a column in X axis.")
21482 (defvar X-axis-label-spacing
21483 (if (boundp 'graph-blank)
21484 (* 5 (length graph-blank)) 5)
21485 "Number of units from one X axis label to next.")
21491 (defun count-words-in-defun ()
21492 "Return the number of words and symbols in a defun."
21493 (beginning-of-defun)
21495 (end (save-excursion (end-of-defun) (point))))
21500 (and (< (point) end)
21502 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
21504 (setq count (1+ count)))
21511 (defun lengths-list-file (filename)
21512 "Return list of definitions' lengths within FILE.
21513 The returned list is a list of numbers.
21514 Each number is the number of words or
21515 symbols in one function definition."
21519 (message "Working on `%s' ... " filename)
21521 (let ((buffer (find-file-noselect filename))
21523 (set-buffer buffer)
21524 (setq buffer-read-only t)
21526 (goto-char (point-min))
21530 (while (re-search-forward "^(defun" nil t)
21532 (cons (count-words-in-defun) lengths-list)))
21533 (kill-buffer buffer)
21540 (defun lengths-list-many-files (list-of-files)
21541 "Return list of lengths of defuns in LIST-OF-FILES."
21542 (let (lengths-list)
21543 ;;; @r{true-or-false-test}
21544 (while list-of-files
21550 ;;; @r{Generate a lengths' list.}
21552 (expand-file-name (car list-of-files)))))
21553 ;;; @r{Make files' list shorter.}
21554 (setq list-of-files (cdr list-of-files)))
21555 ;;; @r{Return final value of lengths' list.}
21562 (defun defuns-per-range (sorted-lengths top-of-ranges)
21563 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
21564 (let ((top-of-range (car top-of-ranges))
21565 (number-within-range 0)
21566 defuns-per-range-list)
21571 (while top-of-ranges
21575 ;; @r{Need number for numeric test.}
21576 (car sorted-lengths)
21577 (< (car sorted-lengths) top-of-range))
21579 ;; @r{Count number of definitions within current range.}
21580 (setq number-within-range (1+ number-within-range))
21581 (setq sorted-lengths (cdr sorted-lengths)))
21585 ;; @r{Exit inner loop but remain within outer loop.}
21587 (setq defuns-per-range-list
21588 (cons number-within-range defuns-per-range-list))
21589 (setq number-within-range 0) ; @r{Reset count to zero.}
21591 ;; @r{Move to next range.}
21592 (setq top-of-ranges (cdr top-of-ranges))
21593 ;; @r{Specify next top of range value.}
21594 (setq top-of-range (car top-of-ranges)))
21598 ;; @r{Exit outer loop and count the number of defuns larger than}
21599 ;; @r{ the largest top-of-range value.}
21600 (setq defuns-per-range-list
21602 (length sorted-lengths)
21603 defuns-per-range-list))
21605 ;; @r{Return a list of the number of definitions within each range,}
21606 ;; @r{ smallest to largest.}
21607 (nreverse defuns-per-range-list)))
21613 (defun column-of-graph (max-graph-height actual-height)
21614 "Return list of MAX-GRAPH-HEIGHT strings;
21615 ACTUAL-HEIGHT are graph-symbols.
21616 The graph-symbols are contiguous entries at the end
21618 The list will be inserted as one column of a graph.
21619 The strings are either graph-blank or graph-symbol."
21623 (let ((insert-list nil)
21624 (number-of-top-blanks
21625 (- max-graph-height actual-height)))
21627 ;; @r{Fill in @code{graph-symbols}.}
21628 (while (> actual-height 0)
21629 (setq insert-list (cons graph-symbol insert-list))
21630 (setq actual-height (1- actual-height)))
21634 ;; @r{Fill in @code{graph-blanks}.}
21635 (while (> number-of-top-blanks 0)
21636 (setq insert-list (cons graph-blank insert-list))
21637 (setq number-of-top-blanks
21638 (1- number-of-top-blanks)))
21640 ;; @r{Return whole list.}
21647 (defun Y-axis-element (number full-Y-label-width)
21648 "Construct a NUMBERed label element.
21649 A numbered element looks like this ` 5 - ',
21650 and is padded as needed so all line up with
21651 the element for the largest number."
21654 (let* ((leading-spaces
21655 (- full-Y-label-width
21657 (concat (number-to-string number)
21662 (make-string leading-spaces ? )
21663 (number-to-string number)
21670 (defun print-Y-axis
21671 (height full-Y-label-width &optional vertical-step)
21672 "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH.
21673 Height must be the maximum height of the graph.
21674 Full width is the width of the highest label element.
21675 Optionally, print according to VERTICAL-STEP."
21678 ;; Value of height and full-Y-label-width
21679 ;; are passed by `print-graph'.
21680 (let ((start (point)))
21682 (Y-axis-column height full-Y-label-width vertical-step))
21685 ;; @r{Place point ready for inserting graph.}
21687 ;; @r{Move point forward by value of} full-Y-label-width
21688 (forward-char full-Y-label-width)))
21694 (defun print-X-axis-tic-line
21695 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
21696 "Print ticks for X axis."
21697 (insert X-axis-leading-spaces)
21698 (insert X-axis-tic-symbol) ; @r{Under first column.}
21701 ;; @r{Insert second tic in the right spot.}
21704 (- (* symbol-width X-axis-label-spacing)
21705 ;; @r{Insert white space up to second tic symbol.}
21706 (* 2 (length X-axis-tic-symbol)))
21708 X-axis-tic-symbol))
21711 ;; @r{Insert remaining ticks.}
21712 (while (> number-of-X-tics 1)
21713 (insert X-axis-tic-element)
21714 (setq number-of-X-tics (1- number-of-X-tics))))
21720 (defun X-axis-element (number)
21721 "Construct a numbered X axis element."
21722 (let ((leading-spaces
21723 (- (* symbol-width X-axis-label-spacing)
21724 (length (number-to-string number)))))
21725 (concat (make-string leading-spaces ? )
21726 (number-to-string number))))
21732 (defun graph-body-print (numbers-list height symbol-width)
21733 "Print a bar graph of the NUMBERS-LIST.
21734 The numbers-list consists of the Y-axis values.
21735 HEIGHT is maximum height of graph.
21736 SYMBOL-WIDTH is number of each column."
21739 (let (from-position)
21740 (while numbers-list
21741 (setq from-position (point))
21743 (column-of-graph height (car numbers-list)))
21744 (goto-char from-position)
21745 (forward-char symbol-width)
21748 ;; @r{Draw graph column by column.}
21750 (setq numbers-list (cdr numbers-list)))
21751 ;; @r{Place point for X axis labels.}
21752 (forward-line height)
21759 (defun Y-axis-column
21760 (height width-of-label &optional vertical-step)
21761 "Construct list of labels for Y axis.
21762 HEIGHT is maximum height of graph.
21763 WIDTH-OF-LABEL is maximum width of label.
21766 VERTICAL-STEP, an option, is a positive integer
21767 that specifies how much a Y axis label increments
21768 for each line. For example, a step of 5 means
21769 that each line is five units of the graph."
21771 (number-per-line (or vertical-step 1)))
21774 (while (> height 1)
21775 (if (zerop (% height Y-axis-label-spacing))
21776 ;; @r{Insert label.}
21780 (* height number-per-line)
21785 ;; @r{Else, insert blanks.}
21788 (make-string width-of-label ? )
21790 (setq height (1- height)))
21793 ;; @r{Insert base line.}
21794 (setq Y-axis (cons (Y-axis-element
21795 (or vertical-step 1)
21798 (nreverse Y-axis)))
21804 (defun print-X-axis-numbered-line
21805 (number-of-X-tics X-axis-leading-spaces
21806 &optional horizontal-step)
21807 "Print line of X-axis numbers"
21808 (let ((number X-axis-label-spacing)
21809 (horizontal-step (or horizontal-step 1)))
21812 (insert X-axis-leading-spaces)
21814 (delete-char (- (1- (length (number-to-string horizontal-step)))))
21817 ;; @r{Insert white space up to next number.}
21818 (- (* symbol-width X-axis-label-spacing)
21819 (1- (length (number-to-string horizontal-step)))
21822 (number-to-string (* number horizontal-step))))
21825 ;; @r{Insert remaining numbers.}
21826 (setq number (+ number X-axis-label-spacing))
21827 (while (> number-of-X-tics 1)
21828 (insert (X-axis-element (* number horizontal-step)))
21829 (setq number (+ number X-axis-label-spacing))
21830 (setq number-of-X-tics (1- number-of-X-tics)))))
21836 (defun print-X-axis (numbers-list horizontal-step)
21837 "Print X axis labels to length of NUMBERS-LIST.
21838 Optionally, HORIZONTAL-STEP, a positive integer,
21839 specifies how much an X axis label increments for
21843 ;; Value of symbol-width and full-Y-label-width
21844 ;; are passed by `print-graph'.
21845 (let* ((leading-spaces
21846 (make-string full-Y-label-width ? ))
21847 ;; symbol-width @r{is provided by} graph-body-print
21848 (tic-width (* symbol-width X-axis-label-spacing))
21849 (X-length (length numbers-list))
21855 ;; @r{Make a string of blanks.}
21856 (- (* symbol-width X-axis-label-spacing)
21857 (length X-axis-tic-symbol))
21861 ;; @r{Concatenate blanks with tic symbol.}
21862 X-axis-tic-symbol))
21864 (if (zerop (% X-length tic-width))
21865 (/ X-length tic-width)
21866 (1+ (/ X-length tic-width)))))
21870 (print-X-axis-tic-line
21871 tic-number leading-spaces X-tic)
21873 (print-X-axis-numbered-line
21874 tic-number leading-spaces horizontal-step)))
21880 (defun one-fiftieth (full-range)
21881 "Return list, each number of which is 1/50th previous."
21882 (mapcar '(lambda (arg) (/ arg 50)) full-range))
21889 (numbers-list &optional vertical-step horizontal-step)
21890 "Print labelled bar graph of the NUMBERS-LIST.
21891 The numbers-list consists of the Y-axis values.
21895 Optionally, VERTICAL-STEP, a positive integer,
21896 specifies how much a Y axis label increments for
21897 each line. For example, a step of 5 means that
21898 each row is five units.
21902 Optionally, HORIZONTAL-STEP, a positive integer,
21903 specifies how much an X axis label increments for
21905 (let* ((symbol-width (length graph-blank))
21906 ;; @code{height} @r{is both the largest number}
21907 ;; @r{and the number with the most digits.}
21908 (height (apply 'max numbers-list))
21911 (height-of-top-line
21912 (if (zerop (% height Y-axis-label-spacing))
21915 (* (1+ (/ height Y-axis-label-spacing))
21916 Y-axis-label-spacing)))
21919 (vertical-step (or vertical-step 1))
21920 (full-Y-label-width
21924 (* height-of-top-line vertical-step))
21930 height-of-top-line full-Y-label-width vertical-step)
21932 numbers-list height-of-top-line symbol-width)
21933 (print-X-axis numbers-list horizontal-step)))
21940 @node Final printed graph, , Another Bug, Print Whole Graph
21941 @appendixsubsec The Printed Graph
21943 When made and installed, you can call the @code{print-graph} command
21949 (print-graph fiftieth-list-for-graph 50 10)
21979 50 - ***************** * *
21981 10 50 100 150 200 250 300 350
21988 The largest group of functions contain 10 -- 19 words and symbols each.
21990 @node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top
21991 @appendix Free Software and Free Manuals
21993 @strong{by Richard M. Stallman}
21996 The biggest deficiency in free operating systems is not in the
21997 software---it is the lack of good free manuals that we can include in
21998 these systems. Many of our most important programs do not come with
21999 full manuals. Documentation is an essential part of any software
22000 package; when an important free software package does not come with a
22001 free manual, that is a major gap. We have many such gaps today.
22003 Once upon a time, many years ago, I thought I would learn Perl. I got
22004 a copy of a free manual, but I found it hard to read. When I asked
22005 Perl users about alternatives, they told me that there were better
22006 introductory manuals---but those were not free.
22008 Why was this? The authors of the good manuals had written them for
22009 O'Reilly Associates, which published them with restrictive terms---no
22010 copying, no modification, source files not available---which exclude
22011 them from the free software community.
22013 That wasn't the first time this sort of thing has happened, and (to
22014 our community's great loss) it was far from the last. Proprietary
22015 manual publishers have enticed a great many authors to restrict their
22016 manuals since then. Many times I have heard a GNU user eagerly tell me
22017 about a manual that he is writing, with which he expects to help the
22018 GNU project---and then had my hopes dashed, as he proceeded to explain
22019 that he had signed a contract with a publisher that would restrict it
22020 so that we cannot use it.
22022 Given that writing good English is a rare skill among programmers, we
22023 can ill afford to lose manuals this way.
22026 (The Free Software Foundation
22027 @uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, ,
22028 sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html,
22029 GNU manuals}, too.)
22031 Free documentation, like free software, is a matter of freedom, not
22032 price. The problem with these manuals was not that O'Reilly Associates
22033 charged a price for printed copies---that in itself is fine. (The Free
22034 Software Foundation sells printed copies of free GNU manuals, too.)
22035 But GNU manuals are available in source code form, while these manuals
22036 are available only on paper. GNU manuals come with permission to copy
22037 and modify; the Perl manuals do not. These restrictions are the
22040 The criterion for a free manual is pretty much the same as for free
22041 software: it is a matter of giving all users certain
22042 freedoms. Redistribution (including commercial redistribution) must be
22043 permitted, so that the manual can accompany every copy of the program,
22044 on-line or on paper. Permission for modification is crucial too.
22046 As a general rule, I don't believe that it is essential for people to
22047 have permission to modify all sorts of articles and books. The issues
22048 for writings are not necessarily the same as those for software. For
22049 example, I don't think you or I are obliged to give permission to
22050 modify articles like this one, which describe our actions and our
22053 But there is a particular reason why the freedom to modify is crucial
22054 for documentation for free software. When people exercise their right
22055 to modify the software, and add or change its features, if they are
22056 conscientious they will change the manual too---so they can provide
22057 accurate and usable documentation with the modified program. A manual
22058 which forbids programmers to be conscientious and finish the job, or
22059 more precisely requires them to write a new manual from scratch if
22060 they change the program, does not fill our community's needs.
22062 While a blanket prohibition on modification is unacceptable, some
22063 kinds of limits on the method of modification pose no problem. For
22064 example, requirements to preserve the original author's copyright
22065 notice, the distribution terms, or the list of authors, are ok. It is
22066 also no problem to require modified versions to include notice that
22067 they were modified, even to have entire sections that may not be
22068 deleted or changed, as long as these sections deal with nontechnical
22069 topics. (Some GNU manuals have them.)
22071 These kinds of restrictions are not a problem because, as a practical
22072 matter, they don't stop the conscientious programmer from adapting the
22073 manual to fit the modified program. In other words, they don't block
22074 the free software community from making full use of the manual.
22076 However, it must be possible to modify all the technical content of
22077 the manual, and then distribute the result in all the usual media,
22078 through all the usual channels; otherwise, the restrictions do block
22079 the community, the manual is not free, and so we need another manual.
22081 Unfortunately, it is often hard to find someone to write another
22082 manual when a proprietary manual exists. The obstacle is that many
22083 users think that a proprietary manual is good enough---so they don't
22084 see the need to write a free manual. They do not see that the free
22085 operating system has a gap that needs filling.
22087 Why do users think that proprietary manuals are good enough? Some have
22088 not considered the issue. I hope this article will do something to
22091 Other users consider proprietary manuals acceptable for the same
22092 reason so many people consider proprietary software acceptable: they
22093 judge in purely practical terms, not using freedom as a
22094 criterion. These people are entitled to their opinions, but since
22095 those opinions spring from values which do not include freedom, they
22096 are no guide for those of us who do value freedom.
22098 Please spread the word about this issue. We continue to lose manuals
22099 to proprietary publishing. If we spread the word that proprietary
22100 manuals are not sufficient, perhaps the next person who wants to help
22101 GNU by writing documentation will realize, before it is too late, that
22102 he must above all make it free.
22104 We can also encourage commercial publishers to sell free, copylefted
22105 manuals instead of proprietary ones. One way you can help this is to
22106 check the distribution terms of a manual before you buy it, and prefer
22107 copylefted manuals to non-copylefted ones.
22111 Note: The Free Software Foundation maintains a page on its Web site
22112 that lists free books available from other publishers:@*
22113 @uref{http://www.gnu.org/doc/other-free-books.html}
22115 @node GNU Free Documentation License, Index, Free Software and Free Manuals, Top
22116 @appendix GNU Free Documentation License
22118 @cindex FDL, GNU Free Documentation License
22119 @center Version 1.2, November 2002
22122 Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
22123 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
22125 Everyone is permitted to copy and distribute verbatim copies
22126 of this license document, but changing it is not allowed.
22133 The purpose of this License is to make a manual, textbook, or other
22134 functional and useful document @dfn{free} in the sense of freedom: to
22135 assure everyone the effective freedom to copy and redistribute it,
22136 with or without modifying it, either commercially or noncommercially.
22137 Secondarily, this License preserves for the author and publisher a way
22138 to get credit for their work, while not being considered responsible
22139 for modifications made by others.
22141 This License is a kind of ``copyleft'', which means that derivative
22142 works of the document must themselves be free in the same sense. It
22143 complements the GNU General Public License, which is a copyleft
22144 license designed for free software.
22146 We have designed this License in order to use it for manuals for free
22147 software, because free software needs free documentation: a free
22148 program should come with manuals providing the same freedoms that the
22149 software does. But this License is not limited to software manuals;
22150 it can be used for any textual work, regardless of subject matter or
22151 whether it is published as a printed book. We recommend this License
22152 principally for works whose purpose is instruction or reference.
22155 APPLICABILITY AND DEFINITIONS
22157 This License applies to any manual or other work, in any medium, that
22158 contains a notice placed by the copyright holder saying it can be
22159 distributed under the terms of this License. Such a notice grants a
22160 world-wide, royalty-free license, unlimited in duration, to use that
22161 work under the conditions stated herein. The ``Document'', below,
22162 refers to any such manual or work. Any member of the public is a
22163 licensee, and is addressed as ``you''. You accept the license if you
22164 copy, modify or distribute the work in a way requiring permission
22165 under copyright law.
22167 A ``Modified Version'' of the Document means any work containing the
22168 Document or a portion of it, either copied verbatim, or with
22169 modifications and/or translated into another language.
22171 A ``Secondary Section'' is a named appendix or a front-matter section
22172 of the Document that deals exclusively with the relationship of the
22173 publishers or authors of the Document to the Document's overall
22174 subject (or to related matters) and contains nothing that could fall
22175 directly within that overall subject. (Thus, if the Document is in
22176 part a textbook of mathematics, a Secondary Section may not explain
22177 any mathematics.) The relationship could be a matter of historical
22178 connection with the subject or with related matters, or of legal,
22179 commercial, philosophical, ethical or political position regarding
22182 The ``Invariant Sections'' are certain Secondary Sections whose titles
22183 are designated, as being those of Invariant Sections, in the notice
22184 that says that the Document is released under this License. If a
22185 section does not fit the above definition of Secondary then it is not
22186 allowed to be designated as Invariant. The Document may contain zero
22187 Invariant Sections. If the Document does not identify any Invariant
22188 Sections then there are none.
22190 The ``Cover Texts'' are certain short passages of text that are listed,
22191 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
22192 the Document is released under this License. A Front-Cover Text may
22193 be at most 5 words, and a Back-Cover Text may be at most 25 words.
22195 A ``Transparent'' copy of the Document means a machine-readable copy,
22196 represented in a format whose specification is available to the
22197 general public, that is suitable for revising the document
22198 straightforwardly with generic text editors or (for images composed of
22199 pixels) generic paint programs or (for drawings) some widely available
22200 drawing editor, and that is suitable for input to text formatters or
22201 for automatic translation to a variety of formats suitable for input
22202 to text formatters. A copy made in an otherwise Transparent file
22203 format whose markup, or absence of markup, has been arranged to thwart
22204 or discourage subsequent modification by readers is not Transparent.
22205 An image format is not Transparent if used for any substantial amount
22206 of text. A copy that is not ``Transparent'' is called ``Opaque''.
22208 Examples of suitable formats for Transparent copies include plain
22209 @sc{ascii} without markup, Texinfo input format, La@TeX{} input
22210 format, @acronym{SGML} or @acronym{XML} using a publicly available
22211 @acronym{DTD}, and standard-conforming simple @acronym{HTML},
22212 PostScript or @acronym{PDF} designed for human modification. Examples
22213 of transparent image formats include @acronym{PNG}, @acronym{XCF} and
22214 @acronym{JPG}. Opaque formats include proprietary formats that can be
22215 read and edited only by proprietary word processors, @acronym{SGML} or
22216 @acronym{XML} for which the @acronym{DTD} and/or processing tools are
22217 not generally available, and the machine-generated @acronym{HTML},
22218 PostScript or @acronym{PDF} produced by some word processors for
22219 output purposes only.
22221 The ``Title Page'' means, for a printed book, the title page itself,
22222 plus such following pages as are needed to hold, legibly, the material
22223 this License requires to appear in the title page. For works in
22224 formats which do not have any title page as such, ``Title Page'' means
22225 the text near the most prominent appearance of the work's title,
22226 preceding the beginning of the body of the text.
22228 A section ``Entitled XYZ'' means a named subunit of the Document whose
22229 title either is precisely XYZ or contains XYZ in parentheses following
22230 text that translates XYZ in another language. (Here XYZ stands for a
22231 specific section name mentioned below, such as ``Acknowledgements'',
22232 ``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
22233 of such a section when you modify the Document means that it remains a
22234 section ``Entitled XYZ'' according to this definition.
22236 The Document may include Warranty Disclaimers next to the notice which
22237 states that this License applies to the Document. These Warranty
22238 Disclaimers are considered to be included by reference in this
22239 License, but only as regards disclaiming warranties: any other
22240 implication that these Warranty Disclaimers may have is void and has
22241 no effect on the meaning of this License.
22246 You may copy and distribute the Document in any medium, either
22247 commercially or noncommercially, provided that this License, the
22248 copyright notices, and the license notice saying this License applies
22249 to the Document are reproduced in all copies, and that you add no other
22250 conditions whatsoever to those of this License. You may not use
22251 technical measures to obstruct or control the reading or further
22252 copying of the copies you make or distribute. However, you may accept
22253 compensation in exchange for copies. If you distribute a large enough
22254 number of copies you must also follow the conditions in section 3.
22256 You may also lend copies, under the same conditions stated above, and
22257 you may publicly display copies.
22260 COPYING IN QUANTITY
22262 If you publish printed copies (or copies in media that commonly have
22263 printed covers) of the Document, numbering more than 100, and the
22264 Document's license notice requires Cover Texts, you must enclose the
22265 copies in covers that carry, clearly and legibly, all these Cover
22266 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
22267 the back cover. Both covers must also clearly and legibly identify
22268 you as the publisher of these copies. The front cover must present
22269 the full title with all words of the title equally prominent and
22270 visible. You may add other material on the covers in addition.
22271 Copying with changes limited to the covers, as long as they preserve
22272 the title of the Document and satisfy these conditions, can be treated
22273 as verbatim copying in other respects.
22275 If the required texts for either cover are too voluminous to fit
22276 legibly, you should put the first ones listed (as many as fit
22277 reasonably) on the actual cover, and continue the rest onto adjacent
22280 If you publish or distribute Opaque copies of the Document numbering
22281 more than 100, you must either include a machine-readable Transparent
22282 copy along with each Opaque copy, or state in or with each Opaque copy
22283 a computer-network location from which the general network-using
22284 public has access to download using public-standard network protocols
22285 a complete Transparent copy of the Document, free of added material.
22286 If you use the latter option, you must take reasonably prudent steps,
22287 when you begin distribution of Opaque copies in quantity, to ensure
22288 that this Transparent copy will remain thus accessible at the stated
22289 location until at least one year after the last time you distribute an
22290 Opaque copy (directly or through your agents or retailers) of that
22291 edition to the public.
22293 It is requested, but not required, that you contact the authors of the
22294 Document well before redistributing any large number of copies, to give
22295 them a chance to provide you with an updated version of the Document.
22300 You may copy and distribute a Modified Version of the Document under
22301 the conditions of sections 2 and 3 above, provided that you release
22302 the Modified Version under precisely this License, with the Modified
22303 Version filling the role of the Document, thus licensing distribution
22304 and modification of the Modified Version to whoever possesses a copy
22305 of it. In addition, you must do these things in the Modified Version:
22309 Use in the Title Page (and on the covers, if any) a title distinct
22310 from that of the Document, and from those of previous versions
22311 (which should, if there were any, be listed in the History section
22312 of the Document). You may use the same title as a previous version
22313 if the original publisher of that version gives permission.
22316 List on the Title Page, as authors, one or more persons or entities
22317 responsible for authorship of the modifications in the Modified
22318 Version, together with at least five of the principal authors of the
22319 Document (all of its principal authors, if it has fewer than five),
22320 unless they release you from this requirement.
22323 State on the Title page the name of the publisher of the
22324 Modified Version, as the publisher.
22327 Preserve all the copyright notices of the Document.
22330 Add an appropriate copyright notice for your modifications
22331 adjacent to the other copyright notices.
22334 Include, immediately after the copyright notices, a license notice
22335 giving the public permission to use the Modified Version under the
22336 terms of this License, in the form shown in the Addendum below.
22339 Preserve in that license notice the full lists of Invariant Sections
22340 and required Cover Texts given in the Document's license notice.
22343 Include an unaltered copy of this License.
22346 Preserve the section Entitled ``History'', Preserve its Title, and add
22347 to it an item stating at least the title, year, new authors, and
22348 publisher of the Modified Version as given on the Title Page. If
22349 there is no section Entitled ``History'' in the Document, create one
22350 stating the title, year, authors, and publisher of the Document as
22351 given on its Title Page, then add an item describing the Modified
22352 Version as stated in the previous sentence.
22355 Preserve the network location, if any, given in the Document for
22356 public access to a Transparent copy of the Document, and likewise
22357 the network locations given in the Document for previous versions
22358 it was based on. These may be placed in the ``History'' section.
22359 You may omit a network location for a work that was published at
22360 least four years before the Document itself, or if the original
22361 publisher of the version it refers to gives permission.
22364 For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
22365 the Title of the section, and preserve in the section all the
22366 substance and tone of each of the contributor acknowledgements and/or
22367 dedications given therein.
22370 Preserve all the Invariant Sections of the Document,
22371 unaltered in their text and in their titles. Section numbers
22372 or the equivalent are not considered part of the section titles.
22375 Delete any section Entitled ``Endorsements''. Such a section
22376 may not be included in the Modified Version.
22379 Do not retitle any existing section to be Entitled ``Endorsements'' or
22380 to conflict in title with any Invariant Section.
22383 Preserve any Warranty Disclaimers.
22386 If the Modified Version includes new front-matter sections or
22387 appendices that qualify as Secondary Sections and contain no material
22388 copied from the Document, you may at your option designate some or all
22389 of these sections as invariant. To do this, add their titles to the
22390 list of Invariant Sections in the Modified Version's license notice.
22391 These titles must be distinct from any other section titles.
22393 You may add a section Entitled ``Endorsements'', provided it contains
22394 nothing but endorsements of your Modified Version by various
22395 parties---for example, statements of peer review or that the text has
22396 been approved by an organization as the authoritative definition of a
22399 You may add a passage of up to five words as a Front-Cover Text, and a
22400 passage of up to 25 words as a Back-Cover Text, to the end of the list
22401 of Cover Texts in the Modified Version. Only one passage of
22402 Front-Cover Text and one of Back-Cover Text may be added by (or
22403 through arrangements made by) any one entity. If the Document already
22404 includes a cover text for the same cover, previously added by you or
22405 by arrangement made by the same entity you are acting on behalf of,
22406 you may not add another; but you may replace the old one, on explicit
22407 permission from the previous publisher that added the old one.
22409 The author(s) and publisher(s) of the Document do not by this License
22410 give permission to use their names for publicity for or to assert or
22411 imply endorsement of any Modified Version.
22414 COMBINING DOCUMENTS
22416 You may combine the Document with other documents released under this
22417 License, under the terms defined in section 4 above for modified
22418 versions, provided that you include in the combination all of the
22419 Invariant Sections of all of the original documents, unmodified, and
22420 list them all as Invariant Sections of your combined work in its
22421 license notice, and that you preserve all their Warranty Disclaimers.
22423 The combined work need only contain one copy of this License, and
22424 multiple identical Invariant Sections may be replaced with a single
22425 copy. If there are multiple Invariant Sections with the same name but
22426 different contents, make the title of each such section unique by
22427 adding at the end of it, in parentheses, the name of the original
22428 author or publisher of that section if known, or else a unique number.
22429 Make the same adjustment to the section titles in the list of
22430 Invariant Sections in the license notice of the combined work.
22432 In the combination, you must combine any sections Entitled ``History''
22433 in the various original documents, forming one section Entitled
22434 ``History''; likewise combine any sections Entitled ``Acknowledgements'',
22435 and any sections Entitled ``Dedications''. You must delete all
22436 sections Entitled ``Endorsements.''
22439 COLLECTIONS OF DOCUMENTS
22441 You may make a collection consisting of the Document and other documents
22442 released under this License, and replace the individual copies of this
22443 License in the various documents with a single copy that is included in
22444 the collection, provided that you follow the rules of this License for
22445 verbatim copying of each of the documents in all other respects.
22447 You may extract a single document from such a collection, and distribute
22448 it individually under this License, provided you insert a copy of this
22449 License into the extracted document, and follow this License in all
22450 other respects regarding verbatim copying of that document.
22453 AGGREGATION WITH INDEPENDENT WORKS
22455 A compilation of the Document or its derivatives with other separate
22456 and independent documents or works, in or on a volume of a storage or
22457 distribution medium, is called an ``aggregate'' if the copyright
22458 resulting from the compilation is not used to limit the legal rights
22459 of the compilation's users beyond what the individual works permit.
22460 When the Document is included in an aggregate, this License does not
22461 apply to the other works in the aggregate which are not themselves
22462 derivative works of the Document.
22464 If the Cover Text requirement of section 3 is applicable to these
22465 copies of the Document, then if the Document is less than one half of
22466 the entire aggregate, the Document's Cover Texts may be placed on
22467 covers that bracket the Document within the aggregate, or the
22468 electronic equivalent of covers if the Document is in electronic form.
22469 Otherwise they must appear on printed covers that bracket the whole
22475 Translation is considered a kind of modification, so you may
22476 distribute translations of the Document under the terms of section 4.
22477 Replacing Invariant Sections with translations requires special
22478 permission from their copyright holders, but you may include
22479 translations of some or all Invariant Sections in addition to the
22480 original versions of these Invariant Sections. You may include a
22481 translation of this License, and all the license notices in the
22482 Document, and any Warranty Disclaimers, provided that you also include
22483 the original English version of this License and the original versions
22484 of those notices and disclaimers. In case of a disagreement between
22485 the translation and the original version of this License or a notice
22486 or disclaimer, the original version will prevail.
22488 If a section in the Document is Entitled ``Acknowledgements'',
22489 ``Dedications'', or ``History'', the requirement (section 4) to Preserve
22490 its Title (section 1) will typically require changing the actual
22496 You may not copy, modify, sublicense, or distribute the Document except
22497 as expressly provided for under this License. Any other attempt to
22498 copy, modify, sublicense or distribute the Document is void, and will
22499 automatically terminate your rights under this License. However,
22500 parties who have received copies, or rights, from you under this
22501 License will not have their licenses terminated so long as such
22502 parties remain in full compliance.
22505 FUTURE REVISIONS OF THIS LICENSE
22507 The Free Software Foundation may publish new, revised versions
22508 of the GNU Free Documentation License from time to time. Such new
22509 versions will be similar in spirit to the present version, but may
22510 differ in detail to address new problems or concerns. See
22511 @uref{http://www.gnu.org/copyleft/}.
22513 Each version of the License is given a distinguishing version number.
22514 If the Document specifies that a particular numbered version of this
22515 License ``or any later version'' applies to it, you have the option of
22516 following the terms and conditions either of that specified version or
22517 of any later version that has been published (not as a draft) by the
22518 Free Software Foundation. If the Document does not specify a version
22519 number of this License, you may choose any version ever published (not
22520 as a draft) by the Free Software Foundation.
22524 @appendixsubsec ADDENDUM: How to use this License for your documents
22526 To use this License in a document you have written, include a copy of
22527 the License in the document and put the following copyright and
22528 license notices just after the title page:
22532 Copyright (C) @var{year} @var{your name}.
22533 Permission is granted to copy, distribute and/or modify this document
22534 under the terms of the GNU Free Documentation License, Version 1.2
22535 or any later version published by the Free Software Foundation;
22536 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
22537 A copy of the license is included in the section entitled ``GNU
22538 Free Documentation License''.
22542 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
22543 replace the ``with...Texts.'' line with this:
22547 with the Invariant Sections being @var{list their titles}, with
22548 the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
22553 If you have Invariant Sections without Cover Texts, or some other
22554 combination of the three, merge those two alternatives to suit the
22557 If your document contains nontrivial examples of program code, we
22558 recommend releasing these examples in parallel under your choice of
22559 free software license, such as the GNU General Public License,
22560 to permit their use in free software.
22562 @node Index, About the Author, GNU Free Documentation License, Top
22563 @comment node-name, next, previous, up
22567 MENU ENTRY: NODE NAME.
22573 @c Place biographical information on right-hand (verso) page
22577 \par\vfill\supereject
22578 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
22579 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
22582 \par\vfill\supereject
22583 \par\vfill\supereject
22584 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
22585 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
22594 @c ================ Biographical information ================
22598 @center About the Author
22603 @node About the Author, , Index, Top
22604 @unnumbered About the Author
22608 Robert J. Chassell has worked with GNU Emacs since 1985. He writes
22609 and edits, teaches Emacs and Emacs Lisp, and speaks throughout the
22610 world on software freedom. Chassell was a founding Director and
22611 Treasurer of the Free Software Foundation, Inc. He is co-author of
22612 the @cite{Texinfo} manual, and has edited more than a dozen other
22613 books. He graduated from Cambridge University, in England. He has an
22614 abiding interest in social and economic history and flies his own
22621 @c Prevent page number on blank verso, so eject it first.
22623 \par\vfill\supereject
22628 @evenheading @thispage @| @| @thistitle
22629 @oddheading @| @| @thispage
22635 arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf