Mercurial > emacs
changeset 83932:b9810e4e9906
Move to ../doc/lispintro
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 03:58:07 +0000 |
| parents | 92cfbaf16dd9 |
| children | 909c429adf41 |
| files | lispintro/emacs-lisp-intro.texi |
| diffstat | 1 files changed, 0 insertions(+), 22721 deletions(-) [+] |
line wrap: on
line diff
--- a/lispintro/emacs-lisp-intro.texi Thu Sep 06 03:58:01 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,22721 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename ../info/eintr -@c setfilename emacs-lisp-intro.info -@c sethtmlfilename emacs-lisp-intro.html -@settitle Programming in Emacs Lisp -@syncodeindex vr cp -@syncodeindex fn cp -@setchapternewpage odd -@finalout - -@c --------- -@c <<<< For hard copy printing, this file is now -@c set for smallbook, which works for all sizes -@c of paper, and with Postscript figures >>>> -@smallbook -@clear largebook -@set print-postscript-figures -@c set largebook -@c clear print-postscript-figures -@c --------- - -@comment %**end of header - -@set edition-number 3.07 -@set update-date 9 November 2006 - -@ignore - ## Summary of shell commands to create various output formats: - - pushd /usr/local/src/emacs/lispintro/ - ## pushd /u/intro/ - - ## Info output - makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi - - ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/usr/local/src/emacs/info/eintr")) - - ## DVI output - texi2dvi emacs-lisp-intro.texi - - ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi & - - ## HTML output - makeinfo --html --no-split --verbose emacs-lisp-intro.texi - - ## galeon emacs-lisp-intro.html - - ## Plain text output - makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ - --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi - - popd - -# as user `root' -# insert thumbdrive - mtusb # mount -v -t ext3 /dev/sda /mnt - cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi - umtusb # umount -v /mnt -# remove thumbdrive - - ## Other shell commands - - pushd /usr/local/src/emacs/lispintro/ - ## pushd /u/intro/ - - ## PDF - texi2dvi --pdf emacs-lisp-intro.texi - # xpdf emacs-lisp-intro.pdf & - - ## DocBook -- note file extension - makeinfo --docbook --no-split --paragraph-indent=0 \ - --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi - - ## XML with a Texinfo DTD -- note file extension - makeinfo --xml --no-split --paragraph-indent=0 \ - --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi - - ## PostScript (needs DVI) - # gv emacs-lisp-intro.ps & - # Create DVI if we lack it - # texi2dvi emacs-lisp-intro.texi - dvips emacs-lisp-intro.dvi -o emacs-lisp-intro.ps - - ## RTF (needs HTML) - # Use OpenOffice to view RTF - # Create HTML if we lack it - # makeinfo --no-split --html emacs-lisp-intro.texi - /usr/local/src/html2rtf.pl emacs-lisp-intro.html - - ## LaTeX (needs RTF) - /usr/bin/rtf2latex emacs-lisp-intro.rtf - - popd - -@end ignore - -@c ================ Included Figures ================ - -@c Set print-postscript-figures if you print PostScript figures. -@c If you clear this, the ten figures will be printed as ASCII diagrams. -@c (This is not relevant to Info, since Info only handles ASCII.) -@c Your site may require editing changes to print PostScript; in this -@c case, search for `print-postscript-figures' and make appropriate changes. - -@c ================ How to Create an Info file ================ - -@c If you have `makeinfo' installed, run the following command - -@c makeinfo emacs-lisp-intro.texi - -@c or, if you want a single, large Info file, and no paragraph indents: -@c makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi - -@c After creating the Info file, edit your Info `dir' file, if the -@c `dircategory' section below does not enable your system to -@c install the manual automatically. -@c (The `dir' file is often in the `/usr/local/share/info/' directory.) - -@c ================ How to Create an HTML file ================ - -@c To convert to HTML format -@c makeinfo --html --no-split --verbose emacs-lisp-intro.texi - -@c ================ How to Print a Book in Various Sizes ================ - -@c This book can be printed in any of three different sizes. -@c In the above header, set @-commands appropriately. - -@c 7 by 9.25 inches: -@c @smallbook -@c @clear largebook - -@c 8.5 by 11 inches: -@c @c smallbook -@c @set largebook - -@c European A4 size paper: -@c @c smallbook -@c @afourpaper -@c @set largebook - -@c ================ How to Typeset and Print ================ - -@c If you do not include PostScript figures, run either of the -@c following command sequences, or similar commands suited to your -@c system: - -@c texi2dvi emacs-lisp-intro.texi -@c lpr -d emacs-lisp-intro.dvi - -@c or else: - -@c tex emacs-lisp-intro.texi -@c texindex emacs-lisp-intro.?? -@c tex emacs-lisp-intro.texi -@c lpr -d emacs-lisp-intro.dvi - -@c If you include the PostScript figures, and you have old software, -@c you may need to convert the .dvi file to a .ps file before -@c printing. Run either of the following command sequences, or one -@c similar: -@c -@c dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps -@c -@c or else: -@c -@c postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps -@c - -@c (Note: if you edit the book so as to change the length of the -@c table of contents, you may have to change the value of `pageno' below.) - -@c ================ End of Formatting Sections ================ - -@c For next or subsequent edition: -@c create function using with-output-to-temp-buffer -@c create a major mode, with keymaps -@c run an asynchronous process, like grep or diff - -@c For 8.5 by 11 inch format: do not use such a small amount of -@c whitespace between paragraphs as smallbook format -@ifset largebook -@tex -\global\parskip 6pt plus 1pt -@end tex -@end ifset - -@c For all sized formats: print within-book cross -@c reference with ``...'' rather than [...] - -@c This works with the texinfo.tex file, version 2003-05-04.08, -@c in the Texinfo version 4.6 of the 2003 Jun 13 distribution. - -@tex -\if \xrefprintnodename - \global\def\xrefprintnodename#1{\unskip, ``#1''} - \else - \global\def\xrefprintnodename#1{ ``#1''} -\fi -% \global\def\xrefprintnodename#1{, ``#1''} -@end tex - -@c ---------------------------------------------------- - -@dircategory Emacs -@direntry -* Emacs Lisp Intro: (eintr). - A simple introduction to Emacs Lisp programming. -@end direntry - -@copying -This is an @cite{Introduction to Programming in Emacs Lisp}, for -people who are not programmers. -@sp 1 -Edition @value{edition-number}, @value{update-date} -@sp 1 -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, - 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@sp 1 - -@iftex -Published by the:@* - -GNU Press, @hfill @uref{http://www.gnupress.org}@* -a division of the @hfill General: @email{press@@gnu.org}@* -Free Software Foundation, Inc. @hfill Orders:@w{ } @email{sales@@gnu.org}@* -51 Franklin Street, Fifth Floor @hfill Tel: +1 (617) 542-5942@* -Boston, MA 02110-1301 USA @hfill Fax: +1 (617) 542-2652@* -@end iftex - -@ifnottex -Published by the: - -@example -GNU Press, Website: http://www.gnupress.org -a division of the General: press@@gnu.org -Free Software Foundation, Inc. Orders: sales@@gnu.org -51 Franklin Street, Fifth Floor Tel: +1 (617) 542-5942 -Boston, MA 02110-1301 USA Fax: +1 (617) 542-2652 -@end example -@end ifnottex - -@sp 1 -@c Printed copies are available for $30 each.@* -ISBN 1-882114-43-4 - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; there -being no Invariant Section, with the Front-Cover Texts being ``A GNU -Manual'', and with the Back-Cover Texts as in (a) below. A copy of -the license is included in the section entitled ``GNU Free -Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have freedom to copy and -modify this GNU Manual, like GNU software. Copies published by the -Free Software Foundation raise funds for GNU development.'' -@end copying - -@c half title; two lines here, so do not use `shorttitlepage' -@tex -{\begingroup% - \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}% - \endgroup}% -{\begingroup\hbox{}\vskip 0.25in \chaprm% - \centerline{Programming in Emacs Lisp}% - \endgroup\page\hbox{}\page} -@end tex - -@titlepage -@sp 6 -@center @titlefont{An Introduction to} -@sp 2 -@center @titlefont{Programming in Emacs Lisp} -@sp 2 -@center Revised Third Edition -@sp 4 -@center by Robert J. Chassell - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@iftex -@headings off -@evenheading @thispage @| @| @thischapter -@oddheading @thissection @| @| @thispage -@end iftex - -@ifnothtml -@c Keep T.O.C. short by tightening up for largebook -@ifset largebook -@tex -\global\parskip 2pt plus 1pt -\global\advance\baselineskip by -1pt -@end tex -@end ifset -@end ifnothtml - -@shortcontents -@contents - -@ifnottex -@node Top, Preface, (dir), (dir) -@top An Introduction to Programming in Emacs Lisp - -@insertcopying - -This master menu first lists each chapter and index; then it lists -every node in every chapter. -@end ifnottex - -@c >>>> Set pageno appropriately <<<< - -@c The first page of the Preface is a roman numeral; it is the first -@c right handed page after the Table of Contents; hence the following -@c setting must be for an odd negative number. - -@iftex -@global@pageno = -11 -@end iftex - -@menu -* Preface:: What to look for. -* List Processing:: What is Lisp? -* Practicing Evaluation:: Running several programs. -* Writing Defuns:: How to write function definitions. -* Buffer Walk Through:: Exploring a few buffer-related functions. -* More Complex:: A few, even more complex functions. -* Narrowing & Widening:: Restricting your and Emacs attention to - a region. -* car cdr & cons:: Fundamental functions in Lisp. -* Cutting & Storing Text:: Removing text and saving it. -* List Implementation:: How lists are implemented in the computer. -* Yanking:: Pasting stored text. -* Loops & Recursion:: How to repeat a process. -* Regexp Search:: Regular expression searches. -* Counting Words:: A review of repetition and regexps. -* Words in a defun:: Counting words in a @code{defun}. -* Readying a Graph:: A prototype graph printing function. -* Emacs Initialization:: How to write a @file{.emacs} file. -* Debugging:: How to run the Emacs Lisp debuggers. -* Conclusion:: Now you have the basics. -* the-the:: An appendix: how to find reduplicated words. -* Kill Ring:: An appendix: how the kill ring works. -* Full Graph:: How to create a graph with labelled axes. -* Free Software and Free Manuals:: -* GNU Free Documentation License:: -* Index:: -* About the Author:: - -@detailmenu - --- The Detailed Node Listing --- - -Preface - -* Why:: Why learn Emacs Lisp? -* On Reading this Text:: Read, gain familiarity, pick up habits.... -* Who You Are:: For whom this is written. -* Lisp History:: -* Note for Novices:: You can read this as a novice. -* Thank You:: - -List Processing - -* Lisp Lists:: What are lists? -* Run a Program:: Any list in Lisp is a program ready to run. -* Making Errors:: Generating an error message. -* Names & Definitions:: Names of symbols and function definitions. -* Lisp Interpreter:: What the Lisp interpreter does. -* Evaluation:: Running a program. -* Variables:: Returning a value from a variable. -* Arguments:: Passing information to a function. -* set & setq:: Setting the value of a variable. -* Summary:: The major points. -* Error Message Exercises:: - -Lisp Lists - -* Numbers Lists:: List have numbers, other lists, in them. -* Lisp Atoms:: Elemental entities. -* Whitespace in Lists:: Formatting lists to be readable. -* Typing Lists:: How GNU Emacs helps you type lists. - -The Lisp Interpreter - -* Complications:: Variables, Special forms, Lists within. -* Byte Compiling:: Specially processing code for speed. - -Evaluation - -* How the Interpreter Acts:: Returns and Side Effects... -* Evaluating Inner Lists:: Lists within lists... - -Variables - -* fill-column Example:: -* Void Function:: The error message for a symbol - without a function. -* Void Variable:: The error message for a symbol without a value. - -Arguments - -* Data types:: Types of data passed to a function. -* Args as Variable or List:: An argument can be the value - of a variable or list. -* Variable Number of Arguments:: Some functions may take a - variable number of arguments. -* Wrong Type of Argument:: Passing an argument of the wrong type - to a function. -* message:: A useful function for sending messages. - -Setting the Value of a Variable - -* Using set:: Setting values. -* Using setq:: Setting a quoted value. -* Counting:: Using @code{setq} to count. - -Practicing Evaluation - -* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} - causes evaluation. -* Buffer Names:: Buffers and files are different. -* Getting Buffers:: Getting a buffer itself, not merely its name. -* Switching Buffers:: How to change to another buffer. -* Buffer Size & Locations:: Where point is located and the size of - the buffer. -* Evaluation Exercise:: - -How To Write Function Definitions - -* Primitive Functions:: -* defun:: The @code{defun} special form. -* Install:: Install a function definition. -* Interactive:: Making a function interactive. -* Interactive Options:: Different options for @code{interactive}. -* Permanent Installation:: Installing code permanently. -* let:: Creating and initializing local variables. -* if:: What if? -* else:: If--then--else expressions. -* Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. -* Review:: -* defun Exercises:: - -Install a Function Definition - -* Effect of installation:: -* Change a defun:: How to change a function definition. - -Make a Function Interactive - -* Interactive multiply-by-seven:: An overview. -* multiply-by-seven in detail:: The interactive version. - -@code{let} - -* Prevent confusion:: -* Parts of let Expression:: -* Sample let Expression:: -* Uninitialized let Variables:: - -The @code{if} Special Form - -* if in more detail:: -* type-of-animal in detail:: An example of an @code{if} expression. - -Truth and Falsehood in Emacs Lisp - -* nil explained:: @code{nil} has two meanings. - -@code{save-excursion} - -* Point and mark:: A review of various locations. -* Template for save-excursion:: - -A Few Buffer--Related Functions - -* Finding More:: How to find more information. -* simplified-beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. -* append-to-buffer:: Uses @code{save-excursion} and - @code{insert-buffer-substring}. -* Buffer Related Review:: Review. -* Buffer Exercises:: - -The Definition of @code{mark-whole-buffer} - -* mark-whole-buffer overview:: -* Body of mark-whole-buffer:: Only three lines of code. - -The Definition of @code{append-to-buffer} - -* append-to-buffer overview:: -* append interactive:: A two part interactive expression. -* append-to-buffer body:: Incorporates a @code{let} expression. -* append save-excursion:: How the @code{save-excursion} works. - -A Few More Complex Functions - -* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. -* insert-buffer:: Read-only, and with @code{or}. -* beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* Second Buffer Related Review:: -* optional Exercise:: - -The Definition of @code{insert-buffer} - -* insert-buffer code:: -* insert-buffer interactive:: When you can read, but not write. -* insert-buffer body:: The body has an @code{or} and a @code{let}. -* if & or:: Using an @code{if} instead of an @code{or}. -* Insert or:: How the @code{or} expression works. -* Insert let:: Two @code{save-excursion} expressions. -* New insert-buffer:: - -The Interactive Expression in @code{insert-buffer} - -* Read-only buffer:: When a buffer cannot be modified. -* b for interactive:: An existing buffer or else its name. - -Complete Definition of @code{beginning-of-buffer} - -* Optional Arguments:: -* beginning-of-buffer opt arg:: Example with optional argument. -* beginning-of-buffer complete:: - -@code{beginning-of-buffer} with an Argument - -* Disentangle beginning-of-buffer:: -* Large buffer case:: -* Small buffer case:: - -Narrowing and Widening - -* Narrowing advantages:: The advantages of narrowing -* save-restriction:: The @code{save-restriction} special form. -* what-line:: The number of the line that point is on. -* narrow Exercise:: - -@code{car}, @code{cdr}, @code{cons}: Fundamental Functions - -* Strange Names:: An historical aside: why the strange names? -* car & cdr:: Functions for extracting part of a list. -* cons:: Constructing a list. -* nthcdr:: Calling @code{cdr} repeatedly. -* nth:: -* setcar:: Changing the first element of a list. -* setcdr:: Changing the rest of a list. -* cons Exercise:: - -@code{cons} - -* Build a list:: -* length:: How to find the length of a list. - -Cutting and Storing Text - -* Storing Text:: Text is stored in a list. -* zap-to-char:: Cutting out text up to a character. -* kill-region:: Cutting text out of a region. -* copy-region-as-kill:: A definition for copying text. -* Digression into C:: Minor note on C programming language macros. -* defvar:: How to give a variable an initial value. -* cons & search-fwd Review:: -* search Exercises:: - -@code{zap-to-char} - -* Complete zap-to-char:: The complete implementation. -* zap-to-char interactive:: A three part interactive expression. -* zap-to-char body:: A short overview. -* search-forward:: How to search for a string. -* progn:: The @code{progn} special form. -* Summing up zap-to-char:: Using @code{point} and @code{search-forward}. - -@code{kill-region} - -* Complete kill-region:: The function definition. -* condition-case:: Dealing with a problem. -* Lisp macro:: - -@code{copy-region-as-kill} - -* Complete copy-region-as-kill:: The complete function definition. -* copy-region-as-kill body:: The body of @code{copy-region-as-kill}. - -The Body of @code{copy-region-as-kill} - -* last-command & this-command:: -* kill-append function:: -* kill-new function:: - -Initializing a Variable with @code{defvar} - -* See variable current value:: -* defvar and asterisk:: - -How Lists are Implemented - -* Lists diagrammed:: -* Symbols as Chest:: Exploring a powerful metaphor. -* List Exercise:: - -Yanking Text Back - -* Kill Ring Overview:: -* kill-ring-yank-pointer:: The kill ring is a list. -* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. - -Loops and Recursion - -* while:: Causing a stretch of code to repeat. -* dolist dotimes:: -* Recursion:: Causing a function to call itself. -* Looping exercise:: - -@code{while} - -* Looping with while:: Repeat so long as test returns true. -* Loop Example:: A @code{while} loop that uses a list. -* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. -* Incrementing Loop:: A loop with an incrementing counter. -* Incrementing Loop Details:: -* Decrementing Loop:: A loop with a decrementing counter. - -Details of an Incrementing Loop - -* Incrementing Example:: Counting pebbles in a triangle. -* Inc Example parts:: The parts of the function definition. -* Inc Example altogether:: Putting the function definition together. - -Loop with a Decrementing Counter - -* Decrementing Example:: More pebbles on the beach. -* Dec Example parts:: The parts of the function definition. -* Dec Example altogether:: Putting the function definition together. - -Save your time: @code{dolist} and @code{dotimes} - -* dolist:: -* dotimes:: - -Recursion - -* Building Robots:: Same model, different serial number ... -* Recursive Definition Parts:: Walk until you stop ... -* Recursion with list:: Using a list as the test whether to recurse. -* Recursive triangle function:: -* Recursion with cond:: -* Recursive Patterns:: Often used templates. -* No Deferment:: Don't store up work ... -* No deferment solution:: - -Recursion in Place of a Counter - -* Recursive Example arg of 1 or 2:: -* Recursive Example arg of 3 or 4:: - -Recursive Patterns - -* Every:: -* Accumulate:: -* Keep:: - -Regular Expression Searches - -* sentence-end:: The regular expression for @code{sentence-end}. -* re-search-forward:: Very similar to @code{search-forward}. -* forward-sentence:: A straightforward example of regexp search. -* forward-paragraph:: A somewhat complex example. -* etags:: How to create your own @file{TAGS} table. -* Regexp Review:: -* re-search Exercises:: - -@code{forward-sentence} - -* Complete forward-sentence:: -* fwd-sentence while loops:: Two @code{while} loops. -* fwd-sentence re-search:: A regular expression search. - -@code{forward-paragraph}: a Goldmine of Functions - -* forward-paragraph in brief:: Key parts of the function definition. -* fwd-para let:: The @code{let*} expression. -* fwd-para while:: The forward motion @code{while} loop. - -Counting: Repetition and Regexps - -* Why Count Words:: -* count-words-region:: Use a regexp, but find a problem. -* recursive-count-words:: Start with case of no words in region. -* Counting Exercise:: - -The @code{count-words-region} Function - -* Design count-words-region:: The definition using a @code{while} loop. -* Whitespace Bug:: The Whitespace Bug in @code{count-words-region}. - -Counting Words in a @code{defun} - -* Divide and Conquer:: -* Words and Symbols:: What to count? -* Syntax:: What constitutes a word or symbol? -* count-words-in-defun:: Very like @code{count-words}. -* Several defuns:: Counting several defuns in a file. -* Find a File:: Do you want to look at a file? -* lengths-list-file:: A list of the lengths of many definitions. -* Several files:: Counting in definitions in different files. -* Several files recursively:: Recursively counting in different files. -* Prepare the data:: Prepare the data for display in a graph. - -Count Words in @code{defuns} in Different Files - -* lengths-list-many-files:: Return a list of the lengths of defuns. -* append:: Attach one list to another. - -Prepare the Data for Display in a Graph - -* Data for Display in Detail:: -* Sorting:: Sorting lists. -* Files List:: Making a list of files. -* Counting function definitions:: - -Readying a Graph - -* Columns of a graph:: -* graph-body-print:: How to print the body of a graph. -* recursive-graph-body-print:: -* Printed Axes:: -* Line Graph Exercise:: - -Your @file{.emacs} File - -* Default Configuration:: -* Site-wide Init:: You can write site-wide init files. -* defcustom:: Emacs will write code for you. -* Beginning a .emacs File:: How to write a @code{.emacs file}. -* Text and Auto-fill:: Automatically wrap lines. -* Mail Aliases:: Use abbreviations for email addresses. -* Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. -* Keymaps:: More about key binding. -* Loading Files:: Load (i.e., evaluate) files automatically. -* Autoload:: Make functions available. -* Simple Extension:: Define a function; bind it to a key. -* X11 Colors:: Colors in X. -* Miscellaneous:: -* Mode Line:: How to customize your mode line. - -Debugging - -* debug:: How to use the built-in debugger. -* debug-on-entry:: Start debugging when you call a function. -* debug-on-quit:: Start debugging when you quit with @kbd{C-g}. -* edebug:: How to use Edebug, a source level debugger. -* Debugging Exercises:: - -Handling the Kill Ring - -* What the Kill Ring Does:: -* current-kill:: -* yank:: Paste a copy of a clipped element. -* yank-pop:: Insert element pointed to. -* ring file:: - -The @code{current-kill} Function - -* Understanding current-kill:: - -@code{current-kill} in Outline - -* Body of current-kill:: -* Digression concerning error:: How to mislead humans, but not computers. -* Determining the Element:: - -A Graph with Labelled Axes - -* Labelled Example:: -* print-graph Varlist:: @code{let} expression in @code{print-graph}. -* print-Y-axis:: Print a label for the vertical axis. -* print-X-axis:: Print a horizontal label. -* Print Whole Graph:: The function to print a complete graph. - -The @code{print-Y-axis} Function - -* print-Y-axis in Detail:: -* Height of label:: What height for the Y axis? -* Compute a Remainder:: How to compute the remainder of a division. -* Y Axis Element:: Construct a line for the Y axis. -* Y-axis-column:: Generate a list of Y axis labels. -* print-Y-axis Penultimate:: A not quite final version. - -The @code{print-X-axis} Function - -* Similarities differences:: Much like @code{print-Y-axis}, but not exactly. -* X Axis Tic Marks:: Create tic marks for the horizontal axis. - -Printing the Whole Graph - -* The final version:: A few changes. -* Test print-graph:: Run a short test. -* Graphing words in defuns:: Executing the final code. -* lambda:: How to write an anonymous function. -* mapcar:: Apply a function to elements of a list. -* Another Bug:: Yet another bug @dots{} most insidious. -* Final printed graph:: The graph itself! - -@end detailmenu -@end menu - -@node Preface, List Processing, Top, Top -@comment node-name, next, previous, up -@unnumbered Preface - -Most of the GNU Emacs integrated environment is written in the programming -language called Emacs Lisp. The code written in this programming -language is the software---the sets of instructions---that tell the -computer what to do when you give it commands. Emacs is designed so -that you can write new code in Emacs Lisp and easily install it as an -extension to the editor. - -(GNU Emacs is sometimes called an ``extensible editor'', but it does -much more than provide editing capabilities. It is better to refer to -Emacs as an ``extensible computing environment''. However, that -phrase is quite a mouthful. It is easier to refer to Emacs simply as -an editor. Moreover, everything you do in Emacs---find the Mayan date -and phases of the moon, simplify polynomials, debug code, manage -files, read letters, write books---all these activities are kinds of -editing in the most general sense of the word.) - -@menu -* Why:: Why learn Emacs Lisp? -* On Reading this Text:: Read, gain familiarity, pick up habits.... -* Who You Are:: For whom this is written. -* Lisp History:: -* Note for Novices:: You can read this as a novice. -* Thank You:: -@end menu - -@node Why, On Reading this Text, Preface, Preface -@ifnottex -@unnumberedsec Why Study Emacs Lisp? -@end ifnottex - -Although Emacs Lisp is usually thought of in association only with Emacs, -it is a full computer programming language. You can use Emacs Lisp as -you would any other programming language. - -Perhaps you want to understand programming; perhaps you want to extend -Emacs; or perhaps you want to become a programmer. This introduction to -Emacs Lisp is designed to get you started: to guide you in learning the -fundamentals of programming, and more importantly, to show you how you -can teach yourself to go further. - -@node On Reading this Text, Who You Are, Why, Preface -@comment node-name, next, previous, up -@unnumberedsec On Reading this Text - -All through this document, you will see little sample programs you can -run inside of Emacs. If you read this document in Info inside of GNU -Emacs, you can run the programs as they appear. (This is easy to do and -is explained when the examples are presented.) Alternatively, you can -read this introduction as a printed book while sitting beside a computer -running Emacs. (This is what I like to do; I like printed books.) If -you don't have a running Emacs beside you, you can still read this book, -but in this case, it is best to treat it as a novel or as a travel guide -to a country not yet visited: interesting, but not the same as being -there. - -Much of this introduction is dedicated to walk-throughs or guided tours -of code used in GNU Emacs. These tours are designed for two purposes: -first, to give you familiarity with real, working code (code you use -every day); and, second, to give you familiarity with the way Emacs -works. It is interesting to see how a working environment is -implemented. -Also, I -hope that you will pick up the habit of browsing through source code. -You can learn from it and mine it for ideas. Having GNU Emacs is like -having a dragon's cave of treasures. - -In addition to learning about Emacs as an editor and Emacs Lisp as a -programming language, the examples and guided tours will give you an -opportunity to get acquainted with Emacs as a Lisp programming -environment. GNU Emacs supports programming and provides tools that -you will want to become comfortable using, such as @kbd{M-.} (the key -which invokes the @code{find-tag} command). You will also learn about -buffers and other objects that are part of the environment. -Learning about these features of Emacs is like learning new routes -around your home town. - -@ignore -In addition, I have written several programs as extended examples. -Although these are examples, the programs are real. I use them. -Other people use them. You may use them. Beyond the fragments of -programs used for illustrations, there is very little in here that is -`just for teaching purposes'; what you see is used. This is a great -advantage of Emacs Lisp: it is easy to learn to use it for work. -@end ignore - -Finally, I hope to convey some of the skills for using Emacs to -learn aspects of programming that you don't know. You can often use -Emacs to help you understand what puzzles you or to find out how to do -something new. This self-reliance is not only a pleasure, but an -advantage. - -@node Who You Are, Lisp History, On Reading this Text, Preface -@comment node-name, next, previous, up -@unnumberedsec For Whom This is Written - -This text is written as an elementary introduction for people who are -not programmers. If you are a programmer, you may not be satisfied with -this primer. The reason is that you may have become expert at reading -reference manuals and be put off by the way this text is organized. - -An expert programmer who reviewed this text said to me: - -@quotation -@i{I prefer to learn from reference manuals. I ``dive into'' each -paragraph, and ``come up for air'' between paragraphs.} - -@i{When I get to the end of a paragraph, I assume that that subject is -done, finished, that I know everything I need (with the -possible exception of the case when the next paragraph starts talking -about it in more detail). I expect that a well written reference manual -will not have a lot of redundancy, and that it will have excellent -pointers to the (one) place where the information I want is.} -@end quotation - -This introduction is not written for this person! - -Firstly, I try to say everything at least three times: first, to -introduce it; second, to show it in context; and third, to show it in a -different context, or to review it. - -Secondly, I hardly ever put all the information about a subject in one -place, much less in one paragraph. To my way of thinking, that imposes -too heavy a burden on the reader. Instead I try to explain only what -you need to know at the time. (Sometimes I include a little extra -information so you won't be surprised later when the additional -information is formally introduced.) - -When you read this text, you are not expected to learn everything the -first time. Frequently, you need only make, as it were, a `nodding -acquaintance' with some of the items mentioned. My hope is that I have -structured the text and given you enough hints that you will be alert to -what is important, and concentrate on it. - -You will need to ``dive into'' some paragraphs; there is no other way -to read them. But I have tried to keep down the number of such -paragraphs. This book is intended as an approachable hill, rather than -as a daunting mountain. - -This introduction to @cite{Programming in Emacs Lisp} has a companion -document, -@iftex -@cite{The GNU Emacs Lisp Reference Manual}. -@end iftex -@ifnottex -@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU -Emacs Lisp Reference Manual}. -@end ifnottex -The reference manual has more detail than this introduction. In the -reference manual, all the information about one topic is concentrated -in one place. You should turn to it if you are like the programmer -quoted above. And, of course, after you have read this -@cite{Introduction}, you will find the @cite{Reference Manual} useful -when you are writing your own programs. - -@node Lisp History, Note for Novices, Who You Are, Preface -@unnumberedsec Lisp History -@cindex Lisp history - -Lisp was first developed in the late 1950s at the Massachusetts -Institute of Technology for research in artificial intelligence. The -great power of the Lisp language makes it superior for other purposes as -well, such as writing editor commands and integrated environments. - -@cindex Maclisp -@cindex Common Lisp -GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT -in the 1960s. It is somewhat inspired by Common Lisp, which became a -standard in the 1980s. However, Emacs Lisp is much simpler than Common -Lisp. (The standard Emacs distribution contains an optional extensions -file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) - -@node Note for Novices, Thank You, Lisp History, Preface -@comment node-name, next, previous, up -@unnumberedsec A Note for Novices - -If you don't know GNU Emacs, you can still read this document -profitably. However, I recommend you learn Emacs, if only to learn to -move around your computer screen. You can teach yourself how to use -Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This -means you press and release the @key{CTRL} key and the @kbd{h} at the -same time, and then press and release @kbd{t}.) - -Also, I often refer to one of Emacs' standard commands by listing the -keys which you press to invoke the command and then giving the name of -the command in parentheses, like this: @kbd{M-C-\} -(@code{indent-region}). What this means is that the -@code{indent-region} command is customarily invoked by typing -@kbd{M-C-\}. (You can, if you wish, change the keys that are typed to -invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, , -Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your -@key{META} key, @key{CTRL} key and @key{\} key all at the same time. -(On many modern keyboards the @key{META} key is labelled -@key{ALT}.) -Sometimes a combination like this is called a keychord, since it is -similar to the way you play a chord on a piano. If your keyboard does -not have a @key{META} key, the @key{ESC} key prefix is used in place -of it. In this case, @kbd{M-C-\} means that you press and release your -@key{ESC} key and then type the @key{CTRL} key and the @key{\} key at -the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key -along with the key that is labelled @key{ALT} and, at the same time, -press the @key{\} key. - -In addition to typing a lone keychord, you can prefix what you type -with @kbd{C-u}, which is called the `universal argument'. The -@kbd{C-u} keychord passes an argument to the subsequent command. -Thus, to indent a region of plain text by 6 spaces, mark the region, -and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number, -Emacs either passes the number 4 to the command or otherwise runs the -command differently than it would otherwise.) @xref{Arguments, , -Numeric Arguments, emacs, The GNU Emacs Manual}. - -If you are reading this in Info using GNU Emacs, you can read through -this whole document just by pressing the space bar, @key{SPC}. -(To learn about Info, type @kbd{C-h i} and then select Info.) - -A note on terminology: when I use the word Lisp alone, I often am -referring to the various dialects of Lisp in general, but when I speak -of Emacs Lisp, I am referring to GNU Emacs Lisp in particular. - -@node Thank You, , Note for Novices, Preface -@comment node-name, next, previous, up -@unnumberedsec Thank You - -My thanks to all who helped me with this book. My especial thanks to -@r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland -McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@: -Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both -@w{Philip Johnson} and @w{David Stampe} for their patient -encouragement. My mistakes are my own. - -@flushright -Robert J. Chassell -@end flushright - -@c ================ Beginning of main text ================ - -@c Start main text on right-hand (verso) page - -@tex -\par\vfill\supereject -\headings off -\ifodd\pageno - \par\vfill\supereject -\else - \par\vfill\supereject - \page\hbox{}\page - \par\vfill\supereject -\fi -@end tex - -@iftex -@headings off -@evenheading @thispage @| @| @thischapter -@oddheading @thissection @| @| @thispage -@global@pageno = 1 -@end iftex - -@node List Processing, Practicing Evaluation, Preface, Top -@comment node-name, next, previous, up -@chapter List Processing - -To the untutored eye, Lisp is a strange programming language. In Lisp -code there are parentheses everywhere. Some people even claim that -the name stands for `Lots of Isolated Silly Parentheses'. But the -claim is unwarranted. Lisp stands for LISt Processing, and the -programming language handles @emph{lists} (and lists of lists) by -putting them between parentheses. The parentheses mark the boundaries -of the list. Sometimes a list is preceded by a single apostrophe or -quotation mark, @samp{'}@footnote{The single apostrophe or quotation -mark is an abbreviation for the function @code{quote}; you need not -think about functions now; functions are defined in @ref{Making -Errors, , Generate an Error Message}.} Lists are the basis of Lisp. - -@menu -* Lisp Lists:: What are lists? -* Run a Program:: Any list in Lisp is a program ready to run. -* Making Errors:: Generating an error message. -* Names & Definitions:: Names of symbols and function definitions. -* Lisp Interpreter:: What the Lisp interpreter does. -* Evaluation:: Running a program. -* Variables:: Returning a value from a variable. -* Arguments:: Passing information to a function. -* set & setq:: Setting the value of a variable. -* Summary:: The major points. -* Error Message Exercises:: -@end menu - -@node Lisp Lists, Run a Program, List Processing, List Processing -@comment node-name, next, previous, up -@section Lisp Lists -@cindex Lisp Lists - -In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}. -This list is preceded by a single apostrophe. It could just as well be -written as follows, which looks more like the kind of list you are likely -to be familiar with: - -@smallexample -@group -'(rose - violet - daisy - buttercup) -@end group -@end smallexample - -@noindent -The elements of this list are the names of the four different flowers, -separated from each other by whitespace and surrounded by parentheses, -like flowers in a field with a stone wall around them. -@cindex Flowers in a field - -@menu -* Numbers Lists:: List have numbers, other lists, in them. -* Lisp Atoms:: Elemental entities. -* Whitespace in Lists:: Formatting lists to be readable. -* Typing Lists:: How GNU Emacs helps you type lists. -@end menu - -@node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists -@ifnottex -@unnumberedsubsec Numbers, Lists inside of Lists -@end ifnottex - -Lists can also have numbers in them, as in this list: @code{(+ 2 2)}. -This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each -separated by whitespace. - -In Lisp, both data and programs are represented the same way; that is, -they are both lists of words, numbers, or other lists, separated by -whitespace and surrounded by parentheses. (Since a program looks like -data, one program may easily serve as data for another; this is a very -powerful feature of Lisp.) (Incidentally, these two parenthetical -remarks are @emph{not} Lisp lists, because they contain @samp{;} and -@samp{.} as punctuation marks.) - -@need 1200 -Here is another list, this time with a list inside of it: - -@smallexample -'(this list has (a list inside of it)) -@end smallexample - -The components of this list are the words @samp{this}, @samp{list}, -@samp{has}, and the list @samp{(a list inside of it)}. The interior -list is made up of the words @samp{a}, @samp{list}, @samp{inside}, -@samp{of}, @samp{it}. - -@node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists -@comment node-name, next, previous, up -@subsection Lisp Atoms -@cindex Lisp Atoms - -In Lisp, what we have been calling words are called @dfn{atoms}. This -term comes from the historical meaning of the word atom, which means -`indivisible'. As far as Lisp is concerned, the words we have been -using in the lists cannot be divided into any smaller parts and still -mean the same thing as part of a program; likewise with numbers and -single character symbols like @samp{+}. On the other hand, unlike an -ancient atom, a list can be split into parts. (@xref{car cdr & cons, -, @code{car} @code{cdr} & @code{cons} Fundamental Functions}.) - -In a list, atoms are separated from each other by whitespace. They can be -right next to a parenthesis. - -@cindex @samp{empty list} defined -Technically speaking, a list in Lisp consists of parentheses surrounding -atoms separated by whitespace or surrounding other lists or surrounding -both atoms and other lists. A list can have just one atom in it or -have nothing in it at all. A list with nothing in it looks like this: -@code{()}, and is called the @dfn{empty list}. Unlike anything else, an -empty list is considered both an atom and a list at the same time. - -@cindex Symbolic expressions, introduced -@cindex @samp{expression} defined -@cindex @samp{form} defined -The printed representation of both atoms and lists are called -@dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}. -The word @dfn{expression} by itself can refer to either the printed -representation, or to the atom or list as it is held internally in the -computer. Often, people use the term @dfn{expression} -indiscriminately. (Also, in many texts, the word @dfn{form} is used -as a synonym for expression.) - -Incidentally, the atoms that make up our universe were named such when -they were thought to be indivisible; but it has been found that physical -atoms are not indivisible. Parts can split off an atom or it can -fission into two parts of roughly equal size. Physical atoms were named -prematurely, before their truer nature was found. In Lisp, certain -kinds of atom, such as an array, can be separated into parts; but the -mechanism for doing this is different from the mechanism for splitting a -list. As far as list operations are concerned, the atoms of a list are -unsplittable. - -As in English, the meanings of the component letters of a Lisp atom -are different from the meaning the letters make as a word. For -example, the word for the South American sloth, the @samp{ai}, is -completely different from the two words, @samp{a}, and @samp{i}. - -There are many kinds of atom in nature but only a few in Lisp: for -example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such -as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have -listed in the examples above are all symbols. In everyday Lisp -conversation, the word ``atom'' is not often used, because programmers -usually try to be more specific about what kind of atom they are dealing -with. Lisp programming is mostly about symbols (and sometimes numbers) -within lists. (Incidentally, the preceding three word parenthetical -remark is a proper list in Lisp, since it consists of atoms, which in -this case are symbols, separated by whitespace and enclosed by -parentheses, without any non-Lisp punctuation.) - -@need 1250 -In addition, text between double quotation marks---even sentences or -paragraphs---is an atom. Here is an example: -@cindex Text between double quotation marks - -@smallexample -'(this list includes "text between quotation marks.") -@end smallexample - -@cindex @samp{string} defined -@noindent -In Lisp, all of the quoted text including the punctuation mark and the -blank spaces is a single atom. This kind of atom is called a -@dfn{string} (for `string of characters') and is the sort of thing that -is used for messages that a computer can print for a human to read. -Strings are a different kind of atom than numbers or symbols and are -used differently. - -@node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists -@comment node-name, next, previous, up -@subsection Whitespace in Lists -@cindex Whitespace in lists - -@need 1200 -The amount of whitespace in a list does not matter. From the point of view -of the Lisp language, - -@smallexample -@group -'(this list - looks like this) -@end group -@end smallexample - -@need 800 -@noindent -is exactly the same as this: - -@smallexample -'(this list looks like this) -@end smallexample - -Both examples show what to Lisp is the same list, the list made up of -the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and -@samp{this} in that order. - -Extra whitespace and newlines are designed to make a list more readable -by humans. When Lisp reads the expression, it gets rid of all the extra -whitespace (but it needs to have at least one space between atoms in -order to tell them apart.) - -Odd as it seems, the examples we have seen cover almost all of what Lisp -lists look like! Every other list in Lisp looks more or less like one -of these examples, except that the list may be longer and more complex. -In brief, a list is between parentheses, a string is between quotation -marks, a symbol looks like a word, and a number looks like a number. -(For certain situations, square brackets, dots and a few other special -characters may be used; however, we will go quite far without them.) - -@node Typing Lists, , Whitespace in Lists, Lisp Lists -@comment node-name, next, previous, up -@subsection GNU Emacs Helps You Type Lists -@cindex Help typing lists -@cindex Formatting help - -When you type a Lisp expression in GNU Emacs using either Lisp -Interaction mode or Emacs Lisp mode, you have available to you several -commands to format the Lisp expression so it is easy to read. For -example, pressing the @key{TAB} key automatically indents the line the -cursor is on by the right amount. A command to properly indent the -code in a region is customarily bound to @kbd{M-C-\}. Indentation is -designed so that you can see which elements of a list belong to which -list---elements of a sub-list are indented more than the elements of -the enclosing list. - -In addition, when you type a closing parenthesis, Emacs momentarily -jumps the cursor back to the matching opening parenthesis, so you can -see which one it is. This is very useful, since every list you type -in Lisp must have its closing parenthesis match its opening -parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs -Manual}, for more information about Emacs' modes.) - -@node Run a Program, Making Errors, Lisp Lists, List Processing -@comment node-name, next, previous, up -@section Run a Program -@cindex Run a program -@cindex Program, running one - -@cindex @samp{evaluate} defined -A list in Lisp---any list---is a program ready to run. If you run it -(for which the Lisp jargon is @dfn{evaluate}), the computer will do one -of three things: do nothing except return to you the list itself; send -you an error message; or, treat the first symbol in the list as a -command to do something. (Usually, of course, it is the last of these -three things that you really want!) - -@c use code for the single apostrophe, not samp. -The single apostrophe, @code{'}, that I put in front of some of the -example lists in preceding sections is called a @dfn{quote}; when it -precedes a list, it tells Lisp to do nothing with the list, other than -take it as it is written. But if there is no quote preceding a list, -the first item of the list is special: it is a command for the computer -to obey. (In Lisp, these commands are called @emph{functions}.) The list -@code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp -understands that the @code{+} is an instruction to do something with the -rest of the list: add the numbers that follow. - -@need 1250 -If you are reading this inside of GNU Emacs in Info, here is how you can -evaluate such a list: place your cursor immediately after the right -hand parenthesis of the following list and then type @kbd{C-x C-e}: - -@smallexample -(+ 2 2) -@end smallexample - -@c use code for the number four, not samp. -@noindent -You will see the number @code{4} appear in the echo area. (In the -jargon, what you have just done is ``evaluate the list.'' The echo area -is the line at the bottom of the screen that displays or ``echoes'' -text.) Now try the same thing with a quoted list: place the cursor -right after the following list and type @kbd{C-x C-e}: - -@smallexample -'(this is a quoted list) -@end smallexample - -@noindent -You will see @code{(this is a quoted list)} appear in the echo area. - -@cindex Lisp interpreter, explained -@cindex Interpreter, Lisp, explained -In both cases, what you are doing is giving a command to the program -inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the -interpreter a command to evaluate the expression. The name of the Lisp -interpreter comes from the word for the task done by a human who comes -up with the meaning of an expression---who ``interprets'' it. - -You can also evaluate an atom that is not part of a list---one that is -not surrounded by parentheses; again, the Lisp interpreter translates -from the humanly readable expression to the language of the computer. -But before discussing this (@pxref{Variables}), we will discuss what the -Lisp interpreter does when you make an error. - -@node Making Errors, Names & Definitions, Run a Program, List Processing -@comment node-name, next, previous, up -@section Generate an Error Message -@cindex Generate an error message -@cindex Error message generation - -Partly so you won't worry if you do it accidentally, we will now give -a command to the Lisp interpreter that generates an error message. -This is a harmless activity; and indeed, we will often try to generate -error messages intentionally. Once you understand the jargon, error -messages can be informative. Instead of being called ``error'' -messages, they should be called ``help'' messages. They are like -signposts to a traveller in a strange country; deciphering them can be -hard, but once understood, they can point the way. - -The error message is generated by a built-in GNU Emacs debugger. We -will `enter the debugger'. You get out of the debugger by typing @code{q}. - -What we will do is evaluate a list that is not quoted and does not -have a meaningful command as its first element. Here is a list almost -exactly the same as the one we just used, but without the single-quote -in front of it. Position the cursor right after it and type @kbd{C-x -C-e}: - -@smallexample -(this is an unquoted list) -@end smallexample - -@noindent -What you see depends on which version of Emacs you are running. GNU -Emacs version 22 provides more information than version 20 and before. -First, the more recent result of generating an error; then the -earlier, version 20 result. - -@need 1250 -@noindent -In GNU Emacs version 22, a @file{*Backtrace*} window will open up and -you will see the following in it: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function this) - (this is an unquoted list) - eval((this is an unquoted list)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@need 1200 -@noindent -Your cursor will be in this window (you may have to wait a few seconds -before it becomes visible). To quit the debugger and make the -debugger window go away, type: - -@smallexample -q -@end smallexample - -@noindent -Please type @kbd{q} right now, so you become confident that you can -get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter -it. - -@cindex @samp{function} defined -Based on what we already know, we can almost read this error message. - -You read the @file{*Backtrace*} buffer from the bottom up; it tells -you what Emacs did. When you typed @kbd{C-x C-e}, you made an -interactive call to the command @code{eval-last-sexp}. @code{eval} is -an abbreviation for `evaluate' and @code{sexp} is an abbreviation for -`symbolic expression'. The command means `evaluate last symbolic -expression', which is the expression just before your cursor. - -Each line above tells you what the Lisp interpreter evaluated next. -The most recent action is at the top. The buffer is called the -@file{*Backtrace*} buffer because it enables you to track Emacs -backwards. - -@need 800 -At the top of the @file{*Backtrace*} buffer, you see the line: - -@smallexample -Debugger entered--Lisp error: (void-function this) -@end smallexample - -@noindent -The Lisp interpreter tried to evaluate the first atom of the list, the -word @samp{this}. It is this action that generated the error message -@samp{void-function this}. - -The message contains the words @samp{void-function} and @samp{this}. - -@cindex @samp{function} defined -The word @samp{function} was mentioned once before. It is a very -important word. For our purposes, we can define it by saying that a -@dfn{function} is a set of instructions to the computer that tell the -computer to do something. - -Now we can begin to understand the error message: @samp{void-function -this}. The function (that is, the word @samp{this}) does not have a -definition of any set of instructions for the computer to carry out. - -The slightly odd word, @samp{void-function}, is designed to cover the -way Emacs Lisp is implemented, which is that when a symbol does not -have a function definition attached to it, the place that should -contain the instructions is `void'. - -On the other hand, since we were able to add 2 plus 2 successfully, by -evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must -have a set of instructions for the computer to obey and those -instructions must be to add the numbers that follow the @code{+}. - -@need 1250 -In GNU Emacs version 20, and in earlier versions, you will see only -one line of error message; it will appear in the echo area and look -like this: - -@smallexample -Symbol's function definition is void:@: this -@end smallexample - -@noindent -(Also, your terminal may beep at you---some do, some don't; and others -blink. This is just a device to get your attention.) The message goes -away as soon as you type another key, even just to move the cursor. - -We know the meaning of the word @samp{Symbol}. It refers to the first -atom of the list, the word @samp{this}. The word @samp{function} -refers to the instructions that tell the computer what to do. -(Technically, the symbol tells the computer where to find the -instructions, but this is a complication we can ignore for the -moment.) - -The error message can be understood: @samp{Symbol's function -definition is void:@: this}. The symbol (that is, the word -@samp{this}) lacks instructions for the computer to carry out. - -@node Names & Definitions, Lisp Interpreter, Making Errors, List Processing -@comment node-name, next, previous, up -@section Symbol Names and Function Definitions -@cindex Symbol names - -We can articulate another characteristic of Lisp based on what we have -discussed so far---an important characteristic: a symbol, like -@code{+}, is not itself the set of instructions for the computer to -carry out. Instead, the symbol is used, perhaps temporarily, as a way -of locating the definition or set of instructions. What we see is the -name through which the instructions can be found. Names of people -work the same way. I can be referred to as @samp{Bob}; however, I am -not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the -consciousness consistently associated with a particular life-form. -The name is not me, but it can be used to refer to me. - -In Lisp, one set of instructions can be attached to several names. -For example, the computer instructions for adding numbers can be -linked to the symbol @code{plus} as well as to the symbol @code{+} -(and are in some dialects of Lisp). Among humans, I can be referred -to as @samp{Robert} as well as @samp{Bob} and by other words as well. - -On the other hand, a symbol can have only one function definition -attached to it at a time. Otherwise, the computer would be confused as -to which definition to use. If this were the case among people, only -one person in the world could be named @samp{Bob}. However, the function -definition to which the name refers can be changed readily. -(@xref{Install, , Install a Function Definition}.) - -Since Emacs Lisp is large, it is customary to name symbols in a way -that identifies the part of Emacs to which the function belongs. -Thus, all the names for functions that deal with Texinfo start with -@samp{texinfo-} and those for functions that deal with reading mail -start with @samp{rmail-}. - -@node Lisp Interpreter, Evaluation, Names & Definitions, List Processing -@comment node-name, next, previous, up -@section The Lisp Interpreter -@cindex Lisp interpreter, what it does -@cindex Interpreter, what it does - -Based on what we have seen, we can now start to figure out what the -Lisp interpreter does when we command it to evaluate a list. -First, it looks to see whether there is a quote before the list; if -there is, the interpreter just gives us the list. On the other -hand, if there is no quote, the interpreter looks at the first element -in the list and sees whether it has a function definition. If it does, -the interpreter carries out the instructions in the function definition. -Otherwise, the interpreter prints an error message. - -This is how Lisp works. Simple. There are added complications which we -will get to in a minute, but these are the fundamentals. Of course, to -write Lisp programs, you need to know how to write function definitions -and attach them to names, and how to do this without confusing either -yourself or the computer. - -@menu -* Complications:: Variables, Special forms, Lists within. -* Byte Compiling:: Specially processing code for speed. -@end menu - -@node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter -@ifnottex -@unnumberedsubsec Complications -@end ifnottex - -Now, for the first complication. In addition to lists, the Lisp -interpreter can evaluate a symbol that is not quoted and does not have -parentheses around it. The Lisp interpreter will attempt to determine -the symbol's value as a @dfn{variable}. This situation is described -in the section on variables. (@xref{Variables}.) - -@cindex Special form -The second complication occurs because some functions are unusual and do -not work in the usual manner. Those that don't are called @dfn{special -forms}. They are used for special jobs, like defining a function, and -there are not many of them. In the next few chapters, you will be -introduced to several of the more important special forms. - -The third and final complication is this: if the function that the -Lisp interpreter is looking at is not a special form, and if it is part -of a list, the Lisp interpreter looks to see whether the list has a list -inside of it. If there is an inner list, the Lisp interpreter first -figures out what it should do with the inside list, and then it works on -the outside list. If there is yet another list embedded inside the -inner list, it works on that one first, and so on. It always works on -the innermost list first. The interpreter works on the innermost list -first, to evaluate the result of that list. The result may be -used by the enclosing expression. - -Otherwise, the interpreter works left to right, from one expression to -the next. - -@node Byte Compiling, , Complications, Lisp Interpreter -@subsection Byte Compiling -@cindex Byte compiling - -One other aspect of interpreting: the Lisp interpreter is able to -interpret two kinds of entity: humanly readable code, on which we will -focus exclusively, and specially processed code, called @dfn{byte -compiled} code, which is not humanly readable. Byte compiled code -runs faster than humanly readable code. - -You can transform humanly readable code into byte compiled code by -running one of the compile commands such as @code{byte-compile-file}. -Byte compiled code is usually stored in a file that ends with a -@file{.elc} extension rather than a @file{.el} extension. You will -see both kinds of file in the @file{emacs/lisp} directory; the files -to read are those with @file{.el} extensions. - -As a practical matter, for most things you might do to customize or -extend Emacs, you do not need to byte compile; and I will not discuss -the topic here. @xref{Byte Compilation, , Byte Compilation, elisp, -The GNU Emacs Lisp Reference Manual}, for a full description of byte -compilation. - -@node Evaluation, Variables, Lisp Interpreter, List Processing -@comment node-name, next, previous, up -@section Evaluation -@cindex Evaluation - -When the Lisp interpreter works on an expression, the term for the -activity is called @dfn{evaluation}. We say that the interpreter -`evaluates the expression'. I've used this term several times before. -The word comes from its use in everyday language, `to ascertain the -value or amount of; to appraise', according to @cite{Webster's New -Collegiate Dictionary}. - -@menu -* How the Interpreter Acts:: Returns and Side Effects... -* Evaluating Inner Lists:: Lists within lists... -@end menu - -@node How the Interpreter Acts, Evaluating Inner Lists, Evaluation, Evaluation -@ifnottex -@unnumberedsubsec How the Lisp Interpreter Acts -@end ifnottex - -@cindex @samp{returned value} explained -After evaluating an expression, the Lisp interpreter will most likely -@dfn{return} the value that the computer produces by carrying out the -instructions it found in the function definition, or perhaps it will -give up on that function and produce an error message. (The interpreter -may also find itself tossed, so to speak, to a different function or it -may attempt to repeat continually what it is doing for ever and ever in -what is called an `infinite loop'. These actions are less common; and -we can ignore them.) Most frequently, the interpreter returns a value. - -@cindex @samp{side effect} defined -At the same time the interpreter returns a value, it may do something -else as well, such as move a cursor or copy a file; this other kind of -action is called a @dfn{side effect}. Actions that we humans think are -important, such as printing results, are often ``side effects'' to the -Lisp interpreter. The jargon can sound peculiar, but it turns out that -it is fairly easy to learn to use side effects. - -In summary, evaluating a symbolic expression most commonly causes the -Lisp interpreter to return a value and perhaps carry out a side effect; -or else produce an error. - -@node Evaluating Inner Lists, , How the Interpreter Acts, Evaluation -@comment node-name, next, previous, up -@subsection Evaluating Inner Lists -@cindex Inner list evaluation -@cindex Evaluating inner lists - -If evaluation applies to a list that is inside another list, the outer -list may use the value returned by the first evaluation as information -when the outer list is evaluated. This explains why inner expressions -are evaluated first: the values they return are used by the outer -expressions. - -@need 1250 -We can investigate this process by evaluating another addition example. -Place your cursor after the following expression and type @kbd{C-x C-e}: - -@smallexample -(+ 2 (+ 3 3)) -@end smallexample - -@noindent -The number 8 will appear in the echo area. - -What happens is that the Lisp interpreter first evaluates the inner -expression, @code{(+ 3 3)}, for which the value 6 is returned; then it -evaluates the outer expression as if it were written @code{(+ 2 6)}, which -returns the value 8. Since there are no more enclosing expressions to -evaluate, the interpreter prints that value in the echo area. - -Now it is easy to understand the name of the command invoked by the -keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The -letters @code{sexp} are an abbreviation for `symbolic expression', and -@code{eval} is an abbreviation for `evaluate'. The command means -`evaluate last symbolic expression'. - -As an experiment, you can try evaluating the expression by putting the -cursor at the beginning of the next line immediately following the -expression, or inside the expression. - -@need 800 -Here is another copy of the expression: - -@smallexample -(+ 2 (+ 3 3)) -@end smallexample - -@noindent -If you place the cursor at the beginning of the blank line that -immediately follows the expression and type @kbd{C-x C-e}, you will -still get the value 8 printed in the echo area. Now try putting the -cursor inside the expression. If you put it right after the next to -last parenthesis (so it appears to sit on top of the last parenthesis), -you will get a 6 printed in the echo area! This is because the command -evaluates the expression @code{(+ 3 3)}. - -Now put the cursor immediately after a number. Type @kbd{C-x C-e} and -you will get the number itself. In Lisp, if you evaluate a number, you -get the number itself---this is how numbers differ from symbols. If you -evaluate a list starting with a symbol like @code{+}, you will get a -value returned that is the result of the computer carrying out the -instructions in the function definition attached to that name. If a -symbol by itself is evaluated, something different happens, as we will -see in the next section. - -@node Variables, Arguments, Evaluation, List Processing -@comment node-name, next, previous, up -@section Variables -@cindex Variables - -In Emacs Lisp, a symbol can have a value attached to it just as it can -have a function definition attached to it. The two are different. -The function definition is a set of instructions that a computer will -obey. A value, on the other hand, is something, such as number or a -name, that can vary (which is why such a symbol is called a variable). -The value of a symbol can be any expression in Lisp, such as a symbol, -number, list, or string. A symbol that has a value is often called a -@dfn{variable}. - -A symbol can have both a function definition and a value attached to -it at the same time. Or it can have just one or the other. -The two are separate. This is somewhat similar -to the way the name Cambridge can refer to the city in Massachusetts -and have some information attached to the name as well, such as -``great programming center''. - -@ignore -(Incidentally, in Emacs Lisp, a symbol can have two -other things attached to it, too: a property list and a documentation -string; these are discussed later.) -@end ignore - -Another way to think about this is to imagine a symbol as being a chest -of drawers. The function definition is put in one drawer, the value in -another, and so on. What is put in the drawer holding the value can be -changed without affecting the contents of the drawer holding the -function definition, and vice-verse. - -@menu -* fill-column Example:: -* Void Function:: The error message for a symbol - without a function. -* Void Variable:: The error message for a symbol without a value. -@end menu - -@node fill-column Example, Void Function, Variables, Variables -@ifnottex -@unnumberedsubsec @code{fill-column}, an Example Variable -@end ifnottex - -@findex fill-column, @r{an example variable} -@cindex Example variable, @code{fill-column} -@cindex Variable, example of, @code{fill-column} -The variable @code{fill-column} illustrates a symbol with a value -attached to it: in every GNU Emacs buffer, this symbol is set to some -value, usually 72 or 70, but sometimes to some other value. To find the -value of this symbol, evaluate it by itself. If you are reading this in -Info inside of GNU Emacs, you can do this by putting the cursor after -the symbol and typing @kbd{C-x C-e}: - -@smallexample -fill-column -@end smallexample - -@noindent -After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo -area. This is the value for which @code{fill-column} is set for me as I -write this. It may be different for you in your Info buffer. Notice -that the value returned as a variable is printed in exactly the same way -as the value returned by a function carrying out its instructions. From -the point of view of the Lisp interpreter, a value returned is a value -returned. What kind of expression it came from ceases to matter once -the value is known. - -A symbol can have any value attached to it or, to use the jargon, we can -@dfn{bind} the variable to a value: to a number, such as 72; to a -string, @code{"such as this"}; to a list, such as @code{(spruce pine -oak)}; we can even bind a variable to a function definition. - -A symbol can be bound to a value in several ways. @xref{set & setq, , -Setting the Value of a Variable}, for information about one way to do -this. - -@node Void Function, Void Variable, fill-column Example, Variables -@comment node-name, next, previous, up -@subsection Error Message for a Symbol Without a Function -@cindex Symbol without function error -@cindex Error for symbol without function - -When we evaluated @code{fill-column} to find its value as a variable, -we did not place parentheses around the word. This is because we did -not intend to use it as a function name. - -If @code{fill-column} were the first or only element of a list, the -Lisp interpreter would attempt to find the function definition -attached to it. But @code{fill-column} has no function definition. -Try evaluating this: - -@smallexample -(fill-column) -@end smallexample - -@need 1250 -@noindent -In GNU Emacs version 22, you will create a @file{*Backtrace*} buffer -that says: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function fill-column) - (fill-column) - eval((fill-column)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -(Remember, to quit the debugger and make the debugger window go away, -type @kbd{q} in the @file{*Backtrace*} buffer.) - -@ignore -@need 800 -In GNU Emacs 20 and before, you will produce an error message that says: - -@smallexample -Symbol's function definition is void:@: fill-column -@end smallexample - -@noindent -(The message will go away as soon as you move the cursor or type -another key.) -@end ignore - -@node Void Variable, , Void Function, Variables -@comment node-name, next, previous, up -@subsection Error Message for a Symbol Without a Value -@cindex Symbol without value error -@cindex Error for symbol without value - -If you attempt to evaluate a symbol that does not have a value bound to -it, you will receive an error message. You can see this by -experimenting with our 2 plus 2 addition. In the following expression, -put your cursor right after the @code{+}, before the first number 2, -type @kbd{C-x C-e}: - -@smallexample -(+ 2 2) -@end smallexample - -@need 1500 -@noindent -In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that -says: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-variable +) - eval(+) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -(As with the other times we entered the debugger, you can quit by -typing @kbd{q} in the @file{*Backtrace*} buffer.) - -This backtrace is different from the very first error message we saw, -which said, @samp{Debugger entered--Lisp error: (void-function this)}. -In this case, the function does not have a value as a variable; while -in the other error message, the function (the word `this') did not -have a definition. - -In this experiment with the @code{+}, what we did was cause the Lisp -interpreter to evaluate the @code{+} and look for the value of the -variable instead of the function definition. We did this by placing the -cursor right after the symbol rather than after the parenthesis of the -enclosing list as we did before. As a consequence, the Lisp interpreter -evaluated the preceding s-expression, which in this case was the -@code{+} by itself. - -Since @code{+} does not have a value bound to it, just the function -definition, the error message reported that the symbol's value as a -variable was void. - -@ignore -@need 800 -In GNU Emacs version 20 and before, your error message will say: - -@example -Symbol's value as variable is void:@: + -@end example - -@noindent -The meaning is the same as in GNU Emacs 22. -@end ignore - -@node Arguments, set & setq, Variables, List Processing -@comment node-name, next, previous, up -@section Arguments -@cindex Arguments -@cindex Passing information to functions - -To see how information is passed to functions, let's look again at -our old standby, the addition of two plus two. In Lisp, this is written -as follows: - -@smallexample -(+ 2 2) -@end smallexample - -If you evaluate this expression, the number 4 will appear in your echo -area. What the Lisp interpreter does is add the numbers that follow -the @code{+}. - -@cindex @samp{argument} defined -The numbers added by @code{+} are called the @dfn{arguments} of the -function @code{+}. These numbers are the information that is given to -or @dfn{passed} to the function. - -The word `argument' comes from the way it is used in mathematics and -does not refer to a disputation between two people; instead it refers to -the information presented to the function, in this case, to the -@code{+}. In Lisp, the arguments to a function are the atoms or lists -that follow the function. The values returned by the evaluation of -these atoms or lists are passed to the function. Different functions -require different numbers of arguments; some functions require none at -all.@footnote{It is curious to track the path by which the word `argument' -came to have two different meanings, one in mathematics and the other in -everyday English. According to the @cite{Oxford English Dictionary}, -the word derives from the Latin for @samp{to make clear, prove}; thus it -came to mean, by one thread of derivation, `the evidence offered as -proof', which is to say, `the information offered', which led to its -meaning in Lisp. But in the other thread of derivation, it came to mean -`to assert in a manner against which others may make counter -assertions', which led to the meaning of the word as a disputation. -(Note here that the English word has two different definitions attached -to it at the same time. By contrast, in Emacs Lisp, a symbol cannot -have two different function definitions at the same time.)} - -@menu -* Data types:: Types of data passed to a function. -* Args as Variable or List:: An argument can be the value - of a variable or list. -* Variable Number of Arguments:: Some functions may take a - variable number of arguments. -* Wrong Type of Argument:: Passing an argument of the wrong type - to a function. -* message:: A useful function for sending messages. -@end menu - -@node Data types, Args as Variable or List, Arguments, Arguments -@comment node-name, next, previous, up -@subsection Arguments' Data Types -@cindex Data types -@cindex Types of data -@cindex Arguments' data types - -The type of data that should be passed to a function depends on what -kind of information it uses. The arguments to a function such as -@code{+} must have values that are numbers, since @code{+} adds numbers. -Other functions use different kinds of data for their arguments. - -@need 1250 -@findex concat -For example, the @code{concat} function links together or unites two or -more strings of text to produce a string. The arguments are strings. -Concatenating the two character strings @code{abc}, @code{def} produces -the single string @code{abcdef}. This can be seen by evaluating the -following: - -@smallexample -(concat "abc" "def") -@end smallexample - -@noindent -The value produced by evaluating this expression is @code{"abcdef"}. - -A function such as @code{substring} uses both a string and numbers as -arguments. The function returns a part of the string, a substring of -the first argument. This function takes three arguments. Its first -argument is the string of characters, the second and third arguments are -numbers that indicate the beginning and end of the substring. The -numbers are a count of the number of characters (including spaces and -punctuations) from the beginning of the string. - -@need 800 -For example, if you evaluate the following: - -@smallexample -(substring "The quick brown fox jumped." 16 19) -@end smallexample - -@noindent -you will see @code{"fox"} appear in the echo area. The arguments are the -string and the two numbers. - -Note that the string passed to @code{substring} is a single atom even -though it is made up of several words separated by spaces. Lisp counts -everything between the two quotation marks as part of the string, -including the spaces. You can think of the @code{substring} function as -a kind of `atom smasher' since it takes an otherwise indivisible atom -and extracts a part. However, @code{substring} is only able to extract -a substring from an argument that is a string, not from another type of -atom such as a number or symbol. - -@node Args as Variable or List, Variable Number of Arguments, Data types, Arguments -@comment node-name, next, previous, up -@subsection An Argument as the Value of a Variable or List - -An argument can be a symbol that returns a value when it is evaluated. -For example, when the symbol @code{fill-column} by itself is evaluated, -it returns a number. This number can be used in an addition. - -@need 1250 -Position the cursor after the following expression and type @kbd{C-x -C-e}: - -@smallexample -(+ 2 fill-column) -@end smallexample - -@noindent -The value will be a number two more than what you get by evaluating -@code{fill-column} alone. For me, this is 74, because my value of -@code{fill-column} is 72. - -As we have just seen, an argument can be a symbol that returns a value -when evaluated. In addition, an argument can be a list that returns a -value when it is evaluated. For example, in the following expression, -the arguments to the function @code{concat} are the strings -@w{@code{"The "}} and @w{@code{" red foxes."}} and the list -@code{(number-to-string (+ 2 fill-column))}. - -@c For GNU Emacs 22, need number-to-string -@smallexample -(concat "The " (number-to-string (+ 2 fill-column)) " red foxes.") -@end smallexample - -@noindent -If you evaluate this expression---and if, as with my Emacs, -@code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will -appear in the echo area. (Note that you must put spaces after the -word @samp{The} and before the word @samp{red} so they will appear in -the final string. The function @code{number-to-string} converts the -integer that the addition function returns to a string. -@code{number-to-string} is also known as @code{int-to-string}.) - -@node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments -@comment node-name, next, previous, up -@subsection Variable Number of Arguments -@cindex Variable number of arguments -@cindex Arguments, variable number of - -Some functions, such as @code{concat}, @code{+} or @code{*}, take any -number of arguments. (The @code{*} is the symbol for multiplication.) -This can be seen by evaluating each of the following expressions in -the usual way. What you will see in the echo area is printed in this -text after @samp{@result{}}, which you may read as `evaluates to'. - -@need 1250 -In the first set, the functions have no arguments: - -@smallexample -@group -(+) @result{} 0 - -(*) @result{} 1 -@end group -@end smallexample - -@need 1250 -In this set, the functions have one argument each: - -@smallexample -@group -(+ 3) @result{} 3 - -(* 3) @result{} 3 -@end group -@end smallexample - -@need 1250 -In this set, the functions have three arguments each: - -@smallexample -@group -(+ 3 4 5) @result{} 12 - -(* 3 4 5) @result{} 60 -@end group -@end smallexample - -@node Wrong Type of Argument, message, Variable Number of Arguments, Arguments -@comment node-name, next, previous, up -@subsection Using the Wrong Type Object as an Argument -@cindex Wrong type of argument -@cindex Argument, wrong type of - -When a function is passed an argument of the wrong type, the Lisp -interpreter produces an error message. For example, the @code{+} -function expects the values of its arguments to be numbers. As an -experiment we can pass it the quoted symbol @code{hello} instead of a -number. Position the cursor after the following expression and type -@kbd{C-x C-e}: - -@smallexample -(+ 2 'hello) -@end smallexample - -@noindent -When you do this you will generate an error message. What has happened -is that @code{+} has tried to add the 2 to the value returned by -@code{'hello}, but the value returned by @code{'hello} is the symbol -@code{hello}, not a number. Only numbers can be added. So @code{+} -could not carry out its addition. - -@need 1250 -In GNU Emacs version 22, you will create and enter a -@file{*Backtrace*} buffer that says: - -@noindent -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: - (wrong-type-argument number-or-marker-p hello) - +(2 hello) - eval((+ 2 (quote hello))) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@need 1250 -As usual, the error message tries to be helpful and makes sense after you -learn how to read it.@footnote{@code{(quote hello)} is an expansion of -the abbreviation @code{'hello}.} - -The first part of the error message is straightforward; it says -@samp{wrong type argument}. Next comes the mysterious jargon word -@w{@samp{number-or-marker-p}}. This word is trying to tell you what -kind of argument the @code{+} expected. - -The symbol @code{number-or-marker-p} says that the Lisp interpreter is -trying to determine whether the information presented it (the value of -the argument) is a number or a marker (a special object representing a -buffer position). What it does is test to see whether the @code{+} is -being given numbers to add. It also tests to see whether the -argument is something called a marker, which is a specific feature of -Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers. -When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command, -its position is kept as a marker. The mark can be considered a -number---the number of characters the location is from the beginning -of the buffer.) In Emacs Lisp, @code{+} can be used to add the -numeric value of marker positions as numbers. - -The @samp{p} of @code{number-or-marker-p} is the embodiment of a -practice started in the early days of Lisp programming. The @samp{p} -stands for `predicate'. In the jargon used by the early Lisp -researchers, a predicate refers to a function to determine whether some -property is true or false. So the @samp{p} tells us that -@code{number-or-marker-p} is the name of a function that determines -whether it is true or false that the argument supplied is a number or -a marker. Other Lisp symbols that end in @samp{p} include @code{zerop}, -a function that tests whether its argument has the value of zero, and -@code{listp}, a function that tests whether its argument is a list. - -Finally, the last part of the error message is the symbol @code{hello}. -This is the value of the argument that was passed to @code{+}. If the -addition had been passed the correct type of object, the value passed -would have been a number, such as 37, rather than a symbol like -@code{hello}. But then you would not have got the error message. - -@ignore -@need 1250 -In GNU Emacs version 20 and before, the echo area displays an error -message that says: - -@smallexample -Wrong type argument:@: number-or-marker-p, hello -@end smallexample - -This says, in different words, the same as the top line of the -@file{*Backtrace*} buffer. -@end ignore - -@node message, , Wrong Type of Argument, Arguments -@comment node-name, next, previous, up -@subsection The @code{message} Function -@findex message - -Like @code{+}, the @code{message} function takes a variable number of -arguments. It is used to send messages to the user and is so useful -that we will describe it here. - -@need 1250 -A message is printed in the echo area. For example, you can print a -message in your echo area by evaluating the following list: - -@smallexample -(message "This message appears in the echo area!") -@end smallexample - -The whole string between double quotation marks is a single argument -and is printed @i{in toto}. (Note that in this example, the message -itself will appear in the echo area within double quotes; that is -because you see the value returned by the @code{message} function. In -most uses of @code{message} in programs that you write, the text will -be printed in the echo area as a side-effect, without the quotes. -@xref{multiply-by-seven in detail, , @code{multiply-by-seven} in -detail}, for an example of this.) - -However, if there is a @samp{%s} in the quoted string of characters, the -@code{message} function does not print the @samp{%s} as such, but looks -to the argument that follows the string. It evaluates the second -argument and prints the value at the location in the string where the -@samp{%s} is. - -@need 1250 -You can see this by positioning the cursor after the following -expression and typing @kbd{C-x C-e}: - -@smallexample -(message "The name of this buffer is: %s." (buffer-name)) -@end smallexample - -@noindent -In Info, @code{"The name of this buffer is: *info*."} will appear in the -echo area. The function @code{buffer-name} returns the name of the -buffer as a string, which the @code{message} function inserts in place -of @code{%s}. - -To print a value as an integer, use @samp{%d} in the same way as -@samp{%s}. For example, to print a message in the echo area that -states the value of the @code{fill-column}, evaluate the following: - -@smallexample -(message "The value of fill-column is %d." fill-column) -@end smallexample - -@noindent -On my system, when I evaluate this list, @code{"The value of -fill-column is 72."} appears in my echo area@footnote{Actually, you -can use @code{%s} to print a number. It is non-specific. @code{%d} -prints only the part of a number left of a decimal point, and not -anything that is not a number.}. - -If there is more than one @samp{%s} in the quoted string, the value of -the first argument following the quoted string is printed at the -location of the first @samp{%s} and the value of the second argument is -printed at the location of the second @samp{%s}, and so on. - -@need 1250 -For example, if you evaluate the following, - -@smallexample -@group -(message "There are %d %s in the office!" - (- fill-column 14) "pink elephants") -@end group -@end smallexample - -@noindent -a rather whimsical message will appear in your echo area. On my system -it says, @code{"There are 58 pink elephants in the office!"}. - -The expression @code{(- fill-column 14)} is evaluated and the resulting -number is inserted in place of the @samp{%d}; and the string in double -quotes, @code{"pink elephants"}, is treated as a single argument and -inserted in place of the @samp{%s}. (That is to say, a string between -double quotes evaluates to itself, like a number.) - -Finally, here is a somewhat complex example that not only illustrates -the computation of a number, but also shows how you can use an -expression within an expression to generate the text that is substituted -for @samp{%s}: - -@smallexample -@group -(message "He saw %d %s" - (- fill-column 32) - (concat "red " - (substring - "The quick brown foxes jumped." 16 21) - " leaping.")) -@end group -@end smallexample - -In this example, @code{message} has three arguments: the string, -@code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and -the expression beginning with the function @code{concat}. The value -resulting from the evaluation of @code{(- fill-column 32)} is inserted -in place of the @samp{%d}; and the value returned by the expression -beginning with @code{concat} is inserted in place of the @samp{%s}. - -When your fill column is 70 and you evaluate the expression, the -message @code{"He saw 38 red foxes leaping."} appears in your echo -area. - -@node set & setq, Summary, Arguments, List Processing -@comment node-name, next, previous, up -@section Setting the Value of a Variable -@cindex Variable, setting value -@cindex Setting value of variable - -@cindex @samp{bind} defined -There are several ways by which a variable can be given a value. One of -the ways is to use either the function @code{set} or the function -@code{setq}. Another way is to use @code{let} (@pxref{let}). (The -jargon for this process is to @dfn{bind} a variable to a value.) - -The following sections not only describe how @code{set} and @code{setq} -work but also illustrate how arguments are passed. - -@menu -* Using set:: Setting values. -* Using setq:: Setting a quoted value. -* Counting:: Using @code{setq} to count. -@end menu - -@node Using set, Using setq, set & setq, set & setq -@comment node-name, next, previous, up -@subsection Using @code{set} -@findex set - -To set the value of the symbol @code{flowers} to the list @code{'(rose -violet daisy buttercup)}, evaluate the following expression by -positioning the cursor after the expression and typing @kbd{C-x C-e}. - -@smallexample -(set 'flowers '(rose violet daisy buttercup)) -@end smallexample - -@noindent -The list @code{(rose violet daisy buttercup)} will appear in the echo -area. This is what is @emph{returned} by the @code{set} function. As a -side effect, the symbol @code{flowers} is bound to the list; that is, -the symbol @code{flowers}, which can be viewed as a variable, is given -the list as its value. (This process, by the way, illustrates how a -side effect to the Lisp interpreter, setting the value, can be the -primary effect that we humans are interested in. This is because every -Lisp function must return a value if it does not get an error, but it -will only have a side effect if it is designed to have one.) - -After evaluating the @code{set} expression, you can evaluate the symbol -@code{flowers} and it will return the value you just set. Here is the -symbol. Place your cursor after it and type @kbd{C-x C-e}. - -@smallexample -flowers -@end smallexample - -@noindent -When you evaluate @code{flowers}, the list -@code{(rose violet daisy buttercup)} appears in the echo area. - -Incidentally, if you evaluate @code{'flowers}, the variable with a quote -in front of it, what you will see in the echo area is the symbol itself, -@code{flowers}. Here is the quoted symbol, so you can try this: - -@smallexample -'flowers -@end smallexample - -Note also, that when you use @code{set}, you need to quote both -arguments to @code{set}, unless you want them evaluated. Since we do -not want either argument evaluated, neither the variable -@code{flowers} nor the list @code{(rose violet daisy buttercup)}, both -are quoted. (When you use @code{set} without quoting its first -argument, the first argument is evaluated before anything else is -done. If you did this and @code{flowers} did not have a value -already, you would get an error message that the @samp{Symbol's value -as variable is void}; on the other hand, if @code{flowers} did return -a value after it was evaluated, the @code{set} would attempt to set -the value that was returned. There are situations where this is the -right thing for the function to do; but such situations are rare.) - -@node Using setq, Counting, Using set, set & setq -@comment node-name, next, previous, up -@subsection Using @code{setq} -@findex setq - -As a practical matter, you almost always quote the first argument to -@code{set}. The combination of @code{set} and a quoted first argument -is so common that it has its own name: the special form @code{setq}. -This special form is just like @code{set} except that the first argument -is quoted automatically, so you don't need to type the quote mark -yourself. Also, as an added convenience, @code{setq} permits you to set -several different variables to different values, all in one expression. - -To set the value of the variable @code{carnivores} to the list -@code{'(lion tiger leopard)} using @code{setq}, the following expression -is used: - -@smallexample -(setq carnivores '(lion tiger leopard)) -@end smallexample - -@noindent -This is exactly the same as using @code{set} except the first argument -is automatically quoted by @code{setq}. (The @samp{q} in @code{setq} -means @code{quote}.) - -@need 1250 -With @code{set}, the expression would look like this: - -@smallexample -(set 'carnivores '(lion tiger leopard)) -@end smallexample - -Also, @code{setq} can be used to assign different values to -different variables. The first argument is bound to the value -of the second argument, the third argument is bound to the value of the -fourth argument, and so on. For example, you could use the following to -assign a list of trees to the symbol @code{trees} and a list of herbivores -to the symbol @code{herbivores}: - -@smallexample -@group -(setq trees '(pine fir oak maple) - herbivores '(gazelle antelope zebra)) -@end group -@end smallexample - -@noindent -(The expression could just as well have been on one line, but it might -not have fit on a page; and humans find it easier to read nicely -formatted lists.) - -Although I have been using the term `assign', there is another way of -thinking about the workings of @code{set} and @code{setq}; and that is to -say that @code{set} and @code{setq} make the symbol @emph{point} to the -list. This latter way of thinking is very common and in forthcoming -chapters we shall come upon at least one symbol that has `pointer' as -part of its name. The name is chosen because the symbol has a value, -specifically a list, attached to it; or, expressed another way, -the symbol is set to ``point'' to the list. - -@node Counting, , Using setq, set & setq -@comment node-name, next, previous, up -@subsection Counting -@cindex Counting - -Here is an example that shows how to use @code{setq} in a counter. You -might use this to count how many times a part of your program repeats -itself. First set a variable to zero; then add one to the number each -time the program repeats itself. To do this, you need a variable that -serves as a counter, and two expressions: an initial @code{setq} -expression that sets the counter variable to zero; and a second -@code{setq} expression that increments the counter each time it is -evaluated. - -@smallexample -@group -(setq counter 0) ; @r{Let's call this the initializer.} - -(setq counter (+ counter 1)) ; @r{This is the incrementer.} - -counter ; @r{This is the counter.} -@end group -@end smallexample - -@noindent -(The text following the @samp{;} are comments. @xref{Change a -defun, , Change a Function Definition}.) - -If you evaluate the first of these expressions, the initializer, -@code{(setq counter 0)}, and then evaluate the third expression, -@code{counter}, the number @code{0} will appear in the echo area. If -you then evaluate the second expression, the incrementer, @code{(setq -counter (+ counter 1))}, the counter will get the value 1. So if you -again evaluate @code{counter}, the number @code{1} will appear in the -echo area. Each time you evaluate the second expression, the value of -the counter will be incremented. - -When you evaluate the incrementer, @code{(setq counter (+ counter 1))}, -the Lisp interpreter first evaluates the innermost list; this is the -addition. In order to evaluate this list, it must evaluate the variable -@code{counter} and the number @code{1}. When it evaluates the variable -@code{counter}, it receives its current value. It passes this value and -the number @code{1} to the @code{+} which adds them together. The sum -is then returned as the value of the inner list and passed to the -@code{setq} which sets the variable @code{counter} to this new value. -Thus, the value of the variable, @code{counter}, is changed. - -@node Summary, Error Message Exercises, set & setq, List Processing -@comment node-name, next, previous, up -@section Summary - -Learning Lisp is like climbing a hill in which the first part is the -steepest. You have now climbed the most difficult part; what remains -becomes easier as you progress onwards. - -@need 1000 -In summary, - -@itemize @bullet - -@item -Lisp programs are made up of expressions, which are lists or single atoms. - -@item -Lists are made up of zero or more atoms or inner lists, separated by whitespace and -surrounded by parentheses. A list can be empty. - -@item -Atoms are multi-character symbols, like @code{forward-paragraph}, single -character symbols like @code{+}, strings of characters between double -quotation marks, or numbers. - -@item -A number evaluates to itself. - -@item -A string between double quotes also evaluates to itself. - -@item -When you evaluate a symbol by itself, its value is returned. - -@item -When you evaluate a list, the Lisp interpreter looks at the first symbol -in the list and then at the function definition bound to that symbol. -Then the instructions in the function definition are carried out. - -@item -A single quotation mark, -@ifinfo -' -@end ifinfo -@ifnotinfo -@code{'} -@end ifnotinfo -, tells the Lisp interpreter that it should -return the following expression as written, and not evaluate it as it -would if the quote were not there. - -@item -Arguments are the information passed to a function. The arguments to a -function are computed by evaluating the rest of the elements of the list -of which the function is the first element. - -@item -A function always returns a value when it is evaluated (unless it gets -an error); in addition, it may also carry out some action called a -``side effect''. In many cases, a function's primary purpose is to -create a side effect. -@end itemize - -@node Error Message Exercises, , Summary, List Processing -@comment node-name, next, previous, up -@section Exercises - -A few simple exercises: - -@itemize @bullet -@item -Generate an error message by evaluating an appropriate symbol that is -not within parentheses. - -@item -Generate an error message by evaluating an appropriate symbol that is -between parentheses. - -@item -Create a counter that increments by two rather than one. - -@item -Write an expression that prints a message in the echo area when -evaluated. -@end itemize - -@node Practicing Evaluation, Writing Defuns, List Processing, Top -@comment node-name, next, previous, up -@chapter Practicing Evaluation -@cindex Practicing evaluation -@cindex Evaluation practice - -Before learning how to write a function definition in Emacs Lisp, it is -useful to spend a little time evaluating various expressions that have -already been written. These expressions will be lists with the -functions as their first (and often only) element. Since some of the -functions associated with buffers are both simple and interesting, we -will start with those. In this section, we will evaluate a few of -these. In another section, we will study the code of several other -buffer-related functions, to see how they were written. - -@menu -* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} - causes evaluation. -* Buffer Names:: Buffers and files are different. -* Getting Buffers:: Getting a buffer itself, not merely its name. -* Switching Buffers:: How to change to another buffer. -* Buffer Size & Locations:: Where point is located and the size of - the buffer. -* Evaluation Exercise:: -@end menu - -@node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation -@ifnottex -@unnumberedsec How to Evaluate -@end ifnottex - -@i{Whenever you give an editing command} to Emacs Lisp, such as the -command to move the cursor or to scroll the screen, @i{you are evaluating -an expression,} the first element of which is a function. @i{This is -how Emacs works.} - -@cindex @samp{interactive function} defined -@cindex @samp{command} defined -When you type keys, you cause the Lisp interpreter to evaluate an -expression and that is how you get your results. Even typing plain text -involves evaluating an Emacs Lisp function, in this case, one that uses -@code{self-insert-command}, which simply inserts the character you -typed. The functions you evaluate by typing keystrokes are called -@dfn{interactive} functions, or @dfn{commands}; how you make a function -interactive will be illustrated in the chapter on how to write function -definitions. @xref{Interactive, , Making a Function Interactive}. - -In addition to typing keyboard commands, we have seen a second way to -evaluate an expression: by positioning the cursor after a list and -typing @kbd{C-x C-e}. This is what we will do in the rest of this -section. There are other ways to evaluate an expression as well; these -will be described as we come to them. - -Besides being used for practicing evaluation, the functions shown in the -next few sections are important in their own right. A study of these -functions makes clear the distinction between buffers and files, how to -switch to a buffer, and how to determine a location within it. - -@node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation -@comment node-name, next, previous, up -@section Buffer Names -@findex buffer-name -@findex buffer-file-name - -The two functions, @code{buffer-name} and @code{buffer-file-name}, show -the difference between a file and a buffer. When you evaluate the -following expression, @code{(buffer-name)}, the name of the buffer -appears in the echo area. When you evaluate @code{(buffer-file-name)}, -the name of the file to which the buffer refers appears in the echo -area. Usually, the name returned by @code{(buffer-name)} is the same as -the name of the file to which it refers, and the name returned by -@code{(buffer-file-name)} is the full path-name of the file. - -A file and a buffer are two different entities. A file is information -recorded permanently in the computer (unless you delete it). A buffer, -on the other hand, is information inside of Emacs that will vanish at -the end of the editing session (or when you kill the buffer). Usually, -a buffer contains information that you have copied from a file; we say -the buffer is @dfn{visiting} that file. This copy is what you work on -and modify. Changes to the buffer do not change the file, until you -save the buffer. When you save the buffer, the buffer is copied to the file -and is thus saved permanently. - -@need 1250 -If you are reading this in Info inside of GNU Emacs, you can evaluate -each of the following expressions by positioning the cursor after it and -typing @kbd{C-x C-e}. - -@example -@group -(buffer-name) - -(buffer-file-name) -@end group -@end example - -@noindent -When I do this in Info, the value returned by evaluating -@code{(buffer-name)} is @file{"*info*"}, and the value returned by -evaluating @code{(buffer-file-name)} is @file{nil}. - -On the other hand, while I am writing this Introduction, the value -returned by evaluating @code{(buffer-name)} is -@file{"introduction.texinfo"}, and the value returned by evaluating -@code{(buffer-file-name)} is -@file{"/gnu/work/intro/introduction.texinfo"}. - -@cindex @code{nil}, history of word -The former is the name of the buffer and the latter is the name of the -file. In Info, the buffer name is @file{"*info*"}. Info does not -point to any file, so the result of evaluating -@code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is -from the Latin word for `nothing'; in this case, it means that the -buffer is not associated with any file. (In Lisp, @code{nil} is also -used to mean `false' and is a synonym for the empty list, @code{()}.) - -When I am writing, the name of my buffer is -@file{"introduction.texinfo"}. The name of the file to which it -points is @file{"/gnu/work/intro/introduction.texinfo"}. - -(In the expressions, the parentheses tell the Lisp interpreter to -treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as -functions; without the parentheses, the interpreter would attempt to -evaluate the symbols as variables. @xref{Variables}.) - -In spite of the distinction between files and buffers, you will often -find that people refer to a file when they mean a buffer and vice-verse. -Indeed, most people say, ``I am editing a file,'' rather than saying, -``I am editing a buffer which I will soon save to a file.'' It is -almost always clear from context what people mean. When dealing with -computer programs, however, it is important to keep the distinction in mind, -since the computer is not as smart as a person. - -@cindex Buffer, history of word -The word `buffer', by the way, comes from the meaning of the word as a -cushion that deadens the force of a collision. In early computers, a -buffer cushioned the interaction between files and the computer's -central processing unit. The drums or tapes that held a file and the -central processing unit were pieces of equipment that were very -different from each other, working at their own speeds, in spurts. The -buffer made it possible for them to work together effectively. -Eventually, the buffer grew from being an intermediary, a temporary -holding place, to being the place where work is done. This -transformation is rather like that of a small seaport that grew into a -great city: once it was merely the place where cargo was warehoused -temporarily before being loaded onto ships; then it became a business -and cultural center in its own right. - -Not all buffers are associated with files. For example, a -@file{*scratch*} buffer does not visit any file. Similarly, a -@file{*Help*} buffer is not associated with any file. - -In the old days, when you lacked a @file{~/.emacs} file and started an -Emacs session by typing the command @code{emacs} alone, without naming -any files, Emacs started with the @file{*scratch*} buffer visible. -Nowadays, you will see a splash screen. You can follow one of the -commands suggested on the splash screen, visit a file, or press the -spacebar to reach the @file{*scratch*} buffer. - -If you switch to the @file{*scratch*} buffer, type -@code{(buffer-name)}, position the cursor after it, and then type -@kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"} -will be returned and will appear in the echo area. @code{"*scratch*"} -is the name of the buffer. When you type @code{(buffer-file-name)} in -the @file{*scratch*} buffer and evaluate that, @code{nil} will appear -in the echo area, just as it does when you evaluate -@code{(buffer-file-name)} in Info. - -Incidentally, if you are in the @file{*scratch*} buffer and want the -value returned by an expression to appear in the @file{*scratch*} -buffer itself rather than in the echo area, type @kbd{C-u C-x C-e} -instead of @kbd{C-x C-e}. This causes the value returned to appear -after the expression. The buffer will look like this: - -@smallexample -(buffer-name)"*scratch*" -@end smallexample - -@noindent -You cannot do this in Info since Info is read-only and it will not allow -you to change the contents of the buffer. But you can do this in any -buffer you can edit; and when you write code or documentation (such as -this book), this feature is very useful. - -@node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation -@comment node-name, next, previous, up -@section Getting Buffers -@findex current-buffer -@findex other-buffer -@cindex Getting a buffer - -The @code{buffer-name} function returns the @emph{name} of the buffer; -to get the buffer @emph{itself}, a different function is needed: the -@code{current-buffer} function. If you use this function in code, what -you get is the buffer itself. - -A name and the object or entity to which the name refers are different -from each other. You are not your name. You are a person to whom -others refer by name. If you ask to speak to George and someone hands you -a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r}, -@samp{g}, and @samp{e} written on it, you might be amused, but you would -not be satisfied. You do not want to speak to the name, but to the -person to whom the name refers. A buffer is similar: the name of the -scratch buffer is @file{*scratch*}, but the name is not the buffer. To -get a buffer itself, you need to use a function such as -@code{current-buffer}. - -However, there is a slight complication: if you evaluate -@code{current-buffer} in an expression on its own, as we will do here, -what you see is a printed representation of the name of the buffer -without the contents of the buffer. Emacs works this way for two -reasons: the buffer may be thousands of lines long---too long to be -conveniently displayed; and, another buffer may have the same contents -but a different name, and it is important to distinguish between them. - -@need 800 -Here is an expression containing the function: - -@smallexample -(current-buffer) -@end smallexample - -@noindent -If you evaluate this expression in Info in Emacs in the usual way, -@file{#<buffer *info*>} will appear in the echo area. The special -format indicates that the buffer itself is being returned, rather than -just its name. - -Incidentally, while you can type a number or symbol into a program, you -cannot do that with the printed representation of a buffer: the only way -to get a buffer itself is with a function such as @code{current-buffer}. - -A related function is @code{other-buffer}. This returns the most -recently selected buffer other than the one you are in currently, not -a printed representation of its name. If you have recently switched -back and forth from the @file{*scratch*} buffer, @code{other-buffer} -will return that buffer. - -@need 800 -You can see this by evaluating the expression: - -@smallexample -(other-buffer) -@end smallexample - -@noindent -You should see @file{#<buffer *scratch*>} appear in the echo area, or -the name of whatever other buffer you switched back from most -recently@footnote{Actually, by default, if the buffer from which you -just switched is visible to you in another window, @code{other-buffer} -will choose the most recent buffer that you cannot see; this is a -subtlety that I often forget.}. - -@node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation -@comment node-name, next, previous, up -@section Switching Buffers -@findex switch-to-buffer -@findex set-buffer -@cindex Switching to a buffer - -The @code{other-buffer} function actually provides a buffer when it is -used as an argument to a function that requires one. We can see this -by using @code{other-buffer} and @code{switch-to-buffer} to switch to a -different buffer. - -But first, a brief introduction to the @code{switch-to-buffer} -function. When you switched back and forth from Info to the -@file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most -likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or -rather, to save typing, you probably only typed @kbd{RET} if the -default buffer was @file{*scratch*}, or if it was different, then you -typed just part of the name, such as @code{*sc}, pressed your -@kbd{TAB} key to cause it to expand to the full name, and then typed -your @kbd{RET} key.} when prompted in the minibuffer for the name of -the buffer to which you wanted to switch. The keystrokes, @kbd{C-x -b}, cause the Lisp interpreter to evaluate the interactive function -@code{switch-to-buffer}. As we said before, this is how Emacs works: -different keystrokes call or run different functions. For example, -@kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls -@code{forward-sentence}, and so on. - -By writing @code{switch-to-buffer} in an expression, and giving it a -buffer to switch to, we can switch buffers just the way @kbd{C-x b} -does. - -@need 1000 -Here is the Lisp expression: - -@smallexample -(switch-to-buffer (other-buffer)) -@end smallexample - -@noindent -The symbol @code{switch-to-buffer} is the first element of the list, -so the Lisp interpreter will treat it as a function and carry out the -instructions that are attached to it. But before doing that, the -interpreter will note that @code{other-buffer} is inside parentheses -and work on that symbol first. @code{other-buffer} is the first (and -in this case, the only) element of this list, so the Lisp interpreter -calls or runs the function. It returns another buffer. Next, the -interpreter runs @code{switch-to-buffer}, passing to it, as an -argument, the other buffer, which is what Emacs will switch to. If -you are reading this in Info, try this now. Evaluate the expression. -(To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this -expression will move you to your most recent other buffer that you -cannot see. If you really want to go to your most recently selected -buffer, even if you can still see it, you need to evaluate the -following more complex expression: - -@smallexample -(switch-to-buffer (other-buffer (current-buffer) t)) -@end smallexample - -@c noindent -In this case, the first argument to @code{other-buffer} tells it which -buffer to skip---the current one---and the second argument tells -@code{other-buffer} it is OK to switch to a visible buffer. -In regular use, @code{switch-to-buffer} takes you to an invisible -window since you would most likely use @kbd{C-x o} (@code{other-window}) -to go to another visible buffer.} - -In the programming examples in later sections of this document, you will -see the function @code{set-buffer} more often than -@code{switch-to-buffer}. This is because of a difference between -computer programs and humans: humans have eyes and expect to see the -buffer on which they are working on their computer terminals. This is -so obvious, it almost goes without saying. However, programs do not -have eyes. When a computer program works on a buffer, that buffer does -not need to be visible on the screen. - -@code{switch-to-buffer} is designed for humans and does two different -things: it switches the buffer to which Emacs' attention is directed; and -it switches the buffer displayed in the window to the new buffer. -@code{set-buffer}, on the other hand, does only one thing: it switches -the attention of the computer program to a different buffer. The buffer -on the screen remains unchanged (of course, normally nothing happens -there until the command finishes running). - -@cindex @samp{call} defined -Also, we have just introduced another jargon term, the word @dfn{call}. -When you evaluate a list in which the first symbol is a function, you -are calling that function. The use of the term comes from the notion of -the function as an entity that can do something for you if you `call' -it---just as a plumber is an entity who can fix a leak if you call him -or her. - -@node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation -@comment node-name, next, previous, up -@section Buffer Size and the Location of Point -@cindex Size of buffer -@cindex Buffer size -@cindex Point location -@cindex Location of point - -Finally, let's look at several rather simple functions, -@code{buffer-size}, @code{point}, @code{point-min}, and -@code{point-max}. These give information about the size of a buffer and -the location of point within it. - -The function @code{buffer-size} tells you the size of the current -buffer; that is, the function returns a count of the number of -characters in the buffer. - -@smallexample -(buffer-size) -@end smallexample - -@noindent -You can evaluate this in the usual way, by positioning the -cursor after the expression and typing @kbd{C-x C-e}. - -@cindex @samp{point} defined -In Emacs, the current position of the cursor is called @dfn{point}. -The expression @code{(point)} returns a number that tells you where the -cursor is located as a count of the number of characters from the -beginning of the buffer up to point. - -@need 1250 -You can see the character count for point in this buffer by evaluating -the following expression in the usual way: - -@smallexample -(point) -@end smallexample - -@noindent -As I write this, the value of @code{point} is 65724. The @code{point} -function is frequently used in some of the examples later in this -book. - -@need 1250 -The value of point depends, of course, on its location within the -buffer. If you evaluate point in this spot, the number will be larger: - -@smallexample -(point) -@end smallexample - -@noindent -For me, the value of point in this location is 66043, which means that -there are 319 characters (including spaces) between the two -expressions. (Doubtless, you will see different numbers, since I will -have edited this since I first evaluated point.) - -@cindex @samp{narrowing} defined -The function @code{point-min} is somewhat similar to @code{point}, but -it returns the value of the minimum permissible value of point in the -current buffer. This is the number 1 unless @dfn{narrowing} is in -effect. (Narrowing is a mechanism whereby you can restrict yourself, -or a program, to operations on just a part of a buffer. -@xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the -function @code{point-max} returns the value of the maximum permissible -value of point in the current buffer. - -@node Evaluation Exercise, , Buffer Size & Locations, Practicing Evaluation -@section Exercise - -Find a file with which you are working and move towards its middle. -Find its buffer name, file name, length, and your position in the file. - -@node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top -@comment node-name, next, previous, up -@chapter How To Write Function Definitions -@cindex Definition writing -@cindex Function definition writing -@cindex Writing a function definition - -When the Lisp interpreter evaluates a list, it looks to see whether the -first symbol on the list has a function definition attached to it; or, -put another way, whether the symbol points to a function definition. If -it does, the computer carries out the instructions in the definition. A -symbol that has a function definition is called, simply, a function -(although, properly speaking, the definition is the function and the -symbol refers to it.) - -@menu -* Primitive Functions:: -* defun:: The @code{defun} special form. -* Install:: Install a function definition. -* Interactive:: Making a function interactive. -* Interactive Options:: Different options for @code{interactive}. -* Permanent Installation:: Installing code permanently. -* let:: Creating and initializing local variables. -* if:: What if? -* else:: If--then--else expressions. -* Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. -* Review:: -* defun Exercises:: -@end menu - -@node Primitive Functions, defun, Writing Defuns, Writing Defuns -@ifnottex -@unnumberedsec An Aside about Primitive Functions -@end ifnottex -@cindex Primitive functions -@cindex Functions, primitive - -@cindex C language primitives -@cindex Primitives written in C -All functions are defined in terms of other functions, except for a few -@dfn{primitive} functions that are written in the C programming -language. When you write functions' definitions, you will write them in -Emacs Lisp and use other functions as your building blocks. Some of the -functions you will use will themselves be written in Emacs Lisp (perhaps -by you) and some will be primitives written in C. The primitive -functions are used exactly like those written in Emacs Lisp and behave -like them. They are written in C so we can easily run GNU Emacs on any -computer that has sufficient power and can run C. - -Let me re-emphasize this: when you write code in Emacs Lisp, you do not -distinguish between the use of functions written in C and the use of -functions written in Emacs Lisp. The difference is irrelevant. I -mention the distinction only because it is interesting to know. Indeed, -unless you investigate, you won't know whether an already-written -function is written in Emacs Lisp or C. - -@node defun, Install, Primitive Functions, Writing Defuns -@comment node-name, next, previous, up -@section The @code{defun} Special Form -@findex defun -@cindex Special form of @code{defun} - -@cindex @samp{function definition} defined -In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to -it that tells the computer what to do when the function is called. -This code is called the @dfn{function definition} and is created by -evaluating a Lisp expression that starts with the symbol @code{defun} -(which is an abbreviation for @emph{define function}). Because -@code{defun} does not evaluate its arguments in the usual way, it is -called a @dfn{special form}. - -In subsequent sections, we will look at function definitions from the -Emacs source code, such as @code{mark-whole-buffer}. In this section, -we will describe a simple function definition so you can see how it -looks. This function definition uses arithmetic because it makes for a -simple example. Some people dislike examples using arithmetic; however, -if you are such a person, do not despair. Hardly any of the code we -will study in the remainder of this introduction involves arithmetic or -mathematics. The examples mostly involve text in one way or another. - -A function definition has up to five parts following the word -@code{defun}: - -@enumerate -@item -The name of the symbol to which the function definition should be -attached. - -@item -A list of the arguments that will be passed to the function. If no -arguments will be passed to the function, this is an empty list, -@code{()}. - -@item -Documentation describing the function. (Technically optional, but -strongly recommended.) - -@item -Optionally, an expression to make the function interactive so you can -use it by typing @kbd{M-x} and then the name of the function; or by -typing an appropriate key or keychord. - -@cindex @samp{body} defined -@item -The code that instructs the computer what to do: the @dfn{body} of the -function definition. -@end enumerate - -It is helpful to think of the five parts of a function definition as -being organized in a template, with slots for each part: - -@smallexample -@group -(defun @var{function-name} (@var{arguments}@dots{}) - "@var{optional-documentation}@dots{}" - (interactive @var{argument-passing-info}) ; @r{optional} - @var{body}@dots{}) -@end group -@end smallexample - -As an example, here is the code for a function that multiplies its -argument by 7. (This example is not interactive. @xref{Interactive, -, Making a Function Interactive}, for that information.) - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) -@end group -@end smallexample - -This definition begins with a parenthesis and the symbol @code{defun}, -followed by the name of the function. - -@cindex @samp{argument list} defined -The name of the function is followed by a list that contains the -arguments that will be passed to the function. This list is called -the @dfn{argument list}. In this example, the list has only one -element, the symbol, @code{number}. When the function is used, the -symbol will be bound to the value that is used as the argument to the -function. - -Instead of choosing the word @code{number} for the name of the argument, -I could have picked any other name. For example, I could have chosen -the word @code{multiplicand}. I picked the word `number' because it -tells what kind of value is intended for this slot; but I could just as -well have chosen the word `multiplicand' to indicate the role that the -value placed in this slot will play in the workings of the function. I -could have called it @code{foogle}, but that would have been a bad -choice because it would not tell humans what it means. The choice of -name is up to the programmer and should be chosen to make the meaning of -the function clear. - -Indeed, you can choose any name you wish for a symbol in an argument -list, even the name of a symbol used in some other function: the name -you use in an argument list is private to that particular definition. -In that definition, the name refers to a different entity than any use -of the same name outside the function definition. Suppose you have a -nick-name `Shorty' in your family; when your family members refer to -`Shorty', they mean you. But outside your family, in a movie, for -example, the name `Shorty' refers to someone else. Because a name in an -argument list is private to the function definition, you can change the -value of such a symbol inside the body of a function without changing -its value outside the function. The effect is similar to that produced -by a @code{let} expression. (@xref{let, , @code{let}}.) - -@ignore -Note also that we discuss the word `number' in two different ways: as a -symbol that appears in the code, and as the name of something that will -be replaced by a something else during the evaluation of the function. -In the first case, @code{number} is a symbol, not a number; it happens -that within the function, it is a variable who value is the number in -question, but our primary interest in it is as a symbol. On the other -hand, when we are talking about the function, our interest is that we -will substitute a number for the word @var{number}. To keep this -distinction clear, we use different typography for the two -circumstances. When we talk about this function, or about how it works, -we refer to this number by writing @var{number}. In the function -itself, we refer to it by writing @code{number}. -@end ignore - -The argument list is followed by the documentation string that -describes the function. This is what you see when you type -@w{@kbd{C-h f}} and the name of a function. Incidentally, when you -write a documentation string like this, you should make the first line -a complete sentence since some commands, such as @code{apropos}, print -only the first line of a multi-line documentation string. Also, you -should not indent the second line of a documentation string, if you -have one, because that looks odd when you use @kbd{C-h f} -(@code{describe-function}). The documentation string is optional, but -it is so useful, it should be included in almost every function you -write. - -@findex * @r{(multiplication)} -The third line of the example consists of the body of the function -definition. (Most functions' definitions, of course, are longer than -this.) In this function, the body is the list, @code{(* 7 number)}, which -says to multiply the value of @var{number} by 7. (In Emacs Lisp, -@code{*} is the function for multiplication, just as @code{+} is the -function for addition.) - -When you use the @code{multiply-by-seven} function, the argument -@code{number} evaluates to the actual number you want used. Here is an -example that shows how @code{multiply-by-seven} is used; but don't try -to evaluate this yet! - -@smallexample -(multiply-by-seven 3) -@end smallexample - -@noindent -The symbol @code{number}, specified in the function definition in the -next section, is given or ``bound to'' the value 3 in the actual use of -the function. Note that although @code{number} was inside parentheses -in the function definition, the argument passed to the -@code{multiply-by-seven} function is not in parentheses. The -parentheses are written in the function definition so the computer can -figure out where the argument list ends and the rest of the function -definition begins. - -If you evaluate this example, you are likely to get an error message. -(Go ahead, try it!) This is because we have written the function -definition, but not yet told the computer about the definition---we have -not yet installed (or `loaded') the function definition in Emacs. -Installing a function is the process that tells the Lisp interpreter the -definition of the function. Installation is described in the next -section. - -@node Install, Interactive, defun, Writing Defuns -@comment node-name, next, previous, up -@section Install a Function Definition -@cindex Install a Function Definition -@cindex Definition installation -@cindex Function definition installation - -If you are reading this inside of Info in Emacs, you can try out the -@code{multiply-by-seven} function by first evaluating the function -definition and then evaluating @code{(multiply-by-seven 3)}. A copy of -the function definition follows. Place the cursor after the last -parenthesis of the function definition and type @kbd{C-x C-e}. When you -do this, @code{multiply-by-seven} will appear in the echo area. (What -this means is that when a function definition is evaluated, the value it -returns is the name of the defined function.) At the same time, this -action installs the function definition. - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) -@end group -@end smallexample - -@noindent -By evaluating this @code{defun}, you have just installed -@code{multiply-by-seven} in Emacs. The function is now just as much a -part of Emacs as @code{forward-word} or any other editing function you -use. (@code{multiply-by-seven} will stay installed until you quit -Emacs. To reload code automatically whenever you start Emacs, see -@ref{Permanent Installation, , Installing Code Permanently}.) - -@menu -* Effect of installation:: -* Change a defun:: How to change a function definition. -@end menu - -@node Effect of installation, Change a defun, Install, Install -@ifnottex -@unnumberedsubsec The effect of installation -@end ifnottex - -You can see the effect of installing @code{multiply-by-seven} by -evaluating the following sample. Place the cursor after the following -expression and type @kbd{C-x C-e}. The number 21 will appear in the -echo area. - -@smallexample -(multiply-by-seven 3) -@end smallexample - -If you wish, you can read the documentation for the function by typing -@kbd{C-h f} (@code{describe-function}) and then the name of the -function, @code{multiply-by-seven}. When you do this, a -@file{*Help*} window will appear on your screen that says: - -@smallexample -@group -multiply-by-seven is a Lisp function. -(multiply-by-seven NUMBER) - -Multiply NUMBER by seven. -@end group -@end smallexample - -@noindent -(To return to a single window on your screen, type @kbd{C-x 1}.) - -@node Change a defun, , Effect of installation, Install -@comment node-name, next, previous, up -@subsection Change a Function Definition -@cindex Changing a function definition -@cindex Function definition, how to change -@cindex Definition, how to change - -If you want to change the code in @code{multiply-by-seven}, just rewrite -it. To install the new version in place of the old one, evaluate the -function definition again. This is how you modify code in Emacs. It is -very simple. - -As an example, you can change the @code{multiply-by-seven} function to -add the number to itself seven times instead of multiplying the number -by seven. It produces the same answer, but by a different path. At -the same time, we will add a comment to the code; a comment is text -that the Lisp interpreter ignores, but that a human reader may find -useful or enlightening. The comment is that this is the ``second -version''. - -@smallexample -@group -(defun multiply-by-seven (number) ; @r{Second version.} - "Multiply NUMBER by seven." - (+ number number number number number number number)) -@end group -@end smallexample - -@cindex Comments in Lisp code -The comment follows a semicolon, @samp{;}. In Lisp, everything on a -line that follows a semicolon is a comment. The end of the line is the -end of the comment. To stretch a comment over two or more lines, begin -each line with a semicolon. - -@xref{Beginning a .emacs File, , Beginning a @file{.emacs} -File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp -Reference Manual}, for more about comments. - -You can install this version of the @code{multiply-by-seven} function by -evaluating it in the same way you evaluated the first function: place -the cursor after the last parenthesis and type @kbd{C-x C-e}. - -In summary, this is how you write code in Emacs Lisp: you write a -function; install it; test it; and then make fixes or enhancements and -install it again. - -@node Interactive, Interactive Options, Install, Writing Defuns -@comment node-name, next, previous, up -@section Make a Function Interactive -@cindex Interactive functions -@findex interactive - -You make a function interactive by placing a list that begins with -the special form @code{interactive} immediately after the -documentation. A user can invoke an interactive function by typing -@kbd{M-x} and then the name of the function; or by typing the keys to -which it is bound, for example, by typing @kbd{C-n} for -@code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}. - -Interestingly, when you call an interactive function interactively, -the value returned is not automatically displayed in the echo area. -This is because you often call an interactive function for its side -effects, such as moving forward by a word or line, and not for the -value returned. If the returned value were displayed in the echo area -each time you typed a key, it would be very distracting. - -@menu -* Interactive multiply-by-seven:: An overview. -* multiply-by-seven in detail:: The interactive version. -@end menu - -@node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive -@ifnottex -@unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview -@end ifnottex - -Both the use of the special form @code{interactive} and one way to -display a value in the echo area can be illustrated by creating an -interactive version of @code{multiply-by-seven}. - -@need 1250 -Here is the code: - -@smallexample -@group -(defun multiply-by-seven (number) ; @r{Interactive version.} - "Multiply NUMBER by seven." - (interactive "p") - (message "The result is %d" (* 7 number))) -@end group -@end smallexample - -@noindent -You can install this code by placing your cursor after it and typing -@kbd{C-x C-e}. The name of the function will appear in your echo area. -Then, you can use this code by typing @kbd{C-u} and a number and then -typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase -@samp{The result is @dots{}} followed by the product will appear in the -echo area. - -Speaking more generally, you invoke a function like this in either of two -ways: - -@enumerate -@item -By typing a prefix argument that contains the number to be passed, and -then typing @kbd{M-x} and the name of the function, as with -@kbd{C-u 3 M-x forward-sentence}; or, - -@item -By typing whatever key or keychord the function is bound to, as with -@kbd{C-u 3 M-e}. -@end enumerate - -@noindent -Both the examples just mentioned work identically to move point forward -three sentences. (Since @code{multiply-by-seven} is not bound to a key, -it could not be used as an example of key binding.) - -(@xref{Keybindings, , Some Keybindings}, to learn how to bind a command -to a key.) - -A prefix argument is passed to an interactive function by typing the -@key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by -typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you -type @kbd{C-u} without a number, it defaults to 4). - -@node multiply-by-seven in detail, , Interactive multiply-by-seven, Interactive -@comment node-name, next, previous, up -@subsection An Interactive @code{multiply-by-seven} - -Let's look at the use of the special form @code{interactive} and then at -the function @code{message} in the interactive version of -@code{multiply-by-seven}. You will recall that the function definition -looks like this: - -@smallexample -@group -(defun multiply-by-seven (number) ; @r{Interactive version.} - "Multiply NUMBER by seven." - (interactive "p") - (message "The result is %d" (* 7 number))) -@end group -@end smallexample - -In this function, the expression, @code{(interactive "p")}, is a list of -two elements. The @code{"p"} tells Emacs to pass the prefix argument to -the function and use its value for the argument of the function. - -@need 1000 -The argument will be a number. This means that the symbol -@code{number} will be bound to a number in the line: - -@smallexample -(message "The result is %d" (* 7 number)) -@end smallexample - -@need 1250 -@noindent -For example, if your prefix argument is 5, the Lisp interpreter will -evaluate the line as if it were: - -@smallexample -(message "The result is %d" (* 7 5)) -@end smallexample - -@noindent -(If you are reading this in GNU Emacs, you can evaluate this expression -yourself.) First, the interpreter will evaluate the inner list, which -is @code{(* 7 5)}. This returns a value of 35. Next, it -will evaluate the outer list, passing the values of the second and -subsequent elements of the list to the function @code{message}. - -As we have seen, @code{message} is an Emacs Lisp function especially -designed for sending a one line message to a user. (@xref{message, , -The @code{message} function}.) In summary, the @code{message} -function prints its first argument in the echo area as is, except for -occurrences of @samp{%d} or @samp{%s} (and various other %-sequences -which we have not mentioned). When it sees a control sequence, the -function looks to the second or subsequent arguments and prints the -value of the argument in the location in the string where the control -sequence is located. - -In the interactive @code{multiply-by-seven} function, the control string -is @samp{%d}, which requires a number, and the value returned by -evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35 -is printed in place of the @samp{%d} and the message is @samp{The result -is 35}. - -(Note that when you call the function @code{multiply-by-seven}, the -message is printed without quotes, but when you call @code{message}, the -text is printed in double quotes. This is because the value returned by -@code{message} is what appears in the echo area when you evaluate an -expression whose first element is @code{message}; but when embedded in a -function, @code{message} prints the text as a side effect without -quotes.) - -@node Interactive Options, Permanent Installation, Interactive, Writing Defuns -@comment node-name, next, previous, up -@section Different Options for @code{interactive} -@cindex Options for @code{interactive} -@cindex Interactive options - -In the example, @code{multiply-by-seven} used @code{"p"} as the -argument to @code{interactive}. This argument told Emacs to interpret -your typing either @kbd{C-u} followed by a number or @key{META} -followed by a number as a command to pass that number to the function -as its argument. Emacs has more than twenty characters predefined for -use with @code{interactive}. In almost every case, one of these -options will enable you to pass the right information interactively to -a function. (@xref{Interactive Codes, , Code Characters for -@code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.) - -@need 1250 -Consider the function @code{zap-to-char}. Its interactive expression -is - -@smallexample -(interactive "p\ncZap to char: ") -@end smallexample - -The first part of the argument to @code{interactive} is @samp{p}, with -which you are already familiar. This argument tells Emacs to -interpret a `prefix', as a number to be passed to the function. You -can specify a prefix either by typing @kbd{C-u} followed by a number -or by typing @key{META} followed by a number. The prefix is the -number of specified characters. Thus, if your prefix is three and the -specified character is @samp{x}, then you will delete all the text up -to and including the third next @samp{x}. If you do not set a prefix, -then you delete all the text up to and including the specified -character, but no more. - -The @samp{c} tells the function the name of the character to which to delete. - -More formally, a function with two or more arguments can have -information passed to each argument by adding parts to the string that -follows @code{interactive}. When you do this, the information is -passed to each argument in the same order it is specified in the -@code{interactive} list. In the string, each part is separated from -the next part by a @samp{\n}, which is a newline. For example, you -can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }. -This causes Emacs to pass the value of the prefix argument (if there -is one) and the character. - -In this case, the function definition looks like the following, where -@code{arg} and @code{char} are the symbols to which @code{interactive} -binds the prefix argument and the specified character: - -@smallexample -@group -(defun @var{name-of-function} (arg char) - "@var{documentation}@dots{}" - (interactive "p\ncZap to char: ") - @var{body-of-function}@dots{}) -@end group -@end smallexample - -@noindent -(The space after the colon in the prompt makes it look better when you -are prompted. @xref{copy-to-buffer, , The Definition of -@code{copy-to-buffer}}, for an example.) - -When a function does not take arguments, @code{interactive} does not -require any. Such a function contains the simple expression -@code{(interactive)}. The @code{mark-whole-buffer} function is like -this. - -Alternatively, if the special letter-codes are not right for your -application, you can pass your own arguments to @code{interactive} as -a list. - -@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}, -for an example. @xref{Using Interactive, , Using @code{Interactive}, -elisp, The GNU Emacs Lisp Reference Manual}, for a more complete -explanation about this technique. - -@node Permanent Installation, let, Interactive Options, Writing Defuns -@comment node-name, next, previous, up -@section Install Code Permanently -@cindex Install code permanently -@cindex Permanent code installation -@cindex Code installation - -When you install a function definition by evaluating it, it will stay -installed until you quit Emacs. The next time you start a new session -of Emacs, the function will not be installed unless you evaluate the -function definition again. - -At some point, you may want to have code installed automatically -whenever you start a new session of Emacs. There are several ways of -doing this: - -@itemize @bullet -@item -If you have code that is just for yourself, you can put the code for the -function definition in your @file{.emacs} initialization file. When you -start Emacs, your @file{.emacs} file is automatically evaluated and all -the function definitions within it are installed. -@xref{Emacs Initialization, , Your @file{.emacs} File}. - -@item -Alternatively, you can put the function definitions that you want -installed in one or more files of their own and use the @code{load} -function to cause Emacs to evaluate and thereby install each of the -functions in the files. -@xref{Loading Files, , Loading Files}. - -@item -Thirdly, if you have code that your whole site will use, it is usual -to put it in a file called @file{site-init.el} that is loaded when -Emacs is built. This makes the code available to everyone who uses -your machine. (See the @file{INSTALL} file that is part of the Emacs -distribution.) -@end itemize - -Finally, if you have code that everyone who uses Emacs may want, you -can post it on a computer network or send a copy to the Free Software -Foundation. (When you do this, please license the code and its -documentation under a license that permits other people to run, copy, -study, modify, and redistribute the code and which protects you from -having your work taken from you.) If you send a copy of your code to -the Free Software Foundation, and properly protect yourself and -others, it may be included in the next release of Emacs. In large -part, this is how Emacs has grown over the past years, by donations. - -@node let, if, Permanent Installation, Writing Defuns -@comment node-name, next, previous, up -@section @code{let} -@findex let - -The @code{let} expression is a special form in Lisp that you will need -to use in most function definitions. - -@code{let} is used to attach or bind a symbol to a value in such a way -that the Lisp interpreter will not confuse the variable with a -variable of the same name that is not part of the function. - -To understand why the @code{let} special form is necessary, consider -the situation in which you own a home that you generally refer to as -`the house', as in the sentence, ``The house needs painting.'' If you -are visiting a friend and your host refers to `the house', he is -likely to be referring to @emph{his} house, not yours, that is, to a -different house. - -If your friend is referring to his house and you think he is referring -to your house, you may be in for some confusion. The same thing could -happen in Lisp if a variable that is used inside of one function has -the same name as a variable that is used inside of another function, -and the two are not intended to refer to the same value. The -@code{let} special form prevents this kind of confusion. - -@menu -* Prevent confusion:: -* Parts of let Expression:: -* Sample let Expression:: -* Uninitialized let Variables:: -@end menu - -@node Prevent confusion, Parts of let Expression, let, let -@ifnottex -@unnumberedsubsec @code{let} Prevents Confusion -@end ifnottex - -@cindex @samp{local variable} defined -@cindex @samp{variable, local}, defined -The @code{let} special form prevents confusion. @code{let} creates a -name for a @dfn{local variable} that overshadows any use of the same -name outside the @code{let} expression. This is like understanding -that whenever your host refers to `the house', he means his house, not -yours. (Symbols used in argument lists work the same way. -@xref{defun, , The @code{defun} Special Form}.) - -Local variables created by a @code{let} expression retain their value -@emph{only} within the @code{let} expression itself (and within -expressions called within the @code{let} expression); the local -variables have no effect outside the @code{let} expression. - -Another way to think about @code{let} is that it is like a @code{setq} -that is temporary and local. The values set by @code{let} are -automatically undone when the @code{let} is finished. The setting -only affects expressions that are inside the bounds of the @code{let} -expression. In computer science jargon, we would say ``the binding of -a symbol is visible only in functions called in the @code{let} form; -in Emacs Lisp, scoping is dynamic, not lexical.'' - -@code{let} can create more than one variable at once. Also, -@code{let} gives each variable it creates an initial value, either a -value specified by you, or @code{nil}. (In the jargon, this is called -`binding the variable to the value'.) After @code{let} has created -and bound the variables, it executes the code in the body of the -@code{let}, and returns the value of the last expression in the body, -as the value of the whole @code{let} expression. (`Execute' is a jargon -term that means to evaluate a list; it comes from the use of the word -meaning `to give practical effect to' (@cite{Oxford English -Dictionary}). Since you evaluate an expression to perform an action, -`execute' has evolved as a synonym to `evaluate'.) - -@node Parts of let Expression, Sample let Expression, Prevent confusion, let -@comment node-name, next, previous, up -@subsection The Parts of a @code{let} Expression -@cindex @code{let} expression, parts of -@cindex Parts of @code{let} expression - -@cindex @samp{varlist} defined -A @code{let} expression is a list of three parts. The first part is -the symbol @code{let}. The second part is a list, called a -@dfn{varlist}, each element of which is either a symbol by itself or a -two-element list, the first element of which is a symbol. The third -part of the @code{let} expression is the body of the @code{let}. The -body usually consists of one or more lists. - -@need 800 -A template for a @code{let} expression looks like this: - -@smallexample -(let @var{varlist} @var{body}@dots{}) -@end smallexample - -@noindent -The symbols in the varlist are the variables that are given initial -values by the @code{let} special form. Symbols by themselves are given -the initial value of @code{nil}; and each symbol that is the first -element of a two-element list is bound to the value that is returned -when the Lisp interpreter evaluates the second element. - -Thus, a varlist might look like this: @code{(thread (needles 3))}. In -this case, in a @code{let} expression, Emacs binds the symbol -@code{thread} to an initial value of @code{nil}, and binds the symbol -@code{needles} to an initial value of 3. - -When you write a @code{let} expression, what you do is put the -appropriate expressions in the slots of the @code{let} expression -template. - -If the varlist is composed of two-element lists, as is often the case, -the template for the @code{let} expression looks like this: - -@smallexample -@group -(let ((@var{variable} @var{value}) - (@var{variable} @var{value}) - @dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -@node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let -@comment node-name, next, previous, up -@subsection Sample @code{let} Expression -@cindex Sample @code{let} expression -@cindex @code{let} expression sample - -The following expression creates and gives initial values -to the two variables @code{zebra} and @code{tiger}. The body of the -@code{let} expression is a list which calls the @code{message} function. - -@smallexample -@group -(let ((zebra 'stripes) - (tiger 'fierce)) - (message "One kind of animal has %s and another is %s." - zebra tiger)) -@end group -@end smallexample - -Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}. - -The two variables are @code{zebra} and @code{tiger}. Each variable is -the first element of a two-element list and each value is the second -element of its two-element list. In the varlist, Emacs binds the -variable @code{zebra} to the value @code{stripes}@footnote{According -to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras -become impossibly dangerous as they grow older'' but the claim here is -that they do not become fierce like a tiger. (1997, W. W. Norton and -Co., ISBN 0-393-03894-2, page 171)}, and binds the -variable @code{tiger} to the value @code{fierce}. In this example, -both values are symbols preceded by a quote. The values could just as -well have been another list or a string. The body of the @code{let} -follows after the list holding the variables. In this example, the -body is a list that uses the @code{message} function to print a string -in the echo area. - -@need 1500 -You may evaluate the example in the usual fashion, by placing the -cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do -this, the following will appear in the echo area: - -@smallexample -"One kind of animal has stripes and another is fierce." -@end smallexample - -As we have seen before, the @code{message} function prints its first -argument, except for @samp{%s}. In this example, the value of the variable -@code{zebra} is printed at the location of the first @samp{%s} and the -value of the variable @code{tiger} is printed at the location of the -second @samp{%s}. - -@node Uninitialized let Variables, , Sample let Expression, let -@comment node-name, next, previous, up -@subsection Uninitialized Variables in a @code{let} Statement -@cindex Uninitialized @code{let} variables -@cindex @code{let} variables uninitialized - -If you do not bind the variables in a @code{let} statement to specific -initial values, they will automatically be bound to an initial value of -@code{nil}, as in the following expression: - -@smallexample -@group -(let ((birch 3) - pine - fir - (oak 'some)) - (message - "Here are %d variables with %s, %s, and %s value." - birch pine fir oak)) -@end group -@end smallexample - -@noindent -Here, the varlist is @code{((birch 3) pine fir (oak 'some))}. - -@need 1250 -If you evaluate this expression in the usual way, the following will -appear in your echo area: - -@smallexample -"Here are 3 variables with nil, nil, and some value." -@end smallexample - -@noindent -In this example, Emacs binds the symbol @code{birch} to the number 3, -binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds -the symbol @code{oak} to the value @code{some}. - -Note that in the first part of the @code{let}, the variables @code{pine} -and @code{fir} stand alone as atoms that are not surrounded by -parentheses; this is because they are being bound to @code{nil}, the -empty list. But @code{oak} is bound to @code{some} and so is a part of -the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the -number 3 and so is in a list with that number. (Since a number -evaluates to itself, the number does not need to be quoted. Also, the -number is printed in the message using a @samp{%d} rather than a -@samp{%s}.) The four variables as a group are put into a list to -delimit them from the body of the @code{let}. - -@node if, else, let, Writing Defuns -@comment node-name, next, previous, up -@section The @code{if} Special Form -@findex if -@cindex Conditional with @code{if} - -A third special form, in addition to @code{defun} and @code{let}, is the -conditional @code{if}. This form is used to instruct the computer to -make decisions. You can write function definitions without using -@code{if}, but it is used often enough, and is important enough, to be -included here. It is used, for example, in the code for the -function @code{beginning-of-buffer}. - -The basic idea behind an @code{if}, is that ``@emph{if} a test is true, -@emph{then} an expression is evaluated.'' If the test is not true, the -expression is not evaluated. For example, you might make a decision -such as, ``if it is warm and sunny, then go to the beach!'' - -@menu -* if in more detail:: -* type-of-animal in detail:: An example of an @code{if} expression. -@end menu - -@node if in more detail, type-of-animal in detail, if, if -@ifnottex -@unnumberedsubsec @code{if} in more detail -@end ifnottex - -@cindex @samp{if-part} defined -@cindex @samp{then-part} defined -An @code{if} expression written in Lisp does not use the word `then'; -the test and the action are the second and third elements of the list -whose first element is @code{if}. Nonetheless, the test part of an -@code{if} expression is often called the @dfn{if-part} and the second -argument is often called the @dfn{then-part}. - -Also, when an @code{if} expression is written, the true-or-false-test -is usually written on the same line as the symbol @code{if}, but the -action to carry out if the test is true, the ``then-part'', is written -on the second and subsequent lines. This makes the @code{if} -expression easier to read. - -@smallexample -@group -(if @var{true-or-false-test} - @var{action-to-carry-out-if-test-is-true}) -@end group -@end smallexample - -@noindent -The true-or-false-test will be an expression that -is evaluated by the Lisp interpreter. - -Here is an example that you can evaluate in the usual manner. The test -is whether the number 5 is greater than the number 4. Since it is, the -message @samp{5 is greater than 4!} will be printed. - -@smallexample -@group -(if (> 5 4) ; @r{if-part} - (message "5 is greater than 4!")) ; @r{then-part} -@end group -@end smallexample - -@noindent -(The function @code{>} tests whether its first argument is greater than -its second argument and returns true if it is.) -@findex > (greater than) - -Of course, in actual use, the test in an @code{if} expression will not -be fixed for all time as it is by the expression @code{(> 5 4)}. -Instead, at least one of the variables used in the test will be bound to -a value that is not known ahead of time. (If the value were known ahead -of time, we would not need to run the test!) - -For example, the value may be bound to an argument of a function -definition. In the following function definition, the character of the -animal is a value that is passed to the function. If the value bound to -@code{characteristic} is @code{fierce}, then the message, @samp{It's a -tiger!} will be printed; otherwise, @code{nil} will be returned. - -@smallexample -@group -(defun type-of-animal (characteristic) - "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger." - (if (equal characteristic 'fierce) - (message "It's a tiger!"))) -@end group -@end smallexample - -@need 1500 -@noindent -If you are reading this inside of GNU Emacs, you can evaluate the -function definition in the usual way to install it in Emacs, and then you -can evaluate the following two expressions to see the results: - -@smallexample -@group -(type-of-animal 'fierce) - -(type-of-animal 'zebra) - -@end group -@end smallexample - -@c Following sentences rewritten to prevent overfull hbox. -@noindent -When you evaluate @code{(type-of-animal 'fierce)}, you will see the -following message printed in the echo area: @code{"It's a tiger!"}; and -when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil} -printed in the echo area. - -@node type-of-animal in detail, , if in more detail, if -@comment node-name, next, previous, up -@subsection The @code{type-of-animal} Function in Detail - -Let's look at the @code{type-of-animal} function in detail. - -The function definition for @code{type-of-animal} was written by filling -the slots of two templates, one for a function definition as a whole, and -a second for an @code{if} expression. - -@need 1250 -The template for every function that is not interactive is: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - @var{body}@dots{}) -@end group -@end smallexample - -@need 800 -The parts of the function that match this template look like this: - -@smallexample -@group -(defun type-of-animal (characteristic) - "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger." - @var{body: the} @code{if} @var{expression}) -@end group -@end smallexample - -The name of function is @code{type-of-animal}; it is passed the value -of one argument. The argument list is followed by a multi-line -documentation string. The documentation string is included in the -example because it is a good habit to write documentation string for -every function definition. The body of the function definition -consists of the @code{if} expression. - -@need 800 -The template for an @code{if} expression looks like this: - -@smallexample -@group -(if @var{true-or-false-test} - @var{action-to-carry-out-if-the-test-returns-true}) -@end group -@end smallexample - -@need 1250 -In the @code{type-of-animal} function, the code for the @code{if} -looks like this: - -@smallexample -@group -(if (equal characteristic 'fierce) - (message "It's a tiger!"))) -@end group -@end smallexample - -@need 800 -Here, the true-or-false-test is the expression: - -@smallexample -(equal characteristic 'fierce) -@end smallexample - -@noindent -In Lisp, @code{equal} is a function that determines whether its first -argument is equal to its second argument. The second argument is the -quoted symbol @code{'fierce} and the first argument is the value of the -symbol @code{characteristic}---in other words, the argument passed to -this function. - -In the first exercise of @code{type-of-animal}, the argument -@code{fierce} is passed to @code{type-of-animal}. Since @code{fierce} -is equal to @code{fierce}, the expression, @code{(equal characteristic -'fierce)}, returns a value of true. When this happens, the @code{if} -evaluates the second argument or then-part of the @code{if}: -@code{(message "It's tiger!")}. - -On the other hand, in the second exercise of @code{type-of-animal}, the -argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra} -is not equal to @code{fierce}, so the then-part is not evaluated and -@code{nil} is returned by the @code{if} expression. - -@node else, Truth & Falsehood, if, Writing Defuns -@comment node-name, next, previous, up -@section If--then--else Expressions -@cindex Else - -An @code{if} expression may have an optional third argument, called -the @dfn{else-part}, for the case when the true-or-false-test returns -false. When this happens, the second argument or then-part of the -overall @code{if} expression is @emph{not} evaluated, but the third or -else-part @emph{is} evaluated. You might think of this as the cloudy -day alternative for the decision ``if it is warm and sunny, then go to -the beach, else read a book!''. - -The word ``else'' is not written in the Lisp code; the else-part of an -@code{if} expression comes after the then-part. In the written Lisp, the -else-part is usually written to start on a line of its own and is -indented less than the then-part: - -@smallexample -@group -(if @var{true-or-false-test} - @var{action-to-carry-out-if-the-test-returns-true} - @var{action-to-carry-out-if-the-test-returns-false}) -@end group -@end smallexample - -For example, the following @code{if} expression prints the message @samp{4 -is not greater than 5!} when you evaluate it in the usual way: - -@smallexample -@group -(if (> 4 5) ; @r{if-part} - (message "4 falsely greater than 5!") ; @r{then-part} - (message "4 is not greater than 5!")) ; @r{else-part} -@end group -@end smallexample - -@noindent -Note that the different levels of indentation make it easy to -distinguish the then-part from the else-part. (GNU Emacs has several -commands that automatically indent @code{if} expressions correctly. -@xref{Typing Lists, , GNU Emacs Helps You Type Lists}.) - -We can extend the @code{type-of-animal} function to include an -else-part by simply incorporating an additional part to the @code{if} -expression. - -@need 1500 -You can see the consequences of doing this if you evaluate the following -version of the @code{type-of-animal} function definition to install it -and then evaluate the two subsequent expressions to pass different -arguments to the function. - -@smallexample -@group -(defun type-of-animal (characteristic) ; @r{Second version.} - "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger; -else say it's not fierce." - (if (equal characteristic 'fierce) - (message "It's a tiger!") - (message "It's not fierce!"))) -@end group -@end smallexample -@sp 1 - -@smallexample -@group -(type-of-animal 'fierce) - -(type-of-animal 'zebra) - -@end group -@end smallexample - -@c Following sentence rewritten to prevent overfull hbox. -@noindent -When you evaluate @code{(type-of-animal 'fierce)}, you will see the -following message printed in the echo area: @code{"It's a tiger!"}; but -when you evaluate @code{(type-of-animal 'zebra)}, you will see -@code{"It's not fierce!"}. - -(Of course, if the @var{characteristic} were @code{ferocious}, the -message @code{"It's not fierce!"} would be printed; and it would be -misleading! When you write code, you need to take into account the -possibility that some such argument will be tested by the @code{if} -and write your program accordingly.) - -@node Truth & Falsehood, save-excursion, else, Writing Defuns -@comment node-name, next, previous, up -@section Truth and Falsehood in Emacs Lisp -@cindex Truth and falsehood in Emacs Lisp -@cindex Falsehood and truth in Emacs Lisp -@findex nil - -There is an important aspect to the truth test in an @code{if} -expression. So far, we have spoken of `true' and `false' as values of -predicates as if they were new kinds of Emacs Lisp objects. In fact, -`false' is just our old friend @code{nil}. Anything else---anything -at all---is `true'. - -The expression that tests for truth is interpreted as @dfn{true} -if the result of evaluating it is a value that is not @code{nil}. In -other words, the result of the test is considered true if the value -returned is a number such as 47, a string such as @code{"hello"}, or a -symbol (other than @code{nil}) such as @code{flowers}, or a list (so -long as it is not empty), or even a buffer! - -@menu -* nil explained:: @code{nil} has two meanings. -@end menu - -@node nil explained, , Truth & Falsehood, Truth & Falsehood -@ifnottex -@unnumberedsubsec An explanation of @code{nil} -@end ifnottex - -Before illustrating a test for truth, we need an explanation of @code{nil}. - -In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the -empty list. Second, it means false and is the value returned when a -true-or-false-test tests false. @code{nil} can be written as an empty -list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is -concerned, @code{()} and @code{nil} are the same. Humans, however, tend -to use @code{nil} for false and @code{()} for the empty list. - -In Emacs Lisp, any value that is not @code{nil}---is not the empty -list---is considered true. This means that if an evaluation returns -something that is not an empty list, an @code{if} expression will test -true. For example, if a number is put in the slot for the test, it -will be evaluated and will return itself, since that is what numbers -do when evaluated. In this conditional, the @code{if} expression will -test true. The expression tests false only when @code{nil}, an empty -list, is returned by evaluating the expression. - -You can see this by evaluating the two expressions in the following examples. - -In the first example, the number 4 is evaluated as the test in the -@code{if} expression and returns itself; consequently, the then-part -of the expression is evaluated and returned: @samp{true} appears in -the echo area. In the second example, the @code{nil} indicates false; -consequently, the else-part of the expression is evaluated and -returned: @samp{false} appears in the echo area. - -@smallexample -@group -(if 4 - 'true - 'false) -@end group - -@group -(if nil - 'true - 'false) -@end group -@end smallexample - -@need 1250 -Incidentally, if some other useful value is not available for a test that -returns true, then the Lisp interpreter will return the symbol @code{t} -for true. For example, the expression @code{(> 5 4)} returns @code{t} -when evaluated, as you can see by evaluating it in the usual way: - -@smallexample -(> 5 4) -@end smallexample - -@need 1250 -@noindent -On the other hand, this function returns @code{nil} if the test is false. - -@smallexample -(> 4 5) -@end smallexample - -@node save-excursion, Review, Truth & Falsehood, Writing Defuns -@comment node-name, next, previous, up -@section @code{save-excursion} -@findex save-excursion -@cindex Region, what it is -@cindex Preserving point, mark, and buffer -@cindex Point, mark, buffer preservation -@findex point -@findex mark - -The @code{save-excursion} function is the fourth and final special form -that we will discuss in this chapter. - -In Emacs Lisp programs used for editing, the @code{save-excursion} -function is very common. It saves the location of point and mark, -executes the body of the function, and then restores point and mark to -their previous positions if their locations were changed. Its primary -purpose is to keep the user from being surprised and disturbed by -unexpected movement of point or mark. - -@menu -* Point and mark:: A review of various locations. -* Template for save-excursion:: -@end menu - -@node Point and mark, Template for save-excursion, save-excursion, save-excursion -@ifnottex -@unnumberedsubsec Point and Mark -@end ifnottex - -Before discussing @code{save-excursion}, however, it may be useful -first to review what point and mark are in GNU Emacs. @dfn{Point} is -the current location of the cursor. Wherever the cursor -is, that is point. More precisely, on terminals where the cursor -appears to be on top of a character, point is immediately before the -character. In Emacs Lisp, point is an integer. The first character in -a buffer is number one, the second is number two, and so on. The -function @code{point} returns the current position of the cursor as a -number. Each buffer has its own value for point. - -The @dfn{mark} is another position in the buffer; its value can be set -with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If -a mark has been set, you can use the command @kbd{C-x C-x} -(@code{exchange-point-and-mark}) to cause the cursor to jump to the mark -and set the mark to be the previous position of point. In addition, if -you set another mark, the position of the previous mark is saved in the -mark ring. Many mark positions can be saved this way. You can jump the -cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more -times. - -The part of the buffer between point and mark is called @dfn{the -region}. Numerous commands work on the region, including -@code{center-region}, @code{count-lines-region}, @code{kill-region}, and -@code{print-region}. - -The @code{save-excursion} special form saves the locations of point and -mark and restores those positions after the code within the body of the -special form is evaluated by the Lisp interpreter. Thus, if point were -in the beginning of a piece of text and some code moved point to the end -of the buffer, the @code{save-excursion} would put point back to where -it was before, after the expressions in the body of the function were -evaluated. - -In Emacs, a function frequently moves point as part of its internal -workings even though a user would not expect this. For example, -@code{count-lines-region} moves point. To prevent the user from being -bothered by jumps that are both unexpected and (from the user's point of -view) unnecessary, @code{save-excursion} is often used to keep point and -mark in the location expected by the user. The use of -@code{save-excursion} is good housekeeping. - -To make sure the house stays clean, @code{save-excursion} restores the -values of point and mark even if something goes wrong in the code inside -of it (or, to be more precise and to use the proper jargon, ``in case of -abnormal exit''). This feature is very helpful. - -In addition to recording the values of point and mark, -@code{save-excursion} keeps track of the current buffer, and restores -it, too. This means you can write code that will change the buffer and -have @code{save-excursion} switch you back to the original buffer. -This is how @code{save-excursion} is used in @code{append-to-buffer}. -(@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) - -@node Template for save-excursion, , Point and mark, save-excursion -@comment node-name, next, previous, up -@subsection Template for a @code{save-excursion} Expression - -@need 800 -The template for code using @code{save-excursion} is simple: - -@smallexample -@group -(save-excursion - @var{body}@dots{}) -@end group -@end smallexample - -@noindent -The body of the function is one or more expressions that will be -evaluated in sequence by the Lisp interpreter. If there is more than -one expression in the body, the value of the last one will be returned -as the value of the @code{save-excursion} function. The other -expressions in the body are evaluated only for their side effects; and -@code{save-excursion} itself is used only for its side effect (which -is restoring the positions of point and mark). - -@need 1250 -In more detail, the template for a @code{save-excursion} expression -looks like this: - -@smallexample -@group -(save-excursion - @var{first-expression-in-body} - @var{second-expression-in-body} - @var{third-expression-in-body} - @dots{} - @var{last-expression-in-body}) -@end group -@end smallexample - -@noindent -An expression, of course, may be a symbol on its own or a list. - -In Emacs Lisp code, a @code{save-excursion} expression often occurs -within the body of a @code{let} expression. It looks like this: - -@smallexample -@group -(let @var{varlist} - (save-excursion - @var{body}@dots{})) -@end group -@end smallexample - -@node Review, defun Exercises, save-excursion, Writing Defuns -@comment node-name, next, previous, up -@section Review - -In the last few chapters we have introduced a fair number of functions -and special forms. Here they are described in brief, along with a few -similar functions that have not been mentioned yet. - -@table @code -@item eval-last-sexp -Evaluate the last symbolic expression before the current location of -point. The value is printed in the echo area unless the function is -invoked with an argument; in that case, the output is printed in the -current buffer. This command is normally bound to @kbd{C-x C-e}. - -@item defun -Define function. This special form has up to five parts: the name, -a template for the arguments that will be passed to the function, -documentation, an optional interactive declaration, and the body of the -definition. - -@need 1250 -For example, in an early version of Emacs, the function definition was -as follows. (It is slightly more complex now that it seeks the first -non-whitespace character rather than the first visible character.) - -@smallexample -@group -(defun back-to-indentation () - "Move point to first visible character on line." - (interactive) - (beginning-of-line 1) - (skip-chars-forward " \t")) -@end group -@end smallexample - -@ignore -In GNU Emacs 22, - -(defun backward-to-indentation (&optional arg) - "Move backward ARG lines and position at first nonblank character." - (interactive "p") - (forward-line (- (or arg 1))) - (skip-chars-forward " \t")) - -(defun back-to-indentation () - "Move point to the first non-whitespace character on this line." - (interactive) - (beginning-of-line 1) - (skip-syntax-forward " " (line-end-position)) - ;; Move back over chars that have whitespace syntax but have the p flag. - (backward-prefix-chars)) -@end ignore - -@item interactive -Declare to the interpreter that the function can be used -interactively. This special form may be followed by a string with one -or more parts that pass the information to the arguments of the -function, in sequence. These parts may also tell the interpreter to -prompt for information. Parts of the string are separated by -newlines, @samp{\n}. - -@need 1000 -Common code characters are: - -@table @code -@item b -The name of an existing buffer. - -@item f -The name of an existing file. - -@item p -The numeric prefix argument. (Note that this `p' is lower case.) - -@item r -Point and the mark, as two numeric arguments, smallest first. This -is the only code letter that specifies two successive arguments -rather than one. -@end table - -@xref{Interactive Codes, , Code Characters for @samp{interactive}, -elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of -code characters. - -@item let -Declare that a list of variables is for use within the body of the -@code{let} and give them an initial value, either @code{nil} or a -specified value; then evaluate the rest of the expressions in the body -of the @code{let} and return the value of the last one. Inside the -body of the @code{let}, the Lisp interpreter does not see the values of -the variables of the same names that are bound outside of the -@code{let}. - -@need 1250 -For example, - -@smallexample -@group -(let ((foo (buffer-name)) - (bar (buffer-size))) - (message - "This buffer is %s and has %d characters." - foo bar)) -@end group -@end smallexample - -@item save-excursion -Record the values of point and mark and the current buffer before -evaluating the body of this special form. Restore the values of point -and mark and buffer afterward. - -@need 1250 -For example, - -@smallexample -@group -(message "We are %d characters into this buffer." - (- (point) - (save-excursion - (goto-char (point-min)) (point)))) -@end group -@end smallexample - -@item if -Evaluate the first argument to the function; if it is true, evaluate -the second argument; else evaluate the third argument, if there is one. - -The @code{if} special form is called a @dfn{conditional}. There are -other conditionals in Emacs Lisp, but @code{if} is perhaps the most -commonly used. - -@need 1250 -For example, - -@smallexample -@group -(if (= 22 emacs-major-version) - (message "This is version 22 Emacs") - (message "This is not version 22 Emacs")) -@end group -@end smallexample - -@need 1250 -@item < -@itemx > -@itemx <= -@itemx >= -The @code{<} function tests whether its first argument is smaller than -its second argument. A corresponding function, @code{>}, tests whether -the first argument is greater than the second. Likewise, @code{<=} -tests whether the first argument is less than or equal to the second and -@code{>=} tests whether the first argument is greater than or equal to -the second. In all cases, both arguments must be numbers or markers -(markers indicate positions in buffers). - -@need 800 -@item = -The @code{=} function tests whether two arguments, both numbers or -markers, are equal. - -@need 1250 -@item equal -@itemx eq -Test whether two objects are the same. @code{equal} uses one meaning -of the word `same' and @code{eq} uses another: @code{equal} returns -true if the two objects have a similar structure and contents, such as -two copies of the same book. On the other hand, @code{eq}, returns -true if both arguments are actually the same object. -@findex equal -@findex eq - -@need 1250 -@item string< -@itemx string-lessp -@itemx string= -@itemx string-equal -The @code{string-lessp} function tests whether its first argument is -smaller than the second argument. A shorter, alternative name for the -same function (a @code{defalias}) is @code{string<}. - -The arguments to @code{string-lessp} must be strings or symbols; the -ordering is lexicographic, so case is significant. The print names of -symbols are used instead of the symbols themselves. - -@cindex @samp{empty string} defined -An empty string, @samp{""}, a string with no characters in it, is -smaller than any string of characters. - -@code{string-equal} provides the corresponding test for equality. Its -shorter, alternative name is @code{string=}. There are no string test -functions that correspond to @var{>}, @code{>=}, or @code{<=}. - -@item message -Print a message in the echo area. The first argument is a string that -can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of -arguments that follow the string. The argument used by @samp{%s} must -be a string or a symbol; the argument used by @samp{%d} must be a -number. The argument used by @samp{%c} must be an @sc{ascii} code -number; it will be printed as the character with that @sc{ascii} code. -(Various other %-sequences have not been mentioned.) - -@item setq -@itemx set -The @code{setq} function sets the value of its first argument to the -value of the second argument. The first argument is automatically -quoted by @code{setq}. It does the same for succeeding pairs of -arguments. Another function, @code{set}, takes only two arguments and -evaluates both of them before setting the value returned by its first -argument to the value returned by its second argument. - -@item buffer-name -Without an argument, return the name of the buffer, as a string. - -@itemx buffer-file-name -Without an argument, return the name of the file the buffer is -visiting. - -@item current-buffer -Return the buffer in which Emacs is active; it may not be -the buffer that is visible on the screen. - -@item other-buffer -Return the most recently selected buffer (other than the buffer passed -to @code{other-buffer} as an argument and other than the current -buffer). - -@item switch-to-buffer -Select a buffer for Emacs to be active in and display it in the current -window so users can look at it. Usually bound to @kbd{C-x b}. - -@item set-buffer -Switch Emacs' attention to a buffer on which programs will run. Don't -alter what the window is showing. - -@item buffer-size -Return the number of characters in the current buffer. - -@item point -Return the value of the current position of the cursor, as an -integer counting the number of characters from the beginning of the -buffer. - -@item point-min -Return the minimum permissible value of point in -the current buffer. This is 1, unless narrowing is in effect. - -@item point-max -Return the value of the maximum permissible value of point in the -current buffer. This is the end of the buffer, unless narrowing is in -effect. -@end table - -@need 1500 -@node defun Exercises, , Review, Writing Defuns -@section Exercises - -@itemize @bullet -@item -Write a non-interactive function that doubles the value of its -argument, a number. Make that function interactive. - -@item -Write a function that tests whether the current value of -@code{fill-column} is greater than the argument passed to the function, -and if so, prints an appropriate message. -@end itemize - -@node Buffer Walk Through, More Complex, Writing Defuns, Top -@comment node-name, next, previous, up -@chapter A Few Buffer--Related Functions - -In this chapter we study in detail several of the functions used in GNU -Emacs. This is called a ``walk-through''. These functions are used as -examples of Lisp code, but are not imaginary examples; with the -exception of the first, simplified function definition, these functions -show the actual code used in GNU Emacs. You can learn a great deal from -these definitions. The functions described here are all related to -buffers. Later, we will study other functions. - -@menu -* Finding More:: How to find more information. -* simplified-beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. -* append-to-buffer:: Uses @code{save-excursion} and - @code{insert-buffer-substring}. -* Buffer Related Review:: Review. -* Buffer Exercises:: -@end menu - -@node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through -@section Finding More Information - -@findex describe-function, @r{introduced} -@cindex Find function documentation -In this walk-through, I will describe each new function as we come to -it, sometimes in detail and sometimes briefly. If you are interested, -you can get the full documentation of any Emacs Lisp function at any -time by typing @kbd{C-h f} and then the name of the function (and then -@key{RET}). Similarly, you can get the full documentation for a -variable by typing @kbd{C-h v} and then the name of the variable (and -then @key{RET}). - -@cindex Find source of function -@c In version 22, tells location both of C and of Emacs Lisp -Also, @code{describe-function} will tell you the location of the -function definition. - -Put point into the name of the file that contains the function and -press the @key{RET} key. In this case, @key{RET} means -@code{push-button} rather than `return' or `enter'. Emacs will take -you directly to the function definition. - -@ignore -Not In version 22 - -If you move point over the file name and press -the @key{RET} key, which in this case means @code{help-follow} rather -than `return' or `enter', Emacs will take you directly to the function -definition. -@end ignore - -More generally, if you want to see a function in its original source -file, you can use the @code{find-tags} function to jump to it. -@code{find-tags} works with a wide variety of languages, not just -Lisp, and C, and it works with non-programming text as well. For -example, @code{find-tags} will jump to the various nodes in the -Texinfo source file of this document. -The @code{find-tags} function depends on `tags tables' that record -the locations of the functions, variables, and other items to which -@code{find-tags} jumps. - -To use the @code{find-tags} command, type @kbd{M-.} (i.e., press the -period key while holding down the @key{META} key, or else type the -@key{ESC} key and then type the period key), and then, at the prompt, -type in the name of the function whose source code you want to see, -such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will -switch buffers and display the source code for the function on your -screen. To switch back to your current buffer, type @kbd{C-x b -@key{RET}}. (On some keyboards, the @key{META} key is labelled -@key{ALT}.) - -@c !!! 22.1.1 tags table location in this paragraph -@cindex TAGS table, specifying -@findex find-tags -Depending on how the initial default values of your copy of Emacs are -set, you may also need to specify the location of your `tags table', -which is a file called @file{TAGS}. For example, if you are -interested in Emacs sources, the tags table you will most likely want, -if it has already been created for you, will be in a subdirectory of -the @file{/usr/local/share/emacs/} directory; thus you would use the -@code{M-x visit-tags-table} command and specify a pathname such as -@file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table -has not already been created, you will have to create it yourself. It -will in a file such as @file{/usr/local/src/emacs/src/TAGS}. - -@need 1250 -To create a @file{TAGS} file in a specific directory, switch to that -directory in Emacs using @kbd{M-x cd} command, or list the directory -with @kbd{C-x d} (@code{dired}). Then run the compile command, with -@w{@code{etags *.el}} as the command to execute: - -@smallexample -M-x compile RET etags *.el RET -@end smallexample - -For more information, see @ref{etags, , Create Your Own @file{TAGS} File}. - -After you become more familiar with Emacs Lisp, you will find that you will -frequently use @code{find-tags} to navigate your way around source code; -and you will create your own @file{TAGS} tables. - -@cindex Library, as term for `file' -Incidentally, the files that contain Lisp code are conventionally -called @dfn{libraries}. The metaphor is derived from that of a -specialized library, such as a law library or an engineering library, -rather than a general library. Each library, or file, contains -functions that relate to a particular topic or activity, such as -@file{abbrev.el} for handling abbreviations and other typing -shortcuts, and @file{help.el} for on-line help. (Sometimes several -libraries provide code for a single activity, as the various -@file{rmail@dots{}} files provide code for reading electronic mail.) -In @cite{The GNU Emacs Manual}, you will see sentences such as ``The -@kbd{C-h p} command lets you search the standard Emacs Lisp libraries -by topic keywords.'' - -@node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through -@comment node-name, next, previous, up -@section A Simplified @code{beginning-of-buffer} Definition -@findex simplified-beginning-of-buffer - -The @code{beginning-of-buffer} command is a good function to start with -since you are likely to be familiar with it and it is easy to -understand. Used as an interactive command, @code{beginning-of-buffer} -moves the cursor to the beginning of the buffer, leaving the mark at the -previous position. It is generally bound to @kbd{M-<}. - -In this section, we will discuss a shortened version of the function -that shows how it is most frequently used. This shortened function -works as written, but it does not contain the code for a complex option. -In another section, we will describe the entire function. -(@xref{beginning-of-buffer, , Complete Definition of -@code{beginning-of-buffer}}.) - -Before looking at the code, let's consider what the function -definition has to contain: it must include an expression that makes -the function interactive so it can be called by typing @kbd{M-x -beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it -must include code to leave a mark at the original position in the -buffer; and it must include code to move the cursor to the beginning -of the buffer. - -@need 1250 -Here is the complete text of the shortened version of the function: - -@smallexample -@group -(defun simplified-beginning-of-buffer () - "Move point to the beginning of the buffer; -leave mark at previous position." - (interactive) - (push-mark) - (goto-char (point-min))) -@end group -@end smallexample - -Like all function definitions, this definition has five parts following -the special form @code{defun}: - -@enumerate -@item -The name: in this example, @code{simplified-beginning-of-buffer}. - -@item -A list of the arguments: in this example, an empty list, @code{()}, - -@item -The documentation string. - -@item -The interactive expression. - -@item -The body. -@end enumerate - -@noindent -In this function definition, the argument list is empty; this means that -this function does not require any arguments. (When we look at the -definition for the complete function, we will see that it may be passed -an optional argument.) - -The interactive expression tells Emacs that the function is intended to -be used interactively. In this example, @code{interactive} does not have -an argument because @code{simplified-beginning-of-buffer} does not -require one. - -@need 800 -The body of the function consists of the two lines: - -@smallexample -@group -(push-mark) -(goto-char (point-min)) -@end group -@end smallexample - -The first of these lines is the expression, @code{(push-mark)}. When -this expression is evaluated by the Lisp interpreter, it sets a mark at -the current position of the cursor, wherever that may be. The position -of this mark is saved in the mark ring. - -The next line is @code{(goto-char (point-min))}. This expression -jumps the cursor to the minimum point in the buffer, that is, to the -beginning of the buffer (or to the beginning of the accessible portion -of the buffer if it is narrowed. @xref{Narrowing & Widening, , -Narrowing and Widening}.) - -The @code{push-mark} command sets a mark at the place where the cursor -was located before it was moved to the beginning of the buffer by the -@code{(goto-char (point-min))} expression. Consequently, you can, if -you wish, go back to where you were originally by typing @kbd{C-x C-x}. - -That is all there is to the function definition! - -@findex describe-function -When you are reading code such as this and come upon an unfamiliar -function, such as @code{goto-char}, you can find out what it does by -using the @code{describe-function} command. To use this command, type -@kbd{C-h f} and then type in the name of the function and press -@key{RET}. The @code{describe-function} command will print the -function's documentation string in a @file{*Help*} window. For -example, the documentation for @code{goto-char} is: - -@smallexample -@group -Set point to POSITION, a number or marker. -Beginning of buffer is position (point-min), end is (point-max). -@end group -@end smallexample - -@noindent -The function's one argument is the desired position. - -@noindent -(The prompt for @code{describe-function} will offer you the symbol -under or preceding the cursor, so you can save typing by positioning -the cursor right over or after the function and then typing @kbd{C-h f -@key{RET}}.) - -The @code{end-of-buffer} function definition is written in the same way as -the @code{beginning-of-buffer} definition except that the body of the -function contains the expression @code{(goto-char (point-max))} in place -of @code{(goto-char (point-min))}. - -@node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through -@comment node-name, next, previous, up -@section The Definition of @code{mark-whole-buffer} -@findex mark-whole-buffer - -The @code{mark-whole-buffer} function is no harder to understand than the -@code{simplified-beginning-of-buffer} function. In this case, however, -we will look at the complete function, not a shortened version. - -The @code{mark-whole-buffer} function is not as commonly used as the -@code{beginning-of-buffer} function, but is useful nonetheless: it -marks a whole buffer as a region by putting point at the beginning and -a mark at the end of the buffer. It is generally bound to @kbd{C-x -h}. - -@menu -* mark-whole-buffer overview:: -* Body of mark-whole-buffer:: Only three lines of code. -@end menu - -@node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer -@ifnottex -@unnumberedsubsec An overview of @code{mark-whole-buffer} -@end ifnottex - -@need 1250 -In GNU Emacs 22, the code for the complete function looks like this: - -@smallexample -@group -(defun mark-whole-buffer () - "Put point at beginning and mark at end of buffer. -You probably should not use this function in Lisp programs; -it is usually a mistake for a Lisp function to use any subroutine -that uses or sets the mark." - (interactive) - (push-mark (point)) - (push-mark (point-max) nil t) - (goto-char (point-min))) -@end group -@end smallexample - -@need 1250 -Like all other functions, the @code{mark-whole-buffer} function fits -into the template for a function definition. The template looks like -this: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (@var{interactive-expression}@dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -Here is how the function works: the name of the function is -@code{mark-whole-buffer}; it is followed by an empty argument list, -@samp{()}, which means that the function does not require arguments. -The documentation comes next. - -The next line is an @code{(interactive)} expression that tells Emacs -that the function will be used interactively. These details are similar -to the @code{simplified-beginning-of-buffer} function described in the -previous section. - -@need 1250 -@node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer -@comment node-name, next, previous, up -@subsection Body of @code{mark-whole-buffer} - -The body of the @code{mark-whole-buffer} function consists of three -lines of code: - -@c GNU Emacs 22 -@smallexample -@group -(push-mark (point)) -(push-mark (point-max) nil t) -(goto-char (point-min)) -@end group -@end smallexample - -The first of these lines is the expression, @code{(push-mark (point))}. - -This line does exactly the same job as the first line of the body of -the @code{simplified-beginning-of-buffer} function, which is written -@code{(push-mark)}. In both cases, the Lisp interpreter sets a mark -at the current position of the cursor. - -I don't know why the expression in @code{mark-whole-buffer} is written -@code{(push-mark (point))} and the expression in -@code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps -whoever wrote the code did not know that the arguments for -@code{push-mark} are optional and that if @code{push-mark} is not -passed an argument, the function automatically sets mark at the -location of point by default. Or perhaps the expression was written -so as to parallel the structure of the next line. In any case, the -line causes Emacs to determine the position of point and set a mark -there. - -In earlier versions of GNU Emacs, the next line of -@code{mark-whole-buffer} was @code{(push-mark (point-max))}. This -expression sets a mark at the point in the buffer that has the highest -number. This will be the end of the buffer (or, if the buffer is -narrowed, the end of the accessible portion of the buffer. -@xref{Narrowing & Widening, , Narrowing and Widening}, for more about -narrowing.) After this mark has been set, the previous mark, the one -set at point, is no longer set, but Emacs remembers its position, just -as all other recent marks are always remembered. This means that you -can, if you wish, go back to that position by typing @kbd{C-u -C-@key{SPC}} twice. - -@need 1250 -In GNU Emacs 22, the @code{(point-max)} is slightly more complicated. -The line reads - -@smallexample -(push-mark (point-max) nil t) -@end smallexample - -@noindent -The expression works nearly the same as before. It sets a mark at the -highest numbered place in the buffer that it can. However, in this -version, @code{push-mark} has two additional arguments. The second -argument to @code{push-mark} is @code{nil}. This tells the function -it @emph{should} display a message that says `Mark set' when it pushes -the mark. The third argument is @code{t}. This tells -@code{push-mark} to activate the mark when Transient Mark mode is -turned on. Transient Mark mode highlights the currently active -region. It is often turned off. - -Finally, the last line of the function is @code{(goto-char -(point-min)))}. This is written exactly the same way as it is written -in @code{beginning-of-buffer}. The expression moves the cursor to -the minimum point in the buffer, that is, to the beginning of the buffer -(or to the beginning of the accessible portion of the buffer). As a -result of this, point is placed at the beginning of the buffer and mark -is set at the end of the buffer. The whole buffer is, therefore, the -region. - -@node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through -@comment node-name, next, previous, up -@section The Definition of @code{append-to-buffer} -@findex append-to-buffer - -The @code{append-to-buffer} command is more complex than the -@code{mark-whole-buffer} command. What it does is copy the region -(that is, the part of the buffer between point and mark) from the -current buffer to a specified buffer. - -@menu -* append-to-buffer overview:: -* append interactive:: A two part interactive expression. -* append-to-buffer body:: Incorporates a @code{let} expression. -* append save-excursion:: How the @code{save-excursion} works. -@end menu - -@node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer -@ifnottex -@unnumberedsubsec An Overview of @code{append-to-buffer} -@end ifnottex - -@findex insert-buffer-substring -The @code{append-to-buffer} command uses the -@code{insert-buffer-substring} function to copy the region. -@code{insert-buffer-substring} is described by its name: it takes a -string of characters from part of a buffer, a ``substring'', and -inserts them into another buffer. - -Most of @code{append-to-buffer} is -concerned with setting up the conditions for -@code{insert-buffer-substring} to work: the code must specify both the -buffer to which the text will go, the window it comes from and goes -to, and the region that will be copied. - -@need 1250 -Here is the complete text of the function: - -@smallexample -@group -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. -@end group - -@group -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer - (current-buffer) t)) - (region-beginning) (region-end))) -@end group -@group - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end group -@end smallexample - -The function can be understood by looking at it as a series of -filled-in templates. - -The outermost template is for the function definition. In this -function, it looks like this (with several slots filled in): - -@smallexample -@group -(defun append-to-buffer (buffer start end) - "@var{documentation}@dots{}" - (interactive @dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -The first line of the function includes its name and three arguments. -The arguments are the @code{buffer} to which the text will be copied, and -the @code{start} and @code{end} of the region in the current buffer that -will be copied. - -The next part of the function is the documentation, which is clear and -complete. As is conventional, the three arguments are written in -upper case so you will notice them easily. Even better, they are -described in the same order as in the argument list. - -Note that the documentation distinguishes between a buffer and its -name. (The function can handle either.) - -@node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer -@comment node-name, next, previous, up -@subsection The @code{append-to-buffer} Interactive Expression - -Since the @code{append-to-buffer} function will be used interactively, -the function must have an @code{interactive} expression. (For a -review of @code{interactive}, see @ref{Interactive, , Making a -Function Interactive}.) The expression reads as follows: - -@smallexample -@group -(interactive - (list (read-buffer - "Append to buffer: " - (other-buffer (current-buffer) t)) - (region-beginning) - (region-end))) -@end group -@end smallexample - -@noindent -This expression is not one with letters standing for parts, as -described earlier. Instead, it starts a list with these parts: - -The first part of the list is an expression to read the name of a -buffer and return it as a string. That is @code{read-buffer}. The -function requires a prompt as its first argument, @samp{"Append to -buffer: "}. Its second argument tells the command what value to -provide if you don't specify anything. - -In this case that second argument is an expression containing the -function @code{other-buffer}, an exception, and a @samp{t}, standing -for true. - -The first argument to @code{other-buffer}, the exception, is yet -another function, @code{current-buffer}. That is not going to be -returned. The second argument is the symbol for true, @code{t}. that -tells @code{other-buffer} that it may show visible buffers (except in -this case, it will not show the current buffer, which makes sense). - -@need 1250 -The expression looks like this: - -@smallexample -(other-buffer (current-buffer) t) -@end smallexample - -The second and third arguments to the @code{list} expression are -@code{(region-beginning)} and @code{(region-end)}. These two -functions specify the beginning and end of the text to be appended. - -@need 1250 -Originally, the command used the letters @samp{B} and @samp{r}. -The whole @code{interactive} expression looked like this: - -@smallexample -(interactive "BAppend to buffer:@: \nr") -@end smallexample - -@noindent -But when that was done, the default value of the buffer switched to -was invisible. That was not wanted. - -(The prompt was separated from the second argument with a newline, -@samp{\n}. It was followed by an @samp{r} that told Emacs to bind the -two arguments that follow the symbol @code{buffer} in the function's -argument list (that is, @code{start} and @code{end}) to the values of -point and mark. That argument worked fine.) - -@node append-to-buffer body, append save-excursion, append interactive, append-to-buffer -@comment node-name, next, previous, up -@subsection The Body of @code{append-to-buffer} - -@ignore -in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el - -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. - -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) - (region-beginning) (region-end))) - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - -The body of the @code{append-to-buffer} function begins with @code{let}. - -As we have seen before (@pxref{let, , @code{let}}), the purpose of a -@code{let} expression is to create and give initial values to one or -more variables that will only be used within the body of the -@code{let}. This means that such a variable will not be confused with -any variable of the same name outside the @code{let} expression. - -We can see how the @code{let} expression fits into the function as a -whole by showing a template for @code{append-to-buffer} with the -@code{let} expression in outline: - -@smallexample -@group -(defun append-to-buffer (buffer start end) - "@var{documentation}@dots{}" - (interactive @dots{}) - (let ((@var{variable} @var{value})) - @var{body}@dots{}) -@end group -@end smallexample - -The @code{let} expression has three elements: - -@enumerate -@item -The symbol @code{let}; - -@item -A varlist containing, in this case, a single two-element list, -@code{(@var{variable} @var{value})}; - -@item -The body of the @code{let} expression. -@end enumerate - -@need 800 -In the @code{append-to-buffer} function, the varlist looks like this: - -@smallexample -(oldbuf (current-buffer)) -@end smallexample - -@noindent -In this part of the @code{let} expression, the one variable, -@code{oldbuf}, is bound to the value returned by the -@code{(current-buffer)} expression. The variable, @code{oldbuf}, is -used to keep track of the buffer in which you are working and from -which you will copy. - -The element or elements of a varlist are surrounded by a set of -parentheses so the Lisp interpreter can distinguish the varlist from -the body of the @code{let}. As a consequence, the two-element list -within the varlist is surrounded by a circumscribing set of parentheses. -The line looks like this: - -@smallexample -@group -(let ((oldbuf (current-buffer))) - @dots{} ) -@end group -@end smallexample - -@noindent -The two parentheses before @code{oldbuf} might surprise you if you did -not realize that the first parenthesis before @code{oldbuf} marks the -boundary of the varlist and the second parenthesis marks the beginning -of the two-element list, @code{(oldbuf (current-buffer))}. - -@node append save-excursion, , append-to-buffer body, append-to-buffer -@comment node-name, next, previous, up -@subsection @code{save-excursion} in @code{append-to-buffer} - -The body of the @code{let} expression in @code{append-to-buffer} -consists of a @code{save-excursion} expression. - -The @code{save-excursion} function saves the locations of point and -mark, and restores them to those positions after the expressions in the -body of the @code{save-excursion} complete execution. In addition, -@code{save-excursion} keeps track of the original buffer, and -restores it. This is how @code{save-excursion} is used in -@code{append-to-buffer}. - -@need 1500 -@cindex Indentation for formatting -@cindex Formatting convention -Incidentally, it is worth noting here that a Lisp function is normally -formatted so that everything that is enclosed in a multi-line spread is -indented more to the right than the first symbol. In this function -definition, the @code{let} is indented more than the @code{defun}, and -the @code{save-excursion} is indented more than the @code{let}, like -this: - -@smallexample -@group -(defun @dots{} - @dots{} - @dots{} - (let@dots{} - (save-excursion - @dots{} -@end group -@end smallexample - -@need 1500 -@noindent -This formatting convention makes it easy to see that the lines in -the body of the @code{save-excursion} are enclosed by the parentheses -associated with @code{save-excursion}, just as the -@code{save-excursion} itself is enclosed by the parentheses associated -with the @code{let}: - -@smallexample -@group -(let ((oldbuf (current-buffer))) - (save-excursion - @dots{} - (set-buffer @dots{}) - (insert-buffer-substring oldbuf start end) - @dots{})) -@end group -@end smallexample - -@need 1200 -The use of the @code{save-excursion} function can be viewed as a process -of filling in the slots of a template: - -@smallexample -@group -(save-excursion - @var{first-expression-in-body} - @var{second-expression-in-body} - @dots{} - @var{last-expression-in-body}) -@end group -@end smallexample - -@need 1200 -@noindent -In this function, the body of the @code{save-excursion} contains only -one expression, the @code{let*} expression. You know about a -@code{let} function. The @code{let*} function is different. It has a -@samp{*} in its name. It enables Emacs to set each variable in its -varlist in sequence, one after another. - -Its critical feature is that variables later in the varlist can make -use of the values to which Emacs set variables earlier in the varlist. -@xref{fwd-para let, , The @code{let*} expression}. - -We will skip functions like @code{let*} and focus on two: the -@code{set-buffer} function and the @code{insert-buffer-substring} -function. - -@need 1250 -In the old days, the @code{set-buffer} expression was simply - -@smallexample -(set-buffer (get-buffer-create buffer)) -@end smallexample - -@need 1250 -@noindent -but now it is - -@smallexample -(set-buffer append-to) -@end smallexample - -@noindent -@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier -on in the @code{let*} expression. That extra binding would not be -necessary except for that @code{append-to} is used later in the -varlist as an argument to @code{get-buffer-window-list}. - -@ignore -in GNU Emacs 22 - - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - -The @code{append-to-buffer} function definition inserts text from the -buffer in which you are currently to a named buffer. It happens that -@code{insert-buffer-substring} copies text from another buffer to the -current buffer, just the reverse---that is why the -@code{append-to-buffer} definition starts out with a @code{let} that -binds the local symbol @code{oldbuf} to the value returned by -@code{current-buffer}. - -@need 1250 -The @code{insert-buffer-substring} expression looks like this: - -@smallexample -(insert-buffer-substring oldbuf start end) -@end smallexample - -@noindent -The @code{insert-buffer-substring} function copies a string -@emph{from} the buffer specified as its first argument and inserts the -string into the present buffer. In this case, the argument to -@code{insert-buffer-substring} is the value of the variable created -and bound by the @code{let}, namely the value of @code{oldbuf}, which -was the current buffer when you gave the @code{append-to-buffer} -command. - -After @code{insert-buffer-substring} has done its work, -@code{save-excursion} will restore the action to the original buffer -and @code{append-to-buffer} will have done its job. - -@need 800 -Written in skeletal form, the workings of the body look like this: - -@smallexample -@group -(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) - (save-excursion ; @r{Keep track of buffer.} - @var{change-buffer} - @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}) - - @var{change-back-to-original-buffer-when-finished} -@var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished} -@end group -@end smallexample - -In summary, @code{append-to-buffer} works as follows: it saves the -value of the current buffer in the variable called @code{oldbuf}. It -gets the new buffer (creating one if need be) and switches Emacs' -attention to it. Using the value of @code{oldbuf}, it inserts the -region of text from the old buffer into the new buffer; and then using -@code{save-excursion}, it brings you back to your original buffer. - -In looking at @code{append-to-buffer}, you have explored a fairly -complex function. It shows how to use @code{let} and -@code{save-excursion}, and how to change to and come back from another -buffer. Many function definitions use @code{let}, -@code{save-excursion}, and @code{set-buffer} this way. - -@node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through -@comment node-name, next, previous, up -@section Review - -Here is a brief summary of the various functions discussed in this chapter. - -@table @code -@item describe-function -@itemx describe-variable -Print the documentation for a function or variable. -Conventionally bound to @kbd{C-h f} and @kbd{C-h v}. - -@item find-tag -Find the file containing the source for a function or variable and -switch buffers to it, positioning point at the beginning of the item. -Conventionally bound to @kbd{M-.} (that's a period following the -@key{META} key). - -@item save-excursion -Save the location of point and mark and restore their values after the -arguments to @code{save-excursion} have been evaluated. Also, remember -the current buffer and return to it. - -@item push-mark -Set mark at a location and record the value of the previous mark on the -mark ring. The mark is a location in the buffer that will keep its -relative position even if text is added to or removed from the buffer. - -@item goto-char -Set point to the location specified by the value of the argument, which -can be a number, a marker, or an expression that returns the number of -a position, such as @code{(point-min)}. - -@item insert-buffer-substring -Copy a region of text from a buffer that is passed to the function as -an argument and insert the region into the current buffer. - -@item mark-whole-buffer -Mark the whole buffer as a region. Normally bound to @kbd{C-x h}. - -@item set-buffer -Switch the attention of Emacs to another buffer, but do not change the -window being displayed. Used when the program rather than a human is -to work on a different buffer. - -@item get-buffer-create -@itemx get-buffer -Find a named buffer or create one if a buffer of that name does not -exist. The @code{get-buffer} function returns @code{nil} if the named -buffer does not exist. -@end table - -@need 1500 -@node Buffer Exercises, , Buffer Related Review, Buffer Walk Through -@section Exercises - -@itemize @bullet -@item -Write your own @code{simplified-end-of-buffer} function definition; -then test it to see whether it works. - -@item -Use @code{if} and @code{get-buffer} to write a function that prints a -message telling you whether a buffer exists. - -@item -Using @code{find-tag}, find the source for the @code{copy-to-buffer} -function. -@end itemize - -@node More Complex, Narrowing & Widening, Buffer Walk Through, Top -@comment node-name, next, previous, up -@chapter A Few More Complex Functions - -In this chapter, we build on what we have learned in previous chapters -by looking at more complex functions. The @code{copy-to-buffer} -function illustrates use of two @code{save-excursion} expressions in -one definition, while the @code{insert-buffer} function illustrates -use of an asterisk in an @code{interactive} expression, use of -@code{or}, and the important distinction between a name and the object -to which the name refers. - -@menu -* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. -* insert-buffer:: Read-only, and with @code{or}. -* beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* Second Buffer Related Review:: -* optional Exercise:: -@end menu - -@node copy-to-buffer, insert-buffer, More Complex, More Complex -@comment node-name, next, previous, up -@section The Definition of @code{copy-to-buffer} -@findex copy-to-buffer - -After understanding how @code{append-to-buffer} works, it is easy to -understand @code{copy-to-buffer}. This function copies text into a -buffer, but instead of adding to the second buffer, it replaces all the -previous text in the second buffer. - -@need 800 -The body of @code{copy-to-buffer} looks like this, - -@smallexample -@group -@dots{} -(interactive "BCopy to buffer: \nr") -(let ((oldbuf (current-buffer))) - (with-current-buffer (get-buffer-create buffer) - (barf-if-buffer-read-only) - (erase-buffer) - (save-excursion - (insert-buffer-substring oldbuf start end))))) -@end group -@end smallexample - -The @code{copy-to-buffer} function has a simpler @code{interactive} -expression than @code{append-to-buffer}. - -@need 800 -The definition then says - -@smallexample -(with-current-buffer (get-buffer-create buffer) @dots{} -@end smallexample - -First, look at the earliest inner expression; that is evaluated first. -That expression starts with @code{get-buffer-create buffer}. The -function tells the computer to use the buffer with the name specified -as the one to which you are copying, or if such a buffer does not -exist, to create it. Then, the @code{with-current-buffer} function -evaluates its body with that buffer temporarily current. - -(This demonstrates another way to shift the computer's attention but -not the user's. The @code{append-to-buffer} function showed how to do -the same with @code{save-excursion} and @code{set-buffer}. -@code{with-current-buffer} is a newer, and arguably easier, -mechanism.) - -The @code{barf-if-buffer-read-only} function sends you an error -message saying the buffer is read-only if you cannot modify it. - -The next line has the @code{erase-buffer} function as its sole -contents. That function erases the buffer. - -Finally, the last two lines contain the @code{save-excursion} -expression with @code{insert-buffer-substring} as its body. -The @code{insert-buffer-substring} expression copies the text from -the buffer you are in (and you have not seen the computer shift its -attention, so you don't know that that buffer is now called -@code{oldbuf}). - -Incidentally, this is what is meant by `replacement'. To replace text, -Emacs erases the previous text and then inserts new text. - -@need 1250 -In outline, the body of @code{copy-to-buffer} looks like this: - -@smallexample -@group -(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) - (@var{with-the-buffer-you-are-copying-to} - (@var{but-do-not-erase-or-copy-to-a-read-only-buffer}) - (erase-buffer) - (save-excursion - @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}))) -@end group -@end smallexample - -@node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex -@comment node-name, next, previous, up -@section The Definition of @code{insert-buffer} -@findex insert-buffer - -@code{insert-buffer} is yet another buffer-related function. This -command copies another buffer @emph{into} the current buffer. It is the -reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they -copy a region of text @emph{from} the current buffer to another buffer. - -Here is a discussion based on the original code. The code was -simplified in 2003 and is harder to understand. - -(@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see -a discussion of the new body.) - -In addition, this code illustrates the use of @code{interactive} with a -buffer that might be @dfn{read-only} and the important distinction -between the name of an object and the object actually referred to. - -@menu -* insert-buffer code:: -* insert-buffer interactive:: When you can read, but not write. -* insert-buffer body:: The body has an @code{or} and a @code{let}. -* if & or:: Using an @code{if} instead of an @code{or}. -* Insert or:: How the @code{or} expression works. -* Insert let:: Two @code{save-excursion} expressions. -* New insert-buffer:: -@end menu - -@node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer -@ifnottex -@unnumberedsubsec The Code for @code{insert-buffer} -@end ifnottex - -@need 800 -Here is the earlier code: - -@smallexample -@group -(defun insert-buffer (buffer) - "Insert after point the contents of BUFFER. -Puts mark after the inserted text. -BUFFER may be a buffer or a buffer name." - (interactive "*bInsert buffer:@: ") -@end group -@group - (or (bufferp buffer) - (setq buffer (get-buffer buffer))) - (let (start end newmark) - (save-excursion - (save-excursion - (set-buffer buffer) - (setq start (point-min) end (point-max))) -@end group -@group - (insert-buffer-substring buffer start end) - (setq newmark (point))) - (push-mark newmark))) -@end group -@end smallexample - -@need 1200 -As with other function definitions, you can use a template to see an -outline of the function: - -@smallexample -@group -(defun insert-buffer (buffer) - "@var{documentation}@dots{}" - (interactive "*bInsert buffer:@: ") - @var{body}@dots{}) -@end group -@end smallexample - -@node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer -@comment node-name, next, previous, up -@subsection The Interactive Expression in @code{insert-buffer} -@findex interactive, @r{example use of} - -In @code{insert-buffer}, the argument to the @code{interactive} -declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert -buffer:@: }. - -@menu -* Read-only buffer:: When a buffer cannot be modified. -* b for interactive:: An existing buffer or else its name. -@end menu - -@node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive -@comment node-name, next, previous, up -@unnumberedsubsubsec A Read-only Buffer -@cindex Read-only buffer -@cindex Asterisk for read-only buffer -@findex * @r{for read-only buffer} - -The asterisk is for the situation when the current buffer is a -read-only buffer---a buffer that cannot be modified. If -@code{insert-buffer} is called when the current buffer is read-only, a -message to this effect is printed in the echo area and the terminal -may beep or blink at you; you will not be permitted to insert anything -into current buffer. The asterisk does not need to be followed by a -newline to separate it from the next argument. - -@node b for interactive, , Read-only buffer, insert-buffer interactive -@comment node-name, next, previous, up -@unnumberedsubsubsec @samp{b} in an Interactive Expression - -The next argument in the interactive expression starts with a lower -case @samp{b}. (This is different from the code for -@code{append-to-buffer}, which uses an upper-case @samp{B}. -@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) -The lower-case @samp{b} tells the Lisp interpreter that the argument -for @code{insert-buffer} should be an existing buffer or else its -name. (The upper-case @samp{B} option provides for the possibility -that the buffer does not exist.) Emacs will prompt you for the name -of the buffer, offering you a default buffer, with name completion -enabled. If the buffer does not exist, you receive a message that -says ``No match''; your terminal may beep at you as well. - -The new and simplified code generates a list for @code{interactive}. -It uses the @code{barf-if-buffer-read-only} and @code{read-buffer} -functions with which we are already familiar and the @code{progn} -special form with which we are not. (It will be described later.) - -@node insert-buffer body, if & or, insert-buffer interactive, insert-buffer -@comment node-name, next, previous, up -@subsection The Body of the @code{insert-buffer} Function - -The body of the @code{insert-buffer} function has two major parts: an -@code{or} expression and a @code{let} expression. The purpose of the -@code{or} expression is to ensure that the argument @code{buffer} is -bound to a buffer and not just the name of a buffer. The body of the -@code{let} expression contains the code which copies the other buffer -into the current buffer. - -@need 1250 -In outline, the two expressions fit into the @code{insert-buffer} -function like this: - -@smallexample -@group -(defun insert-buffer (buffer) - "@var{documentation}@dots{}" - (interactive "*bInsert buffer:@: ") - (or @dots{} - @dots{} -@end group -@group - (let (@var{varlist}) - @var{body-of-}@code{let}@dots{} ) -@end group -@end smallexample - -To understand how the @code{or} expression ensures that the argument -@code{buffer} is bound to a buffer and not to the name of a buffer, it -is first necessary to understand the @code{or} function. - -Before doing this, let me rewrite this part of the function using -@code{if} so that you can see what is done in a manner that will be familiar. - -@node if & or, Insert or, insert-buffer body, insert-buffer -@comment node-name, next, previous, up -@subsection @code{insert-buffer} With an @code{if} Instead of an @code{or} - -The job to be done is to make sure the value of @code{buffer} is a -buffer itself and not the name of a buffer. If the value is the name, -then the buffer itself must be got. - -You can imagine yourself at a conference where an usher is wandering -around holding a list with your name on it and looking for you: the -usher is ``bound'' to your name, not to you; but when the usher finds -you and takes your arm, the usher becomes ``bound'' to you. - -@need 800 -In Lisp, you might describe this situation like this: - -@smallexample -@group -(if (not (holding-on-to-guest)) - (find-and-take-arm-of-guest)) -@end group -@end smallexample - -We want to do the same thing with a buffer---if we do not have the -buffer itself, we want to get it. - -@need 1200 -Using a predicate called @code{bufferp} that tells us whether we have a -buffer (rather than its name), we can write the code like this: - -@smallexample -@group -(if (not (bufferp buffer)) ; @r{if-part} - (setq buffer (get-buffer buffer))) ; @r{then-part} -@end group -@end smallexample - -@noindent -Here, the true-or-false-test of the @code{if} expression is -@w{@code{(not (bufferp buffer))}}; and the then-part is the expression -@w{@code{(setq buffer (get-buffer buffer))}}. - -In the test, the function @code{bufferp} returns true if its argument is -a buffer---but false if its argument is the name of the buffer. (The -last character of the function name @code{bufferp} is the character -@samp{p}; as we saw earlier, such use of @samp{p} is a convention that -indicates that the function is a predicate, which is a term that means -that the function will determine whether some property is true or false. -@xref{Wrong Type of Argument, , Using the Wrong Type Object as an -Argument}.) - -@need 1200 -The function @code{not} precedes the expression @code{(bufferp buffer)}, -so the true-or-false-test looks like this: - -@smallexample -(not (bufferp buffer)) -@end smallexample - -@noindent -@code{not} is a function that returns true if its argument is false -and false if its argument is true. So if @code{(bufferp buffer)} -returns true, the @code{not} expression returns false and vice-verse: -what is ``not true'' is false and what is ``not false'' is true. - -Using this test, the @code{if} expression works as follows: when the -value of the variable @code{buffer} is actually a buffer rather than -its name, the true-or-false-test returns false and the @code{if} -expression does not evaluate the then-part. This is fine, since we do -not need to do anything to the variable @code{buffer} if it really is -a buffer. - -On the other hand, when the value of @code{buffer} is not a buffer -itself, but the name of a buffer, the true-or-false-test returns true -and the then-part of the expression is evaluated. In this case, the -then-part is @code{(setq buffer (get-buffer buffer))}. This -expression uses the @code{get-buffer} function to return an actual -buffer itself, given its name. The @code{setq} then sets the variable -@code{buffer} to the value of the buffer itself, replacing its previous -value (which was the name of the buffer). - -@node Insert or, Insert let, if & or, insert-buffer -@comment node-name, next, previous, up -@subsection The @code{or} in the Body - -The purpose of the @code{or} expression in the @code{insert-buffer} -function is to ensure that the argument @code{buffer} is bound to a -buffer and not just to the name of a buffer. The previous section shows -how the job could have been done using an @code{if} expression. -However, the @code{insert-buffer} function actually uses @code{or}. -To understand this, it is necessary to understand how @code{or} works. - -@findex or -An @code{or} function can have any number of arguments. It evaluates -each argument in turn and returns the value of the first of its -arguments that is not @code{nil}. Also, and this is a crucial feature -of @code{or}, it does not evaluate any subsequent arguments after -returning the first non-@code{nil} value. - -@need 800 -The @code{or} expression looks like this: - -@smallexample -@group -(or (bufferp buffer) - (setq buffer (get-buffer buffer))) -@end group -@end smallexample - -@noindent -The first argument to @code{or} is the expression @code{(bufferp buffer)}. -This expression returns true (a non-@code{nil} value) if the buffer is -actually a buffer, and not just the name of a buffer. In the @code{or} -expression, if this is the case, the @code{or} expression returns this -true value and does not evaluate the next expression---and this is fine -with us, since we do not want to do anything to the value of -@code{buffer} if it really is a buffer. - -On the other hand, if the value of @code{(bufferp buffer)} is @code{nil}, -which it will be if the value of @code{buffer} is the name of a buffer, -the Lisp interpreter evaluates the next element of the @code{or} -expression. This is the expression @code{(setq buffer (get-buffer -buffer))}. This expression returns a non-@code{nil} value, which -is the value to which it sets the variable @code{buffer}---and this -value is a buffer itself, not the name of a buffer. - -The result of all this is that the symbol @code{buffer} is always -bound to a buffer itself rather than to the name of a buffer. All -this is necessary because the @code{set-buffer} function in a -following line only works with a buffer itself, not with the name to a -buffer. - -@need 1250 -Incidentally, using @code{or}, the situation with the usher would be -written like this: - -@smallexample -(or (holding-on-to-guest) (find-and-take-arm-of-guest)) -@end smallexample - -@node Insert let, New insert-buffer, Insert or, insert-buffer -@comment node-name, next, previous, up -@subsection The @code{let} Expression in @code{insert-buffer} - -After ensuring that the variable @code{buffer} refers to a buffer itself -and not just to the name of a buffer, the @code{insert-buffer function} -continues with a @code{let} expression. This specifies three local -variables, @code{start}, @code{end}, and @code{newmark} and binds them -to the initial value @code{nil}. These variables are used inside the -remainder of the @code{let} and temporarily hide any other occurrence of -variables of the same name in Emacs until the end of the @code{let}. - -@need 1200 -The body of the @code{let} contains two @code{save-excursion} -expressions. First, we will look at the inner @code{save-excursion} -expression in detail. The expression looks like this: - -@smallexample -@group -(save-excursion - (set-buffer buffer) - (setq start (point-min) end (point-max))) -@end group -@end smallexample - -@noindent -The expression @code{(set-buffer buffer)} changes Emacs' attention -from the current buffer to the one from which the text will copied. -In that buffer, the variables @code{start} and @code{end} are set to -the beginning and end of the buffer, using the commands -@code{point-min} and @code{point-max}. Note that we have here an -illustration of how @code{setq} is able to set two variables in the -same expression. The first argument of @code{setq} is set to the -value of its second, and its third argument is set to the value of its -fourth. - -After the body of the inner @code{save-excursion} is evaluated, the -@code{save-excursion} restores the original buffer, but @code{start} and -@code{end} remain set to the values of the beginning and end of the -buffer from which the text will be copied. - -@need 1250 -The outer @code{save-excursion} expression looks like this: - -@smallexample -@group -(save-excursion - (@var{inner-}@code{save-excursion}@var{-expression} - (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end}) - (insert-buffer-substring buffer start end) - (setq newmark (point))) -@end group -@end smallexample - -@noindent -The @code{insert-buffer-substring} function copies the text -@emph{into} the current buffer @emph{from} the region indicated by -@code{start} and @code{end} in @code{buffer}. Since the whole of the -second buffer lies between @code{start} and @code{end}, the whole of -the second buffer is copied into the buffer you are editing. Next, -the value of point, which will be at the end of the inserted text, is -recorded in the variable @code{newmark}. - -After the body of the outer @code{save-excursion} is evaluated, point -and mark are relocated to their original places. - -However, it is convenient to locate a mark at the end of the newly -inserted text and locate point at its beginning. The @code{newmark} -variable records the end of the inserted text. In the last line of -the @code{let} expression, the @code{(push-mark newmark)} expression -function sets a mark to this location. (The previous location of the -mark is still accessible; it is recorded on the mark ring and you can -go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is -located at the beginning of the inserted text, which is where it was -before you called the insert function, the position of which was saved -by the first @code{save-excursion}. - -@need 1250 -The whole @code{let} expression looks like this: - -@smallexample -@group -(let (start end newmark) - (save-excursion - (save-excursion - (set-buffer buffer) - (setq start (point-min) end (point-max))) - (insert-buffer-substring buffer start end) - (setq newmark (point))) - (push-mark newmark)) -@end group -@end smallexample - -Like the @code{append-to-buffer} function, the @code{insert-buffer} -function uses @code{let}, @code{save-excursion}, and -@code{set-buffer}. In addition, the function illustrates one way to -use @code{or}. All these functions are building blocks that we will -find and use again and again. - -@node New insert-buffer, , Insert let, insert-buffer -@comment node-name, next, previous, up -@subsection New Body for @code{insert-buffer} -@findex insert-buffer, new version body -@findex new version body for insert-buffer - -The body in the GNU Emacs 22 version is more confusing than the original. - -@need 1250 -It consists of two expressions, - -@smallexample -@group - (push-mark - (save-excursion - (insert-buffer-substring (get-buffer buffer)) - (point))) - - nil -@end group -@end smallexample - -@noindent -except, and this is what confuses novices, very important work is done -inside the @code{push-mark} expression. - -The @code{get-buffer} function returns a buffer with the name -provided. You will note that the function is @emph{not} called -@code{get-buffer-create}; it does not create a buffer if one does not -already exist. The buffer returned by @code{get-buffer}, an existing -buffer, is passed to @code{insert-buffer-substring}, which inserts the -whole of the buffer (since you did not specify anything else). - -The location into which the buffer is inserted is recorded by -@code{push-mark}. Then the function returns @code{nil}, the value of -its last command. Put another way, the @code{insert-buffer} function -exists only to produce a side effect, inserting another buffer, not to -return any value. - -@node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex -@comment node-name, next, previous, up -@section Complete Definition of @code{beginning-of-buffer} -@findex beginning-of-buffer - -The basic structure of the @code{beginning-of-buffer} function has -already been discussed. (@xref{simplified-beginning-of-buffer, , A -Simplified @code{beginning-of-buffer} Definition}.) -This section describes the complex part of the definition. - -As previously described, when invoked without an argument, -@code{beginning-of-buffer} moves the cursor to the beginning of the -buffer (in truth, the beginning of the accessible portion of the -buffer), leaving the mark at the previous position. However, when the -command is invoked with a number between one and ten, the function -considers that number to be a fraction of the length of the buffer, -measured in tenths, and Emacs moves the cursor that fraction of the -way from the beginning of the buffer. Thus, you can either call this -function with the key command @kbd{M-<}, which will move the cursor to -the beginning of the buffer, or with a key command such as @kbd{C-u 7 -M-<} which will move the cursor to a point 70% of the way through the -buffer. If a number bigger than ten is used for the argument, it -moves to the end of the buffer. - -The @code{beginning-of-buffer} function can be called with or without an -argument. The use of the argument is optional. - -@menu -* Optional Arguments:: -* beginning-of-buffer opt arg:: Example with optional argument. -* beginning-of-buffer complete:: -@end menu - -@node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer -@subsection Optional Arguments - -Unless told otherwise, Lisp expects that a function with an argument in -its function definition will be called with a value for that argument. -If that does not happen, you get an error and a message that says -@samp{Wrong number of arguments}. - -@cindex Optional arguments -@cindex Keyword -@findex optional -However, optional arguments are a feature of Lisp: a particular -@dfn{keyword} is used to tell the Lisp interpreter that an argument is -optional. The keyword is @code{&optional}. (The @samp{&} in front of -@samp{optional} is part of the keyword.) In a function definition, if -an argument follows the keyword @code{&optional}, no value need be -passed to that argument when the function is called. - -@need 1200 -The first line of the function definition of @code{beginning-of-buffer} -therefore looks like this: - -@smallexample -(defun beginning-of-buffer (&optional arg) -@end smallexample - -@need 1250 -In outline, the whole function looks like this: - -@smallexample -@group -(defun beginning-of-buffer (&optional arg) - "@var{documentation}@dots{}" - (interactive "P") - (or (@var{is-the-argument-a-cons-cell} arg) - (and @var{are-both-transient-mark-mode-and-mark-active-true}) - (push-mark)) - (let (@var{determine-size-and-set-it}) - (goto-char - (@var{if-there-is-an-argument} - @var{figure-out-where-to-go} - @var{else-go-to} - (point-min)))) - @var{do-nicety} -@end group -@end smallexample - -The function is similar to the @code{simplified-beginning-of-buffer} -function except that the @code{interactive} expression has @code{"P"} -as an argument and the @code{goto-char} function is followed by an -if-then-else expression that figures out where to put the cursor if -there is an argument that is not a cons cell. - -(Since I do not explain a cons cell for many more chapters, please -consider ignoring the function @code{consp}. @xref{List -Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type, -, Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference -Manual}.) - -The @code{"P"} in the @code{interactive} expression tells Emacs to -pass a prefix argument, if there is one, to the function in raw form. -A prefix argument is made by typing the @key{META} key followed by a -number, or by typing @kbd{C-u} and then a number. (If you don't type -a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase -@code{"p"} in the @code{interactive} expression causes the function to -convert a prefix arg to a number.) - -The true-or-false-test of the @code{if} expression looks complex, but -it is not: it checks whether @code{arg} has a value that is not -@code{nil} and whether it is a cons cell. (That is what @code{consp} -does; it checks whether its argument is a cons cell.) If @code{arg} -has a value that is not @code{nil} (and is not a cons cell), which -will be the case if @code{beginning-of-buffer} is called with a -numeric argument, then this true-or-false-test will return true and -the then-part of the @code{if} expression will be evaluated. On the -other hand, if @code{beginning-of-buffer} is not called with an -argument, the value of @code{arg} will be @code{nil} and the else-part -of the @code{if} expression will be evaluated. The else-part is -simply @code{point-min}, and when this is the outcome, the whole -@code{goto-char} expression is @code{(goto-char (point-min))}, which -is how we saw the @code{beginning-of-buffer} function in its -simplified form. - -@node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer -@subsection @code{beginning-of-buffer} with an Argument - -When @code{beginning-of-buffer} is called with an argument, an -expression is evaluated which calculates what value to pass to -@code{goto-char}. This expression is rather complicated at first sight. -It includes an inner @code{if} expression and much arithmetic. It looks -like this: - -@smallexample -@group -(if (> (buffer-size) 10000) - ;; @r{Avoid overflow for large buffer sizes!} - (* (prefix-numeric-value arg) - (/ size 10)) - (/ - (+ 10 - (* - size (prefix-numeric-value arg))) 10))) -@end group -@end smallexample - -@menu -* Disentangle beginning-of-buffer:: -* Large buffer case:: -* Small buffer case:: -@end menu - -@node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg -@ifnottex -@unnumberedsubsubsec Disentangle @code{beginning-of-buffer} -@end ifnottex - -Like other complex-looking expressions, the conditional expression -within @code{beginning-of-buffer} can be disentangled by looking at it -as parts of a template, in this case, the template for an if-then-else -expression. In skeletal form, the expression looks like this: - -@smallexample -@group -(if (@var{buffer-is-large} - @var{divide-buffer-size-by-10-and-multiply-by-arg} - @var{else-use-alternate-calculation} -@end group -@end smallexample - -The true-or-false-test of this inner @code{if} expression checks the -size of the buffer. The reason for this is that the old version 18 -Emacs used numbers that are no bigger than eight million or so and in -the computation that followed, the programmer feared that Emacs might -try to use over-large numbers if the buffer were large. The term -`overflow', mentioned in the comment, means numbers that are over -large. More recent versions of Emacs use larger numbers, but this -code has not been touched, if only because people now look at buffers -that are far, far larger than ever before. - -There are two cases: if the buffer is large and if it is not. - -@node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg -@comment node-name, next, previous, up -@unnumberedsubsubsec What happens in a large buffer - -In @code{beginning-of-buffer}, the inner @code{if} expression tests -whether the size of the buffer is greater than 10,000 characters. To do -this, it uses the @code{>} function and the computation of @code{size} -that comes from the let expression. - -In the old days, the function @code{buffer-size} was used. Not only -was that function called several times, it gave the size of the whole -buffer, not the accessible part. The computation makes much more -sense when it handles just the accessible part. (@xref{Narrowing & -Widening, , Narrowing and Widening}, for more information on focusing -attention to an `accessible' part.) - -@need 800 -The line looks like this: - -@smallexample -(if (> size 10000) -@end smallexample - -@need 1200 -@noindent -When the buffer is large, the then-part of the @code{if} expression is -evaluated. It reads like this (after formatting for easy reading): - -@smallexample -@group -(* - (prefix-numeric-value arg) - (/ size 10)) -@end group -@end smallexample - -@noindent -This expression is a multiplication, with two arguments to the function -@code{*}. - -The first argument is @code{(prefix-numeric-value arg)}. When -@code{"P"} is used as the argument for @code{interactive}, the value -passed to the function as its argument is passed a ``raw prefix -argument'', and not a number. (It is a number in a list.) To perform -the arithmetic, a conversion is necessary, and -@code{prefix-numeric-value} does the job. - -@findex / @r{(division)} -@cindex Division -The second argument is @code{(/ size 10)}. This expression divides -the numeric value by ten --- the numeric value of the size of the -accessible portion of the buffer. This produces a number that tells -how many characters make up one tenth of the buffer size. (In Lisp, -@code{/} is used for division, just as @code{*} is used for -multiplication.) - -@need 1200 -In the multiplication expression as a whole, this amount is multiplied -by the value of the prefix argument---the multiplication looks like this: - -@smallexample -@group -(* @var{numeric-value-of-prefix-arg} - @var{number-of-characters-in-one-tenth-of-the-accessible-buffer}) -@end group -@end smallexample - -@noindent -If, for example, the prefix argument is @samp{7}, the one-tenth value -will be multiplied by 7 to give a position 70% of the way through. - -@need 1200 -The result of all this is that if the accessible portion of the buffer -is large, the @code{goto-char} expression reads like this: - -@smallexample -@group -(goto-char (* (prefix-numeric-value arg) - (/ size 10))) -@end group -@end smallexample - -This puts the cursor where we want it. - -@node Small buffer case, , Large buffer case, beginning-of-buffer opt arg -@comment node-name, next, previous, up -@unnumberedsubsubsec What happens in a small buffer - -If the buffer contains fewer than 10,000 characters, a slightly -different computation is performed. You might think this is not -necessary, since the first computation could do the job. However, in -a small buffer, the first method may not put the cursor on exactly the -desired line; the second method does a better job. - -@need 800 -The code looks like this: - -@c Keep this on one line. -@smallexample -(/ (+ 10 (* size (prefix-numeric-value arg))) 10)) -@end smallexample - -@need 1200 -@noindent -This is code in which you figure out what happens by discovering how the -functions are embedded in parentheses. It is easier to read if you -reformat it with each expression indented more deeply than its -enclosing expression: - -@smallexample -@group - (/ - (+ 10 - (* - size - (prefix-numeric-value arg))) - 10)) -@end group -@end smallexample - -@need 1200 -@noindent -Looking at parentheses, we see that the innermost operation is -@code{(prefix-numeric-value arg)}, which converts the raw argument to -a number. In the following expression, this number is multiplied by -the size of the accessible portion of the buffer: - -@smallexample -(* size (prefix-numeric-value arg)) -@end smallexample - -@noindent -This multiplication creates a number that may be larger than the size of -the buffer---seven times larger if the argument is 7, for example. Ten -is then added to this number and finally the large number is divided by -ten to provide a value that is one character larger than the percentage -position in the buffer. - -The number that results from all this is passed to @code{goto-char} and -the cursor is moved to that point. - -@need 1500 -@node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer -@comment node-name, next, previous, up -@subsection The Complete @code{beginning-of-buffer} - -@need 1000 -Here is the complete text of the @code{beginning-of-buffer} function: -@sp 1 - -@c In GNU Emacs 22 -@smallexample -@group -(defun beginning-of-buffer (&optional arg) - "Move point to the beginning of the buffer; -leave mark at previous position. -With \\[universal-argument] prefix, -do not set mark at previous position. -With numeric arg N, -put point N/10 of the way from the beginning. - -If the buffer is narrowed, -this command uses the beginning and size -of the accessible part of the buffer. -@end group - -@group -Don't use this command in Lisp programs! -\(goto-char (point-min)) is faster -and avoids clobbering the mark." - (interactive "P") - (or (consp arg) - (and transient-mark-mode mark-active) - (push-mark)) -@end group -@group - (let ((size (- (point-max) (point-min)))) - (goto-char (if (and arg (not (consp arg))) - (+ (point-min) - (if (> size 10000) - ;; Avoid overflow for large buffer sizes! - (* (prefix-numeric-value arg) - (/ size 10)) - (/ (+ 10 (* size (prefix-numeric-value arg))) 10))) - (point-min)))) - (if arg (forward-line 1))) -@end group -@end smallexample - -@ignore -From before GNU Emacs 22 -@smallexample -@group -(defun beginning-of-buffer (&optional arg) - "Move point to the beginning of the buffer; -leave mark at previous position. -With arg N, put point N/10 of the way -from the true beginning. -@end group -@group -Don't use this in Lisp programs! -\(goto-char (point-min)) is faster -and does not set the mark." - (interactive "P") - (push-mark) -@end group -@group - (goto-char - (if arg - (if (> (buffer-size) 10000) - ;; @r{Avoid overflow for large buffer sizes!} - (* (prefix-numeric-value arg) - (/ (buffer-size) 10)) -@end group -@group - (/ (+ 10 (* (buffer-size) - (prefix-numeric-value arg))) - 10)) - (point-min))) - (if arg (forward-line 1))) -@end group -@end smallexample -@end ignore - -@noindent -Except for two small points, the previous discussion shows how this -function works. The first point deals with a detail in the -documentation string, and the second point concerns the last line of -the function. - -@need 800 -In the documentation string, there is reference to an expression: - -@smallexample -\\[universal-argument] -@end smallexample - -@noindent -A @samp{\\} is used before the first square bracket of this -expression. This @samp{\\} tells the Lisp interpreter to substitute -whatever key is currently bound to the @samp{[@dots{}]}. In the case -of @code{universal-argument}, that is usually @kbd{C-u}, but it might -be different. (@xref{Documentation Tips, , Tips for Documentation -Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more -information.) - -@need 1200 -Finally, the last line of the @code{beginning-of-buffer} command says -to move point to the beginning of the next line if the command is -invoked with an argument: - -@smallexample -(if arg (forward-line 1))) -@end smallexample - -@noindent -This puts the cursor at the beginning of the first line after the -appropriate tenths position in the buffer. This is a flourish that -means that the cursor is always located @emph{at least} the requested -tenths of the way through the buffer, which is a nicety that is, -perhaps, not necessary, but which, if it did not occur, would be sure -to draw complaints. - -On the other hand, it also means that if you specify the command with -a @kbd{C-u}, but without a number, that is to say, if the `raw prefix -argument' is simply a cons cell, then the command puts you at the -beginning of the second line @dots{} I don't know whether this is -intended or whether no one has dealt with the code to avoid this -happening. - -@node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex -@comment node-name, next, previous, up -@section Review - -Here is a brief summary of some of the topics covered in this chapter. - -@table @code -@item or -Evaluate each argument in sequence, and return the value of the first -argument that is not @code{nil}; if none return a value that is not -@code{nil}, return @code{nil}. In brief, return the first true value -of the arguments; return a true value if one @emph{or} any of the -others are true. - -@item and -Evaluate each argument in sequence, and if any are @code{nil}, return -@code{nil}; if none are @code{nil}, return the value of the last -argument. In brief, return a true value only if all the arguments are -true; return a true value if one @emph{and} each of the others is -true. - -@item &optional -A keyword used to indicate that an argument to a function definition -is optional; this means that the function can be evaluated without the -argument, if desired. - -@item prefix-numeric-value -Convert the `raw prefix argument' produced by @code{(interactive -"P")} to a numeric value. - -@item forward-line -Move point forward to the beginning of the next line, or if the argument -is greater than one, forward that many lines. If it can't move as far -forward as it is supposed to, @code{forward-line} goes forward as far as -it can and then returns a count of the number of additional lines it was -supposed to move but couldn't. - -@item erase-buffer -Delete the entire contents of the current buffer. - -@item bufferp -Return @code{t} if its argument is a buffer; otherwise return @code{nil}. -@end table - -@node optional Exercise, , Second Buffer Related Review, More Complex -@section @code{optional} Argument Exercise - -Write an interactive function with an optional argument that tests -whether its argument, a number, is greater than or equal to, or else, -less than the value of @code{fill-column}, and tells you which, in a -message. However, if you do not pass an argument to the function, use -56 as a default value. - -@node Narrowing & Widening, car cdr & cons, More Complex, Top -@comment node-name, next, previous, up -@chapter Narrowing and Widening -@cindex Focusing attention (narrowing) -@cindex Narrowing -@cindex Widening - -Narrowing is a feature of Emacs that makes it possible for you to focus -on a specific part of a buffer, and work without accidentally changing -other parts. Narrowing is normally disabled since it can confuse -novices. - -@menu -* Narrowing advantages:: The advantages of narrowing -* save-restriction:: The @code{save-restriction} special form. -* what-line:: The number of the line that point is on. -* narrow Exercise:: -@end menu - -@node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening -@ifnottex -@unnumberedsec The Advantages of Narrowing -@end ifnottex - -With narrowing, the rest of a buffer is made invisible, as if it weren't -there. This is an advantage if, for example, you want to replace a word -in one part of a buffer but not in another: you narrow to the part you want -and the replacement is carried out only in that section, not in the rest -of the buffer. Searches will only work within a narrowed region, not -outside of one, so if you are fixing a part of a document, you can keep -yourself from accidentally finding parts you do not need to fix by -narrowing just to the region you want. -(The key binding for @code{narrow-to-region} is @kbd{C-x n n}.) - -However, narrowing does make the rest of the buffer invisible, which -can scare people who inadvertently invoke narrowing and think they -have deleted a part of their file. Moreover, the @code{undo} command -(which is usually bound to @kbd{C-x u}) does not turn off narrowing -(nor should it), so people can become quite desperate if they do not -know that they can return the rest of a buffer to visibility with the -@code{widen} command. -(The key binding for @code{widen} is @kbd{C-x n w}.) - -Narrowing is just as useful to the Lisp interpreter as to a human. -Often, an Emacs Lisp function is designed to work on just part of a -buffer; or conversely, an Emacs Lisp function needs to work on all of a -buffer that has been narrowed. The @code{what-line} function, for -example, removes the narrowing from a buffer, if it has any narrowing -and when it has finished its job, restores the narrowing to what it was. -On the other hand, the @code{count-lines} function, which is called by -@code{what-line}, uses narrowing to restrict itself to just that portion -of the buffer in which it is interested and then restores the previous -situation. - -@node save-restriction, what-line, Narrowing advantages, Narrowing & Widening -@comment node-name, next, previous, up -@section The @code{save-restriction} Special Form -@findex save-restriction - -In Emacs Lisp, you can use the @code{save-restriction} special form to -keep track of whatever narrowing is in effect, if any. When the Lisp -interpreter meets with @code{save-restriction}, it executes the code -in the body of the @code{save-restriction} expression, and then undoes -any changes to narrowing that the code caused. If, for example, the -buffer is narrowed and the code that follows @code{save-restriction} -gets rid of the narrowing, @code{save-restriction} returns the buffer -to its narrowed region afterwards. In the @code{what-line} command, -any narrowing the buffer may have is undone by the @code{widen} -command that immediately follows the @code{save-restriction} command. -Any original narrowing is restored just before the completion of the -function. - -@need 1250 -The template for a @code{save-restriction} expression is simple: - -@smallexample -@group -(save-restriction - @var{body}@dots{} ) -@end group -@end smallexample - -@noindent -The body of the @code{save-restriction} is one or more expressions that -will be evaluated in sequence by the Lisp interpreter. - -Finally, a point to note: when you use both @code{save-excursion} and -@code{save-restriction}, one right after the other, you should use -@code{save-excursion} outermost. If you write them in reverse order, -you may fail to record narrowing in the buffer to which Emacs switches -after calling @code{save-excursion}. Thus, when written together, -@code{save-excursion} and @code{save-restriction} should be written -like this: - -@smallexample -@group -(save-excursion - (save-restriction - @var{body}@dots{})) -@end group -@end smallexample - -In other circumstances, when not written together, the -@code{save-excursion} and @code{save-restriction} special forms must -be written in the order appropriate to the function. - -@need 1250 -For example, - -@smallexample -@group - (save-restriction - (widen) - (save-excursion - @var{body}@dots{})) -@end group -@end smallexample - -@ignore -Emacs 22 -/usr/local/src/emacs/lisp/simple.el - -(defun what-line () - "Print the current buffer line number and narrowed line number of point." - (interactive) - (let ((start (point-min)) - (n (line-number-at-pos))) - (if (= start 1) - (message "Line %d" n) - (save-excursion - (save-restriction - (widen) - (message "line %d (narrowed line %d)" - (+ n (line-number-at-pos start) -1) n)))))) - -(defun line-number-at-pos (&optional pos) - "Return (narrowed) buffer line number at position POS. -If POS is nil, use current buffer location. -Counting starts at (point-min), so the value refers -to the contents of the accessible portion of the buffer." - (let ((opoint (or pos (point))) start) - (save-excursion - (goto-char (point-min)) - (setq start (point)) - (goto-char opoint) - (forward-line 0) - (1+ (count-lines start (point)))))) - -(defun count-lines (start end) - "Return number of lines between START and END. -This is usually the number of newlines between them, -but can be one more if START is not equal to END -and the greater of them is not at the start of a line." - (save-excursion - (save-restriction - (narrow-to-region start end) - (goto-char (point-min)) - (if (eq selective-display t) - (save-match-data - (let ((done 0)) - (while (re-search-forward "[\n\C-m]" nil t 40) - (setq done (+ 40 done))) - (while (re-search-forward "[\n\C-m]" nil t 1) - (setq done (+ 1 done))) - (goto-char (point-max)) - (if (and (/= start end) - (not (bolp))) - (1+ done) - done))) - (- (buffer-size) (forward-line (buffer-size))))))) -@end ignore - -@node what-line, narrow Exercise, save-restriction, Narrowing & Widening -@comment node-name, next, previous, up -@section @code{what-line} -@findex what-line -@cindex Widening, example of - -The @code{what-line} command tells you the number of the line in which -the cursor is located. The function illustrates the use of the -@code{save-restriction} and @code{save-excursion} commands. Here is the -original text of the function: - -@smallexample -@group -(defun what-line () - "Print the current line number (in the buffer) of point." - (interactive) - (save-restriction - (widen) - (save-excursion - (beginning-of-line) - (message "Line %d" - (1+ (count-lines 1 (point))))))) -@end group -@end smallexample - -(In recent versions of GNU Emacs, the @code{what-line} function has -been expanded to tell you your line number in a narrowed buffer as -well as your line number in a widened buffer. The recent version is -more complex than the version shown here. If you feel adventurous, -you might want to look at it after figuring out how this version -works. You will probably need to use @kbd{C-h f} -(@code{describe-function}). The newer version uses a conditional to -determine whether the buffer has been narrowed. - -(Also, it uses @code{line-number-at-pos}, which among other simple -expressions, such as @code{(goto-char (point-min))}, moves point to -the beginning of the current line with @code{(forward-line 0)} rather -than @code{beginning-of-line}.) - -The @code{what-line} function as shown here has a documentation line -and is interactive, as you would expect. The next two lines use the -functions @code{save-restriction} and @code{widen}. - -The @code{save-restriction} special form notes whatever narrowing is in -effect, if any, in the current buffer and restores that narrowing after -the code in the body of the @code{save-restriction} has been evaluated. - -The @code{save-restriction} special form is followed by @code{widen}. -This function undoes any narrowing the current buffer may have had -when @code{what-line} was called. (The narrowing that was there is -the narrowing that @code{save-restriction} remembers.) This widening -makes it possible for the line counting commands to count from the -beginning of the buffer. Otherwise, they would have been limited to -counting within the accessible region. Any original narrowing is -restored just before the completion of the function by the -@code{save-restriction} special form. - -The call to @code{widen} is followed by @code{save-excursion}, which -saves the location of the cursor (i.e., of point) and of the mark, and -restores them after the code in the body of the @code{save-excursion} -uses the @code{beginning-of-line} function to move point. - -(Note that the @code{(widen)} expression comes between the -@code{save-restriction} and @code{save-excursion} special forms. When -you write the two @code{save- @dots{}} expressions in sequence, write -@code{save-excursion} outermost.) - -@need 1200 -The last two lines of the @code{what-line} function are functions to -count the number of lines in the buffer and then print the number in the -echo area. - -@smallexample -@group -(message "Line %d" - (1+ (count-lines 1 (point))))))) -@end group -@end smallexample - -The @code{message} function prints a one-line message at the bottom of -the Emacs screen. The first argument is inside of quotation marks and -is printed as a string of characters. However, it may contain a -@samp{%d} expression to print a following argument. @samp{%d} prints -the argument as a decimal, so the message will say something such as -@samp{Line 243}. - -@need 1200 -The number that is printed in place of the @samp{%d} is computed by the -last line of the function: - -@smallexample -(1+ (count-lines 1 (point))) -@end smallexample - -@ignore -GNU Emacs 22 - -(defun count-lines (start end) - "Return number of lines between START and END. -This is usually the number of newlines between them, -but can be one more if START is not equal to END -and the greater of them is not at the start of a line." - (save-excursion - (save-restriction - (narrow-to-region start end) - (goto-char (point-min)) - (if (eq selective-display t) - (save-match-data - (let ((done 0)) - (while (re-search-forward "[\n\C-m]" nil t 40) - (setq done (+ 40 done))) - (while (re-search-forward "[\n\C-m]" nil t 1) - (setq done (+ 1 done))) - (goto-char (point-max)) - (if (and (/= start end) - (not (bolp))) - (1+ done) - done))) - (- (buffer-size) (forward-line (buffer-size))))))) -@end ignore - -@noindent -What this does is count the lines from the first position of the -buffer, indicated by the @code{1}, up to @code{(point)}, and then add -one to that number. (The @code{1+} function adds one to its -argument.) We add one to it because line 2 has only one line before -it, and @code{count-lines} counts only the lines @emph{before} the -current line. - -After @code{count-lines} has done its job, and the message has been -printed in the echo area, the @code{save-excursion} restores point and -mark to their original positions; and @code{save-restriction} restores -the original narrowing, if any. - -@node narrow Exercise, , what-line, Narrowing & Widening -@section Exercise with Narrowing - -Write a function that will display the first 60 characters of the -current buffer, even if you have narrowed the buffer to its latter -half so that the first line is inaccessible. Restore point, mark, and -narrowing. For this exercise, you need to use a whole potpourri of -functions, including @code{save-restriction}, @code{widen}, -@code{goto-char}, @code{point-min}, @code{message}, and -@code{buffer-substring}. - -@cindex Properties, mention of @code{buffer-substring-no-properties} -(@code{buffer-substring} is a previously unmentioned function you will -have to investigate yourself; or perhaps you will have to use -@code{buffer-substring-no-properties} or -@code{filter-buffer-substring} @dots{}, yet other functions. Text -properties are a feature otherwise not discussed here. @xref{Text -Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference -Manual}.) - -Additionally, do you really need @code{goto-char} or @code{point-min}? -Or can you write the function without them? - -@node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top -@comment node-name, next, previous, up -@chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions -@findex car, @r{introduced} -@findex cdr, @r{introduced} - -In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental -functions. The @code{cons} function is used to construct lists, and -the @code{car} and @code{cdr} functions are used to take them apart. - -In the walk through of the @code{copy-region-as-kill} function, we -will see @code{cons} as well as two variants on @code{cdr}, -namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.) - -@menu -* Strange Names:: An historical aside: why the strange names? -* car & cdr:: Functions for extracting part of a list. -* cons:: Constructing a list. -* nthcdr:: Calling @code{cdr} repeatedly. -* nth:: -* setcar:: Changing the first element of a list. -* setcdr:: Changing the rest of a list. -* cons Exercise:: -@end menu - -@node Strange Names, car & cdr, car cdr & cons, car cdr & cons -@ifnottex -@unnumberedsec Strange Names -@end ifnottex - -The name of the @code{cons} function is not unreasonable: it is an -abbreviation of the word `construct'. The origins of the names for -@code{car} and @code{cdr}, on the other hand, are esoteric: @code{car} -is an acronym from the phrase `Contents of the Address part of the -Register'; and @code{cdr} (pronounced `could-er') is an acronym from -the phrase `Contents of the Decrement part of the Register'. These -phrases refer to specific pieces of hardware on the very early -computer on which the original Lisp was developed. Besides being -obsolete, the phrases have been completely irrelevant for more than 25 -years to anyone thinking about Lisp. Nonetheless, although a few -brave scholars have begun to use more reasonable names for these -functions, the old terms are still in use. In particular, since the -terms are used in the Emacs Lisp source code, we will use them in this -introduction. - -@node car & cdr, cons, Strange Names, car cdr & cons -@comment node-name, next, previous, up -@section @code{car} and @code{cdr} - -The @sc{car} of a list is, quite simply, the first item in the list. -Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is -@code{rose}. - -@need 1200 -If you are reading this in Info in GNU Emacs, you can see this by -evaluating the following: - -@smallexample -(car '(rose violet daisy buttercup)) -@end smallexample - -@noindent -After evaluating the expression, @code{rose} will appear in the echo -area. - -Clearly, a more reasonable name for the @code{car} function would be -@code{first} and this is often suggested. - -@code{car} does not remove the first item from the list; it only reports -what it is. After @code{car} has been applied to a list, the list is -still the same as it was. In the jargon, @code{car} is -`non-destructive'. This feature turns out to be important. - -The @sc{cdr} of a list is the rest of the list, that is, the -@code{cdr} function returns the part of the list that follows the -first item. Thus, while the @sc{car} of the list @code{'(rose violet -daisy buttercup)} is @code{rose}, the rest of the list, the value -returned by the @code{cdr} function, is @code{(violet daisy -buttercup)}. - -@need 800 -You can see this by evaluating the following in the usual way: - -@smallexample -(cdr '(rose violet daisy buttercup)) -@end smallexample - -@noindent -When you evaluate this, @code{(violet daisy buttercup)} will appear in -the echo area. - -Like @code{car}, @code{cdr} does not remove any elements from the -list---it just returns a report of what the second and subsequent -elements are. - -Incidentally, in the example, the list of flowers is quoted. If it were -not, the Lisp interpreter would try to evaluate the list by calling -@code{rose} as a function. In this example, we do not want to do that. - -Clearly, a more reasonable name for @code{cdr} would be @code{rest}. - -(There is a lesson here: when you name new functions, consider very -carefully what you are doing, since you may be stuck with the names -for far longer than you expect. The reason this document perpetuates -these names is that the Emacs Lisp source code uses them, and if I did -not use them, you would have a hard time reading the code; but do, -please, try to avoid using these terms yourself. The people who come -after you will be grateful to you.) - -When @code{car} and @code{cdr} are applied to a list made up of symbols, -such as the list @code{(pine fir oak maple)}, the element of the list -returned by the function @code{car} is the symbol @code{pine} without -any parentheses around it. @code{pine} is the first element in the -list. However, the @sc{cdr} of the list is a list itself, @code{(fir -oak maple)}, as you can see by evaluating the following expressions in -the usual way: - -@smallexample -@group -(car '(pine fir oak maple)) - -(cdr '(pine fir oak maple)) -@end group -@end smallexample - -On the other hand, in a list of lists, the first element is itself a -list. @code{car} returns this first element as a list. For example, -the following list contains three sub-lists, a list of carnivores, a -list of herbivores and a list of sea mammals: - -@smallexample -@group -(car '((lion tiger cheetah) - (gazelle antelope zebra) - (whale dolphin seal))) -@end group -@end smallexample - -@noindent -In this example, the first element or @sc{car} of the list is the list of -carnivores, @code{(lion tiger cheetah)}, and the rest of the list is -@code{((gazelle antelope zebra) (whale dolphin seal))}. - -@smallexample -@group -(cdr '((lion tiger cheetah) - (gazelle antelope zebra) - (whale dolphin seal))) -@end group -@end smallexample - -It is worth saying again that @code{car} and @code{cdr} are -non-destructive---that is, they do not modify or change lists to which -they are applied. This is very important for how they are used. - -Also, in the first chapter, in the discussion about atoms, I said that -in Lisp, ``certain kinds of atom, such as an array, can be separated -into parts; but the mechanism for doing this is different from the -mechanism for splitting a list. As far as Lisp is concerned, the -atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The -@code{car} and @code{cdr} functions are used for splitting lists and -are considered fundamental to Lisp. Since they cannot split or gain -access to the parts of an array, an array is considered an atom. -Conversely, the other fundamental function, @code{cons}, can put -together or construct a list, but not an array. (Arrays are handled -by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU -Emacs Lisp Reference Manual}.) - -@node cons, nthcdr, car & cdr, car cdr & cons -@comment node-name, next, previous, up -@section @code{cons} -@findex cons, @r{introduced} - -The @code{cons} function constructs lists; it is the inverse of -@code{car} and @code{cdr}. For example, @code{cons} can be used to make -a four element list from the three element list, @code{(fir oak maple)}: - -@smallexample -(cons 'pine '(fir oak maple)) -@end smallexample - -@need 800 -@noindent -After evaluating this list, you will see - -@smallexample -(pine fir oak maple) -@end smallexample - -@noindent -appear in the echo area. @code{cons} causes the creation of a new -list in which the element is followed by the elements of the original -list. - -We often say that `@code{cons} puts a new element at the beginning of -a list; it attaches or pushes elements onto the list', but this -phrasing can be misleading, since @code{cons} does not change an -existing list, but creates a new one. - -Like @code{car} and @code{cdr}, @code{cons} is non-destructive. - -@menu -* Build a list:: -* length:: How to find the length of a list. -@end menu - -@node Build a list, length, cons, cons -@ifnottex -@unnumberedsubsec Build a list -@end ifnottex - -@code{cons} must have a list to attach to.@footnote{Actually, you can -@code{cons} an element to an atom to produce a dotted pair. Dotted -pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted -Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You -cannot start from absolutely nothing. If you are building a list, you -need to provide at least an empty list at the beginning. Here is a -series of @code{cons} expressions that build up a list of flowers. If -you are reading this in Info in GNU Emacs, you can evaluate each of -the expressions in the usual way; the value is printed in this text -after @samp{@result{}}, which you may read as `evaluates to'. - -@smallexample -@group -(cons 'buttercup ()) - @result{} (buttercup) -@end group - -@group -(cons 'daisy '(buttercup)) - @result{} (daisy buttercup) -@end group - -@group -(cons 'violet '(daisy buttercup)) - @result{} (violet daisy buttercup) -@end group - -@group -(cons 'rose '(violet daisy buttercup)) - @result{} (rose violet daisy buttercup) -@end group -@end smallexample - -@noindent -In the first example, the empty list is shown as @code{()} and a list -made up of @code{buttercup} followed by the empty list is constructed. -As you can see, the empty list is not shown in the list that was -constructed. All that you see is @code{(buttercup)}. The empty list is -not counted as an element of a list because there is nothing in an empty -list. Generally speaking, an empty list is invisible. - -The second example, @code{(cons 'daisy '(buttercup))} constructs a new, -two element list by putting @code{daisy} in front of @code{buttercup}; -and the third example constructs a three element list by putting -@code{violet} in front of @code{daisy} and @code{buttercup}. - -@node length, , Build a list, cons -@comment node-name, next, previous, up -@subsection Find the Length of a List: @code{length} -@findex length - -You can find out how many elements there are in a list by using the Lisp -function @code{length}, as in the following examples: - -@smallexample -@group -(length '(buttercup)) - @result{} 1 -@end group - -@group -(length '(daisy buttercup)) - @result{} 2 -@end group - -@group -(length (cons 'violet '(daisy buttercup))) - @result{} 3 -@end group -@end smallexample - -@noindent -In the third example, the @code{cons} function is used to construct a -three element list which is then passed to the @code{length} function as -its argument. - -@need 1200 -We can also use @code{length} to count the number of elements in an -empty list: - -@smallexample -@group -(length ()) - @result{} 0 -@end group -@end smallexample - -@noindent -As you would expect, the number of elements in an empty list is zero. - -An interesting experiment is to find out what happens if you try to find -the length of no list at all; that is, if you try to call @code{length} -without giving it an argument, not even an empty list: - -@smallexample -(length ) -@end smallexample - -@need 800 -@noindent -What you see, if you evaluate this, is the error message - -@smallexample -Lisp error: (wrong-number-of-arguments length 0) -@end smallexample - -@noindent -This means that the function receives the wrong number of -arguments, zero, when it expects some other number of arguments. In -this case, one argument is expected, the argument being a list whose -length the function is measuring. (Note that @emph{one} list is -@emph{one} argument, even if the list has many elements inside it.) - -The part of the error message that says @samp{length} is the name of -the function. - -@ignore -@code{length} is still a subroutine, but you need C-h f to discover that. - -In an earlier version: - This is written with a special notation, @samp{#<subr}, - that indicates that the function @code{length} is one of the primitive - functions written in C rather than in Emacs Lisp. (@samp{subr} is an - abbreviation for `subroutine'.) @xref{What Is a Function, , What Is a - Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more - about subroutines. -@end ignore - -@node nthcdr, nth, cons, car cdr & cons -@comment node-name, next, previous, up -@section @code{nthcdr} -@findex nthcdr - -The @code{nthcdr} function is associated with the @code{cdr} function. -What it does is take the @sc{cdr} of a list repeatedly. - -If you take the @sc{cdr} of the list @code{(pine fir -oak maple)}, you will be returned the list @code{(fir oak maple)}. If you -repeat this on what was returned, you will be returned the list -@code{(oak maple)}. (Of course, repeated @sc{cdr}ing on the original -list will just give you the original @sc{cdr} since the function does -not change the list. You need to evaluate the @sc{cdr} of the -@sc{cdr} and so on.) If you continue this, eventually you will be -returned an empty list, which in this case, instead of being shown as -@code{()} is shown as @code{nil}. - -@need 1200 -For review, here is a series of repeated @sc{cdr}s, the text following -the @samp{@result{}} shows what is returned. - -@smallexample -@group -(cdr '(pine fir oak maple)) - @result{}(fir oak maple) -@end group - -@group -(cdr '(fir oak maple)) - @result{} (oak maple) -@end group - -@group -(cdr '(oak maple)) - @result{}(maple) -@end group - -@group -(cdr '(maple)) - @result{} nil -@end group - -@group -(cdr 'nil) - @result{} nil -@end group - -@group -(cdr ()) - @result{} nil -@end group -@end smallexample - -@need 1200 -You can also do several @sc{cdr}s without printing the values in -between, like this: - -@smallexample -@group -(cdr (cdr '(pine fir oak maple))) - @result{} (oak maple) -@end group -@end smallexample - -@noindent -In this example, the Lisp interpreter evaluates the innermost list first. -The innermost list is quoted, so it just passes the list as it is to the -innermost @code{cdr}. This @code{cdr} passes a list made up of the -second and subsequent elements of the list to the outermost @code{cdr}, -which produces a list composed of the third and subsequent elements of -the original list. In this example, the @code{cdr} function is repeated -and returns a list that consists of the original list without its -first two elements. - -The @code{nthcdr} function does the same as repeating the call to -@code{cdr}. In the following example, the argument 2 is passed to the -function @code{nthcdr}, along with the list, and the value returned is -the list without its first two items, which is exactly the same -as repeating @code{cdr} twice on the list: - -@smallexample -@group -(nthcdr 2 '(pine fir oak maple)) - @result{} (oak maple) -@end group -@end smallexample - -@need 1200 -Using the original four element list, we can see what happens when -various numeric arguments are passed to @code{nthcdr}, including 0, 1, -and 5: - -@smallexample -@group -;; @r{Leave the list as it was.} -(nthcdr 0 '(pine fir oak maple)) - @result{} (pine fir oak maple) -@end group - -@group -;; @r{Return a copy without the first element.} -(nthcdr 1 '(pine fir oak maple)) - @result{} (fir oak maple) -@end group - -@group -;; @r{Return a copy of the list without three elements.} -(nthcdr 3 '(pine fir oak maple)) - @result{} (maple) -@end group - -@group -;; @r{Return a copy lacking all four elements.} -(nthcdr 4 '(pine fir oak maple)) - @result{} nil -@end group - -@group -;; @r{Return a copy lacking all elements.} -(nthcdr 5 '(pine fir oak maple)) - @result{} nil -@end group -@end smallexample - -@node nth, setcar, nthcdr, car cdr & cons -@comment node-name, next, previous, up -@section @code{nth} -@findex nth - -The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly. -The @code{nth} function takes the @sc{car} of the result returned by -@code{nthcdr}. It returns the Nth element of the list. - -@need 1500 -Thus, if it were not defined in C for speed, the definition of -@code{nth} would be: - -@smallexample -@group -(defun nth (n list) - "Returns the Nth element of LIST. -N counts from zero. If LIST is not that long, nil is returned." - (car (nthcdr n list))) -@end group -@end smallexample - -@noindent -(Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el}, -but its definition was redone in C in the 1980s.) - -The @code{nth} function returns a single element of a list. -This can be very convenient. - -Note that the elements are numbered from zero, not one. That is to -say, the first element of a list, its @sc{car} is the zeroth element. -This is called `zero-based' counting and often bothers people who -are accustomed to the first element in a list being number one, which -is `one-based'. - -@need 1250 -For example: - -@smallexample -@group -(nth 0 '("one" "two" "three")) - @result{} "one" - -(nth 1 '("one" "two" "three")) - @result{} "two" -@end group -@end smallexample - -It is worth mentioning that @code{nth}, like @code{nthcdr} and -@code{cdr}, does not change the original list---the function is -non-destructive. This is in sharp contrast to the @code{setcar} and -@code{setcdr} functions. - -@node setcar, setcdr, nth, car cdr & cons -@comment node-name, next, previous, up -@section @code{setcar} -@findex setcar - -As you might guess from their names, the @code{setcar} and @code{setcdr} -functions set the @sc{car} or the @sc{cdr} of a list to a new value. -They actually change the original list, unlike @code{car} and @code{cdr} -which leave the original list as it was. One way to find out how this -works is to experiment. We will start with the @code{setcar} function. - -@need 1200 -First, we can make a list and then set the value of a variable to the -list, using the @code{setq} function. Here is a list of animals: - -@smallexample -(setq animals '(antelope giraffe lion tiger)) -@end smallexample - -@noindent -If you are reading this in Info inside of GNU Emacs, you can evaluate -this expression in the usual fashion, by positioning the cursor after -the expression and typing @kbd{C-x C-e}. (I'm doing this right here -as I write this. This is one of the advantages of having the -interpreter built into the computing environment. Incidentally, when -there is nothing on the line after the final parentheses, such as a -comment, point can be on the next line. Thus, if your cursor is in -the first column of the next line, you do not need to move it. -Indeed, Emacs permits any amount of white space after the final -parenthesis.) - -@need 1200 -When we evaluate the variable @code{animals}, we see that it is bound to -the list @code{(antelope giraffe lion tiger)}: - -@smallexample -@group -animals - @result{} (antelope giraffe lion tiger) -@end group -@end smallexample - -@noindent -Put another way, the variable @code{animals} points to the list -@code{(antelope giraffe lion tiger)}. - -Next, evaluate the function @code{setcar} while passing it two -arguments, the variable @code{animals} and the quoted symbol -@code{hippopotamus}; this is done by writing the three element list -@code{(setcar animals 'hippopotamus)} and then evaluating it in the -usual fashion: - -@smallexample -(setcar animals 'hippopotamus) -@end smallexample - -@need 1200 -@noindent -After evaluating this expression, evaluate the variable @code{animals} -again. You will see that the list of animals has changed: - -@smallexample -@group -animals - @result{} (hippopotamus giraffe lion tiger) -@end group -@end smallexample - -@noindent -The first element on the list, @code{antelope} is replaced by -@code{hippopotamus}. - -So we can see that @code{setcar} did not add a new element to the list -as @code{cons} would have; it replaced @code{antelope} with -@code{hippopotamus}; it @emph{changed} the list. - -@node setcdr, cons Exercise, setcar, car cdr & cons -@comment node-name, next, previous, up -@section @code{setcdr} -@findex setcdr - -The @code{setcdr} function is similar to the @code{setcar} function, -except that the function replaces the second and subsequent elements of -a list rather than the first element. - -(To see how to change the last element of a list, look ahead to -@ref{kill-new function, , The @code{kill-new} function}, which uses -the @code{nthcdr} and @code{setcdr} functions.) - -@need 1200 -To see how this works, set the value of the variable to a list of -domesticated animals by evaluating the following expression: - -@smallexample -(setq domesticated-animals '(horse cow sheep goat)) -@end smallexample - -@need 1200 -@noindent -If you now evaluate the list, you will be returned the list -@code{(horse cow sheep goat)}: - -@smallexample -@group -domesticated-animals - @result{} (horse cow sheep goat) -@end group -@end smallexample - -@need 1200 -Next, evaluate @code{setcdr} with two arguments, the name of the -variable which has a list as its value, and the list to which the -@sc{cdr} of the first list will be set; - -@smallexample -(setcdr domesticated-animals '(cat dog)) -@end smallexample - -@noindent -If you evaluate this expression, the list @code{(cat dog)} will appear -in the echo area. This is the value returned by the function. The -result we are interested in is the ``side effect'', which we can see by -evaluating the variable @code{domesticated-animals}: - -@smallexample -@group -domesticated-animals - @result{} (horse cat dog) -@end group -@end smallexample - -@noindent -Indeed, the list is changed from @code{(horse cow sheep goat)} to -@code{(horse cat dog)}. The @sc{cdr} of the list is changed from -@code{(cow sheep goat)} to @code{(cat dog)}. - -@node cons Exercise, , setcdr, car cdr & cons -@section Exercise - -Construct a list of four birds by evaluating several expressions with -@code{cons}. Find out what happens when you @code{cons} a list onto -itself. Replace the first element of the list of four birds with a -fish. Replace the rest of that list with a list of other fish. - -@node Cutting & Storing Text, List Implementation, car cdr & cons, Top -@comment node-name, next, previous, up -@chapter Cutting and Storing Text -@cindex Cutting and storing text -@cindex Storing and cutting text -@cindex Killing text -@cindex Clipping text -@cindex Erasing text -@cindex Deleting text - -Whenever you cut or clip text out of a buffer with a `kill' command in -GNU Emacs, it is stored in a list and you can bring it back with a -`yank' command. - -(The use of the word `kill' in Emacs for processes which specifically -@emph{do not} destroy the values of the entities is an unfortunate -historical accident. A much more appropriate word would be `clip' since -that is what the kill commands do; they clip text out of a buffer and -put it into storage from which it can be brought back. I have often -been tempted to replace globally all occurrences of `kill' in the Emacs -sources with `clip' and all occurrences of `killed' with `clipped'.) - -@menu -* Storing Text:: Text is stored in a list. -* zap-to-char:: Cutting out text up to a character. -* kill-region:: Cutting text out of a region. -* copy-region-as-kill:: A definition for copying text. -* Digression into C:: Minor note on C programming language macros. -* defvar:: How to give a variable an initial value. -* cons & search-fwd Review:: -* search Exercises:: -@end menu - -@node Storing Text, zap-to-char, Cutting & Storing Text, Cutting & Storing Text -@ifnottex -@unnumberedsec Storing Text in a List -@end ifnottex - -When text is cut out of a buffer, it is stored on a list. Successive -pieces of text are stored on the list successively, so the list might -look like this: - -@smallexample -("a piece of text" "previous piece") -@end smallexample - -@need 1200 -@noindent -The function @code{cons} can be used to create a new list from a piece -of text (an `atom', to use the jargon) and an existing list, like -this: - -@smallexample -@group -(cons "another piece" - '("a piece of text" "previous piece")) -@end group -@end smallexample - -@need 1200 -@noindent -If you evaluate this expression, a list of three elements will appear in -the echo area: - -@smallexample -("another piece" "a piece of text" "previous piece") -@end smallexample - -With the @code{car} and @code{nthcdr} functions, you can retrieve -whichever piece of text you want. For example, in the following code, -@code{nthcdr 1 @dots{}} returns the list with the first item removed; -and the @code{car} returns the first element of that remainder---the -second element of the original list: - -@smallexample -@group -(car (nthcdr 1 '("another piece" - "a piece of text" - "previous piece"))) - @result{} "a piece of text" -@end group -@end smallexample - -The actual functions in Emacs are more complex than this, of course. -The code for cutting and retrieving text has to be written so that -Emacs can figure out which element in the list you want---the first, -second, third, or whatever. In addition, when you get to the end of -the list, Emacs should give you the first element of the list, rather -than nothing at all. - -The list that holds the pieces of text is called the @dfn{kill ring}. -This chapter leads up to a description of the kill ring and how it is -used by first tracing how the @code{zap-to-char} function works. This -function uses (or `calls') a function that invokes a function that -manipulates the kill ring. Thus, before reaching the mountains, we -climb the foothills. - -A subsequent chapter describes how text that is cut from the buffer is -retrieved. @xref{Yanking, , Yanking Text Back}. - -@node zap-to-char, kill-region, Storing Text, Cutting & Storing Text -@comment node-name, next, previous, up -@section @code{zap-to-char} -@findex zap-to-char - -The @code{zap-to-char} function changed little between GNU Emacs -version 19 and GNU Emacs version 22. However, @code{zap-to-char} -calls another function, @code{kill-region}, which enjoyed a major -rewrite. - -The @code{kill-region} function in Emacs 19 is complex, but does not -use code that is important at this time. We will skip it. - -The @code{kill-region} function in Emacs 22 is easier to read than the -same function in Emacs 19 and introduces a very important concept, -that of error handling. We will walk through the function. - -But first, let us look at the interactive @code{zap-to-char} function. - -@menu -* Complete zap-to-char:: The complete implementation. -* zap-to-char interactive:: A three part interactive expression. -* zap-to-char body:: A short overview. -* search-forward:: How to search for a string. -* progn:: The @code{progn} special form. -* Summing up zap-to-char:: Using @code{point} and @code{search-forward}. -@end menu - -@node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char -@ifnottex -@unnumberedsubsec The Complete @code{zap-to-char} Implementation -@end ifnottex - -The @code{zap-to-char} function removes the text in the region between -the location of the cursor (i.e., of point) up to and including the -next occurrence of a specified character. The text that -@code{zap-to-char} removes is put in the kill ring; and it can be -retrieved from the kill ring by typing @kbd{C-y} (@code{yank}). If -the command is given an argument, it removes text through that number -of occurrences. Thus, if the cursor were at the beginning of this -sentence and the character were @samp{s}, @samp{Thus} would be -removed. If the argument were two, @samp{Thus, if the curs} would be -removed, up to and including the @samp{s} in @samp{cursor}. - -If the specified character is not found, @code{zap-to-char} will say -``Search failed'', tell you the character you typed, and not remove -any text. - -In order to determine how much text to remove, @code{zap-to-char} uses -a search function. Searches are used extensively in code that -manipulates text, and we will focus attention on them as well as on the -deletion command. - -@ignore -@c GNU Emacs version 19 -(defun zap-to-char (arg char) ; version 19 implementation - "Kill up to and including ARG'th occurrence of CHAR. -Goes backward if ARG is negative; error if CHAR not found." - (interactive "*p\ncZap to char: ") - (kill-region (point) - (progn - (search-forward - (char-to-string char) nil nil arg) - (point)))) -@end ignore - -@need 1250 -Here is the complete text of the version 22 implementation of the function: - -@c GNU Emacs 22 -@smallexample -@group -(defun zap-to-char (arg char) - "Kill up to and including ARG'th occurrence of CHAR. -Case is ignored if `case-fold-search' is non-nil in the current buffer. -Goes backward if ARG is negative; error if CHAR not found." - (interactive "p\ncZap to char: ") - (if (char-table-p translation-table-for-input) - (setq char (or (aref translation-table-for-input char) char))) - (kill-region (point) (progn - (search-forward (char-to-string char) nil nil arg) - (point)))) -@end group -@end smallexample - -The documentation is thorough. You do need to know the jargon meaning -of the word `kill'. - -@node zap-to-char interactive, zap-to-char body, Complete zap-to-char, zap-to-char -@comment node-name, next, previous, up -@subsection The @code{interactive} Expression - -@need 800 -The interactive expression in the @code{zap-to-char} command looks like -this: - -@smallexample -(interactive "p\ncZap to char: ") -@end smallexample - -The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies -two different things. First, and most simply, is the @samp{p}. -This part is separated from the next part by a newline, @samp{\n}. -The @samp{p} means that the first argument to the function will be -passed the value of a `processed prefix'. The prefix argument is -passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If -the function is called interactively without a prefix, 1 is passed to -this argument. - -The second part of @code{"p\ncZap to char:@: "} is -@samp{cZap to char:@: }. In this part, the lower case @samp{c} -indicates that @code{interactive} expects a prompt and that the -argument will be a character. The prompt follows the @samp{c} and is -the string @samp{Zap to char:@: } (with a space after the colon to -make it look good). - -What all this does is prepare the arguments to @code{zap-to-char} so they -are of the right type, and give the user a prompt. - -In a read-only buffer, the @code{zap-to-char} function copies the text -to the kill ring, but does not remove it. The echo area displays a -message saying that the buffer is read-only. Also, the terminal may -beep or blink at you. - -@node zap-to-char body, search-forward, zap-to-char interactive, zap-to-char -@comment node-name, next, previous, up -@subsection The Body of @code{zap-to-char} - -The body of the @code{zap-to-char} function contains the code that -kills (that is, removes) the text in the region from the current -position of the cursor up to and including the specified character. - -The first part of the code looks like this: - -@smallexample -(if (char-table-p translation-table-for-input) - (setq char (or (aref translation-table-for-input char) char))) -(kill-region (point) (progn - (search-forward (char-to-string char) nil nil arg) - (point))) -@end smallexample - -@noindent -@code{char-table-p} is an hitherto unseen function. It determines -whether its argument is a character table. When it is, it sets the -character passed to @code{zap-to-char} to one of them, if that -character exists, or to the character itself. (This becomes important -for certain characters in non-European languages. The @code{aref} -function extracts an element from an array. It is an array-specific -function that is not described in this document. @xref{Arrays, , -Arrays, elisp, The GNU Emacs Lisp Reference Manual}.) - -@noindent -@code{(point)} is the current position of the cursor. - -The next part of the code is an expression using @code{progn}. The body -of the @code{progn} consists of calls to @code{search-forward} and -@code{point}. - -It is easier to understand how @code{progn} works after learning about -@code{search-forward}, so we will look at @code{search-forward} and -then at @code{progn}. - -@node search-forward, progn, zap-to-char body, zap-to-char -@comment node-name, next, previous, up -@subsection The @code{search-forward} Function -@findex search-forward - -The @code{search-forward} function is used to locate the -zapped-for-character in @code{zap-to-char}. If the search is -successful, @code{search-forward} leaves point immediately after the -last character in the target string. (In @code{zap-to-char}, the -target string is just one character long. @code{zap-to-char} uses the -function @code{char-to-string} to ensure that the computer treats that -character as a string.) If the search is backwards, -@code{search-forward} leaves point just before the first character in -the target. Also, @code{search-forward} returns @code{t} for true. -(Moving point is therefore a `side effect'.) - -@need 1250 -In @code{zap-to-char}, the @code{search-forward} function looks like this: - -@smallexample -(search-forward (char-to-string char) nil nil arg) -@end smallexample - -The @code{search-forward} function takes four arguments: - -@enumerate -@item -The first argument is the target, what is searched for. This must be a -string, such as @samp{"z"}. - -As it happens, the argument passed to @code{zap-to-char} is a single -character. Because of the way computers are built, the Lisp -interpreter may treat a single character as being different from a -string of characters. Inside the computer, a single character has a -different electronic format than a string of one character. (A single -character can often be recorded in the computer using exactly one -byte; but a string may be longer, and the computer needs to be ready -for this.) Since the @code{search-forward} function searches for a -string, the character that the @code{zap-to-char} function receives as -its argument must be converted inside the computer from one format to -the other; otherwise the @code{search-forward} function will fail. -The @code{char-to-string} function is used to make this conversion. - -@item -The second argument bounds the search; it is specified as a position in -the buffer. In this case, the search can go to the end of the buffer, -so no bound is set and the second argument is @code{nil}. - -@item -The third argument tells the function what it should do if the search -fails---it can signal an error (and print a message) or it can return -@code{nil}. A @code{nil} as the third argument causes the function to -signal an error when the search fails. - -@item -The fourth argument to @code{search-forward} is the repeat count---how -many occurrences of the string to look for. This argument is optional -and if the function is called without a repeat count, this argument is -passed the value 1. If this argument is negative, the search goes -backwards. -@end enumerate - -@need 800 -In template form, a @code{search-forward} expression looks like this: - -@smallexample -@group -(search-forward "@var{target-string}" - @var{limit-of-search} - @var{what-to-do-if-search-fails} - @var{repeat-count}) -@end group -@end smallexample - -We will look at @code{progn} next. - -@node progn, Summing up zap-to-char, search-forward, zap-to-char -@comment node-name, next, previous, up -@subsection The @code{progn} Special Form -@findex progn - -@code{progn} is a special form that causes each of its arguments to be -evaluated in sequence and then returns the value of the last one. The -preceding expressions are evaluated only for the side effects they -perform. The values produced by them are discarded. - -@need 800 -The template for a @code{progn} expression is very simple: - -@smallexample -@group -(progn - @var{body}@dots{}) -@end group -@end smallexample - -In @code{zap-to-char}, the @code{progn} expression has to do two things: -put point in exactly the right position; and return the location of -point so that @code{kill-region} will know how far to kill to. - -The first argument to the @code{progn} is @code{search-forward}. When -@code{search-forward} finds the string, the function leaves point -immediately after the last character in the target string. (In this -case the target string is just one character long.) If the search is -backwards, @code{search-forward} leaves point just before the first -character in the target. The movement of point is a side effect. - -The second and last argument to @code{progn} is the expression -@code{(point)}. This expression returns the value of point, which in -this case will be the location to which it has been moved by -@code{search-forward}. (In the source, a line that tells the function -to go to the previous character, if it is going forward, was commented -out in 1999; I don't remember whether that feature or mis-feature was -ever a part of the distributed source.) The value of @code{point} is -returned by the @code{progn} expression and is passed to -@code{kill-region} as @code{kill-region}'s second argument. - -@node Summing up zap-to-char, , progn, zap-to-char -@comment node-name, next, previous, up -@subsection Summing up @code{zap-to-char} - -Now that we have seen how @code{search-forward} and @code{progn} work, -we can see how the @code{zap-to-char} function works as a whole. - -The first argument to @code{kill-region} is the position of the cursor -when the @code{zap-to-char} command is given---the value of point at -that time. Within the @code{progn}, the search function then moves -point to just after the zapped-to-character and @code{point} returns the -value of this location. The @code{kill-region} function puts together -these two values of point, the first one as the beginning of the region -and the second one as the end of the region, and removes the region. - -The @code{progn} special form is necessary because the -@code{kill-region} command takes two arguments; and it would fail if -@code{search-forward} and @code{point} expressions were written in -sequence as two additional arguments. The @code{progn} expression is -a single argument to @code{kill-region} and returns the one value that -@code{kill-region} needs for its second argument. - -@node kill-region, copy-region-as-kill, zap-to-char, Cutting & Storing Text -@comment node-name, next, previous, up -@section @code{kill-region} -@findex kill-region - -The @code{zap-to-char} function uses the @code{kill-region} function. -This function clips text from a region and copies that text to -the kill ring, from which it may be retrieved. - -@ignore -GNU Emacs 22: - -(defun kill-region (beg end &optional yank-handler) - "Kill (\"cut\") text between point and mark. -This deletes the text from the buffer and saves it in the kill ring. -The command \\[yank] can retrieve it from there. -\(If you want to kill and then yank immediately, use \\[kill-ring-save].) - -If you want to append the killed region to the last killed text, -use \\[append-next-kill] before \\[kill-region]. - -If the buffer is read-only, Emacs will beep and refrain from deleting -the text, but put the text in the kill ring anyway. This means that -you can use the killing commands to copy text from a read-only buffer. - -This is the primitive for programs to kill text (as opposed to deleting it). -Supply two arguments, character positions indicating the stretch of text - to be killed. -Any command that calls this function is a \"kill command\". -If the previous command was also a kill command, -the text killed this time appends to the text killed last time -to make one entry in the kill ring. - -In Lisp code, optional third arg YANK-HANDLER, if non-nil, -specifies the yank-handler text property to be set on the killed -text. See `insert-for-yank'." - ;; Pass point first, then mark, because the order matters - ;; when calling kill-append. - (interactive (list (point) (mark))) - (unless (and beg end) - (error "The mark is not set now, so there is no region")) - (condition-case nil - (let ((string (filter-buffer-substring beg end t))) - (when string ;STRING is nil if BEG = END - ;; Add that string to the kill ring, one way or another. - (if (eq last-command 'kill-region) - (kill-append string (< end beg) yank-handler) - (kill-new string nil yank-handler))) - (when (or string (eq last-command 'kill-region)) - (setq this-command 'kill-region)) - nil) - ((buffer-read-only text-read-only) - ;; The code above failed because the buffer, or some of the characters - ;; in the region, are read-only. - ;; We should beep, in case the user just isn't aware of this. - ;; However, there's no harm in putting - ;; the region's text in the kill ring, anyway. - (copy-region-as-kill beg end) - ;; Set this-command now, so it will be set even if we get an error. - (setq this-command 'kill-region) - ;; This should barf, if appropriate, and give us the correct error. - (if kill-read-only-ok - (progn (message "Read only text copied to kill ring") nil) - ;; Signal an error if the buffer is read-only. - (barf-if-buffer-read-only) - ;; If the buffer isn't read-only, the text is. - (signal 'text-read-only (list (current-buffer))))))) -@end ignore - -The Emacs 22 version of that function uses @code{condition-case} and -@code{copy-region-as-kill}, both of which we will explain. -@code{condition-case} is an important special form. - -In essence, the @code{kill-region} function calls -@code{condition-case}, which takes three arguments. In this function, -the first argument does nothing. The second argument contains the -code that does the work when all goes well. The third argument -contains the code that is called in the event of an error. - -@menu -* Complete kill-region:: The function definition. -* condition-case:: Dealing with a problem. -* Lisp macro:: -@end menu - -@node Complete kill-region, condition-case, kill-region, kill-region -@ifnottex -@unnumberedsubsec The Complete @code{kill-region} Definition -@end ifnottex - -@need 1200 -We will go through the @code{condition-case} code in a moment. First, -let us look at the definition of @code{kill-region}, with comments -added: - -@c GNU Emacs 22: -@smallexample -@group -(defun kill-region (beg end) - "Kill (\"cut\") text between point and mark. -This deletes the text from the buffer and saves it in the kill ring. -The command \\[yank] can retrieve it from there. @dots{} " -@end group - -@group - ;; @bullet{} Since order matters, pass point first. - (interactive (list (point) (mark))) - ;; @bullet{} And tell us if we cannot cut the text. - ;; `unless' is an `if' without a then-part. - (unless (and beg end) - (error "The mark is not set now, so there is no region")) -@end group - -@group - ;; @bullet{} `condition-case' takes three arguments. - ;; If the first argument is nil, as it is here, - ;; information about the error signal is not - ;; stored for use by another function. - (condition-case nil -@end group - -@group - ;; @bullet{} The second argument to `condition-case' tells the - ;; Lisp interpreter what to do when all goes well. -@end group - -@group - ;; It starts with a `let' function that extracts the string - ;; and tests whether it exists. If so (that is what the - ;; `when' checks), it calls an `if' function that determines - ;; whether the previous command was another call to - ;; `kill-region'; if it was, then the new text is appended to - ;; the previous text; if not, then a different function, - ;; `kill-new', is called. -@end group - -@group - ;; The `kill-append' function concatenates the new string and - ;; the old. The `kill-new' function inserts text into a new - ;; item in the kill ring. -@end group - -@group - ;; `when' is an `if' without an else-part. The second `when' - ;; again checks whether the current string exists; in - ;; addition, it checks whether the previous command was - ;; another call to `kill-region'. If one or the other - ;; condition is true, then it sets the current command to - ;; be `kill-region'. -@end group -@group - (let ((string (filter-buffer-substring beg end t))) - (when string ;STRING is nil if BEG = END - ;; Add that string to the kill ring, one way or another. - (if (eq last-command 'kill-region) -@end group -@group - ;; @minus{} `yank-handler' is an optional argument to - ;; `kill-region' that tells the `kill-append' and - ;; `kill-new' functions how deal with properties - ;; added to the text, such as `bold' or `italics'. - (kill-append string (< end beg) yank-handler) - (kill-new string nil yank-handler))) - (when (or string (eq last-command 'kill-region)) - (setq this-command 'kill-region)) - nil) -@end group - -@group - ;; @bullet{} The third argument to `condition-case' tells the interpreter - ;; what to do with an error. -@end group -@group - ;; The third argument has a conditions part and a body part. - ;; If the conditions are met (in this case, - ;; if text or buffer are read-only) - ;; then the body is executed. -@end group -@group - ;; The first part of the third argument is the following: - ((buffer-read-only text-read-only) ;; the if-part - ;; @dots{} the then-part - (copy-region-as-kill beg end) -@end group -@group - ;; Next, also as part of the then-part, set this-command, so - ;; it will be set in an error - (setq this-command 'kill-region) - ;; Finally, in the then-part, send a message if you may copy - ;; the text to the kill ring without signally an error, but - ;; don't if you may not. -@end group -@group - (if kill-read-only-ok - (progn (message "Read only text copied to kill ring") nil) - (barf-if-buffer-read-only) - ;; If the buffer isn't read-only, the text is. - (signal 'text-read-only (list (current-buffer))))) -@end group -@end smallexample - -@ignore -@c v 21 -@smallexample -@group -(defun kill-region (beg end) - "Kill between point and mark. -The text is deleted but saved in the kill ring." - (interactive "r") -@end group - -@group - ;; 1. `condition-case' takes three arguments. - ;; If the first argument is nil, as it is here, - ;; information about the error signal is not - ;; stored for use by another function. - (condition-case nil -@end group - -@group - ;; 2. The second argument to `condition-case' - ;; tells the Lisp interpreter what to do when all goes well. -@end group - -@group - ;; The `delete-and-extract-region' function usually does the - ;; work. If the beginning and ending of the region are both - ;; the same, then the variable `string' will be empty, or nil - (let ((string (delete-and-extract-region beg end))) -@end group - -@group - ;; `when' is an `if' clause that cannot take an `else-part'. - ;; Emacs normally sets the value of `last-command' to the - ;; previous command. -@end group -@group - ;; `kill-append' concatenates the new string and the old. - ;; `kill-new' inserts text into a new item in the kill ring. - (when string - (if (eq last-command 'kill-region) - ;; if true, prepend string - (kill-append string (< end beg)) - (kill-new string))) - (setq this-command 'kill-region)) -@end group - -@group - ;; 3. The third argument to `condition-case' tells the interpreter - ;; what to do with an error. -@end group -@group - ;; The third argument has a conditions part and a body part. - ;; If the conditions are met (in this case, - ;; if text or buffer are read-only) - ;; then the body is executed. -@end group -@group - ((buffer-read-only text-read-only) ;; this is the if-part - ;; then... - (copy-region-as-kill beg end) -@end group -@group - (if kill-read-only-ok ;; usually this variable is nil - (message "Read only text copied to kill ring") - ;; or else, signal an error if the buffer is read-only; - (barf-if-buffer-read-only) - ;; and, in any case, signal that the text is read-only. - (signal 'text-read-only (list (current-buffer))))))) -@end group -@end smallexample -@end ignore - -@node condition-case, Lisp macro, Complete kill-region, kill-region -@comment node-name, next, previous, up -@subsection @code{condition-case} -@findex condition-case - -As we have seen earlier (@pxref{Making Errors, , Generate an Error -Message}), when the Emacs Lisp interpreter has trouble evaluating an -expression, it provides you with help; in the jargon, this is called -``signaling an error''. Usually, the computer stops the program and -shows you a message. - -However, some programs undertake complicated actions. They should not -simply stop on an error. In the @code{kill-region} function, the most -likely error is that you will try to kill text that is read-only and -cannot be removed. So the @code{kill-region} function contains code -to handle this circumstance. This code, which makes up the body of -the @code{kill-region} function, is inside of a @code{condition-case} -special form. - -@need 800 -The template for @code{condition-case} looks like this: - -@smallexample -@group -(condition-case - @var{var} - @var{bodyform} - @var{error-handler}@dots{}) -@end group -@end smallexample - -The second argument, @var{bodyform}, is straightforward. The -@code{condition-case} special form causes the Lisp interpreter to -evaluate the code in @var{bodyform}. If no error occurs, the special -form returns the code's value and produces the side-effects, if any. - -In short, the @var{bodyform} part of a @code{condition-case} -expression determines what should happen when everything works -correctly. - -However, if an error occurs, among its other actions, the function -generating the error signal will define one or more error condition -names. - -An error handler is the third argument to @code{condition case}. -An error handler has two parts, a @var{condition-name} and a -@var{body}. If the @var{condition-name} part of an error handler -matches a condition name generated by an error, then the @var{body} -part of the error handler is run. - -As you will expect, the @var{condition-name} part of an error handler -may be either a single condition name or a list of condition names. - -Also, a complete @code{condition-case} expression may contain more -than one error handler. When an error occurs, the first applicable -handler is run. - -Lastly, the first argument to the @code{condition-case} expression, -the @var{var} argument, is sometimes bound to a variable that -contains information about the error. However, if that argument is -nil, as is the case in @code{kill-region}, that information is -discarded. - -@need 1200 -In brief, in the @code{kill-region} function, the code -@code{condition-case} works like this: - -@smallexample -@group -@var{If no errors}, @var{run only this code} - @var{but}, @var{if errors}, @var{run this other code}. -@end group -@end smallexample - -@ignore -2006 Oct 24 -In Emacs 22, -copy-region-as-kill is short, 12 lines, and uses -filter-buffer-substring, which is longer, 39 lines -and has delete-and-extract-region in it. -delete-and-extract-region is written in C. - -see Initializing a Variable with @code{defvar} -this is line 8054 -Initializing a Variable with @code{defvar} includes line 8350 -@end ignore - -@node Lisp macro, , condition-case, kill-region -@comment node-name, next, previous, up -@subsection Lisp macro -@cindex Macro, lisp -@cindex Lisp macro - -The part of the @code{condition-case} expression that is evaluated in -the expectation that all goes well has a @code{when}. The code uses -@code{when} to determine whether the @code{string} variable points to -text that exists. - -A @code{when} expression is simply a programmers' convenience. It is -an @code{if} without the possibility of an else clause. In your mind, -you can replace @code{when} with @code{if} and understand what goes -on. That is what the Lisp interpreter does. - -Technically speaking, @code{when} is a Lisp macro. A Lisp @dfn{macro} -enables you to define new control constructs and other language -features. It tells the interpreter how to compute another Lisp -expression which will in turn compute the value. In this case, the -`other expression' is an @code{if} expression. - -The @code{kill-region} function definition also has an @code{unless} -macro; it is the converse of @code{when}. The @code{unless} macro is -an @code{if} without a then clause - -For more about Lisp macros, see @ref{Macros, , Macros, elisp, The GNU -Emacs Lisp Reference Manual}. The C programming language also -provides macros. These are different, but also useful. - -@ignore -We will briefly look at C macros in -@ref{Digression into C}. -@end ignore - -@need 1200 -Regarding the @code{when} macro, in the @code{condition-case} -expression, when the string has content, then another conditional -expression is executed. This is an @code{if} with both a then-part -and an else-part. - -@smallexample -@group -(if (eq last-command 'kill-region) - (kill-append string (< end beg) yank-handler) - (kill-new string nil yank-handler)) -@end group -@end smallexample - -The then-part is evaluated if the previous command was another call to -@code{kill-region}; if not, the else-part is evaluated. - -@code{yank-handler} is an optional argument to @code{kill-region} that -tells the @code{kill-append} and @code{kill-new} functions how deal -with properties added to the text, such as `bold' or `italics'. - -@code{last-command} is a variable that comes with Emacs that we have -not seen before. Normally, whenever a function is executed, Emacs -sets the value of @code{last-command} to the previous command. - -@need 1200 -In this segment of the definition, the @code{if} expression checks -whether the previous command was @code{kill-region}. If it was, - -@smallexample -(kill-append string (< end beg) yank-handler) -@end smallexample - -@noindent -concatenates a copy of the newly clipped text to the just previously -clipped text in the kill ring. - -@node copy-region-as-kill, Digression into C, kill-region, Cutting & Storing Text -@comment node-name, next, previous, up -@section @code{copy-region-as-kill} -@findex copy-region-as-kill -@findex nthcdr - -The @code{copy-region-as-kill} function copies a region of text from a -buffer and (via either @code{kill-append} or @code{kill-new}) saves it -in the @code{kill-ring}. - -If you call @code{copy-region-as-kill} immediately after a -@code{kill-region} command, Emacs appends the newly copied text to the -previously copied text. This means that if you yank back the text, you -get it all, from both this and the previous operation. On the other -hand, if some other command precedes the @code{copy-region-as-kill}, -the function copies the text into a separate entry in the kill ring. - -@menu -* Complete copy-region-as-kill:: The complete function definition. -* copy-region-as-kill body:: The body of @code{copy-region-as-kill}. -@end menu - -@node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill -@ifnottex -@unnumberedsubsec The complete @code{copy-region-as-kill} function definition -@end ifnottex - -@need 1200 -Here is the complete text of the version 22 @code{copy-region-as-kill} -function: - -@smallexample -@group -(defun copy-region-as-kill (beg end) - "Save the region as if killed, but don't kill it. -In Transient Mark mode, deactivate the mark. -If `interprogram-cut-function' is non-nil, also save the text for a window -system cut and paste." - (interactive "r") -@end group -@group - (if (eq last-command 'kill-region) - (kill-append (filter-buffer-substring beg end) (< end beg)) - (kill-new (filter-buffer-substring beg end))) -@end group -@group - (if transient-mark-mode - (setq deactivate-mark t)) - nil) -@end group -@end smallexample - -@need 800 -As usual, this function can be divided into its component parts: - -@smallexample -@group -(defun copy-region-as-kill (@var{argument-list}) - "@var{documentation}@dots{}" - (interactive "r") - @var{body}@dots{}) -@end group -@end smallexample - -The arguments are @code{beg} and @code{end} and the function is -interactive with @code{"r"}, so the two arguments must refer to the -beginning and end of the region. If you have been reading though this -document from the beginning, understanding these parts of a function is -almost becoming routine. - -The documentation is somewhat confusing unless you remember that the -word `kill' has a meaning different from usual. The `Transient Mark' -and @code{interprogram-cut-function} comments explain certain -side-effects. - -After you once set a mark, a buffer always contains a region. If you -wish, you can use Transient Mark mode to highlight the region -temporarily. (No one wants to highlight the region all the time, so -Transient Mark mode highlights it only at appropriate times. Many -people turn off Transient Mark mode, so the region is never -highlighted.) - -Also, a windowing system allows you to copy, cut, and paste among -different programs. In the X windowing system, for example, the -@code{interprogram-cut-function} function is @code{x-select-text}, -which works with the windowing system's equivalent of the Emacs kill -ring. - -The body of the @code{copy-region-as-kill} function starts with an -@code{if} clause. What this clause does is distinguish between two -different situations: whether or not this command is executed -immediately after a previous @code{kill-region} command. In the first -case, the new region is appended to the previously copied text. -Otherwise, it is inserted into the beginning of the kill ring as a -separate piece of text from the previous piece. - -The last two lines of the function prevent the region from lighting up -if Transient Mark mode is turned on. - -The body of @code{copy-region-as-kill} merits discussion in detail. - -@node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill -@comment node-name, next, previous, up -@subsection The Body of @code{copy-region-as-kill} - -The @code{copy-region-as-kill} function works in much the same way as -the @code{kill-region} function. Both are written so that two or more -kills in a row combine their text into a single entry. If you yank -back the text from the kill ring, you get it all in one piece. -Moreover, kills that kill forward from the current position of the -cursor are added to the end of the previously copied text and commands -that copy text backwards add it to the beginning of the previously -copied text. This way, the words in the text stay in the proper -order. - -Like @code{kill-region}, the @code{copy-region-as-kill} function makes -use of the @code{last-command} variable that keeps track of the -previous Emacs command. - -@menu -* last-command & this-command:: -* kill-append function:: -* kill-new function:: -@end menu - -@node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body -@ifnottex -@unnumberedsubsubsec @code{last-command} and @code{this-command} -@end ifnottex - -Normally, whenever a function is executed, Emacs sets the value of -@code{this-command} to the function being executed (which in this case -would be @code{copy-region-as-kill}). At the same time, Emacs sets -the value of @code{last-command} to the previous value of -@code{this-command}. - -In the first part of the body of the @code{copy-region-as-kill} -function, an @code{if} expression determines whether the value of -@code{last-command} is @code{kill-region}. If so, the then-part of -the @code{if} expression is evaluated; it uses the @code{kill-append} -function to concatenate the text copied at this call to the function -with the text already in the first element (the @sc{car}) of the kill -ring. On the other hand, if the value of @code{last-command} is not -@code{kill-region}, then the @code{copy-region-as-kill} function -attaches a new element to the kill ring using the @code{kill-new} -function. - -@need 1250 -The @code{if} expression reads as follows; it uses @code{eq}: - -@smallexample -@group - (if (eq last-command 'kill-region) - ;; @r{then-part} - (kill-append (filter-buffer-substring beg end) (< end beg)) - ;; @r{else-part} - (kill-new (filter-buffer-substring beg end))) -@end group -@end smallexample - -@findex filter-buffer-substring -(The @code{filter-buffer-substring} function returns a filtered -substring of the buffer, if any. Optionally---the arguments are not -here, so neither is done---the function may delete the initial text or -return the text without its properties; this function is a replacement -for the older @code{buffer-substring} function, which came before text -properties were implemented.) - -@findex eq @r{(example of use)} -@noindent -The @code{eq} function tests whether its first argument is the same Lisp -object as its second argument. The @code{eq} function is similar to the -@code{equal} function in that it is used to test for equality, but -differs in that it determines whether two representations are actually -the same object inside the computer, but with different names. -@code{equal} determines whether the structure and contents of two -expressions are the same. - -If the previous command was @code{kill-region}, then the Emacs Lisp -interpreter calls the @code{kill-append} function - -@node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body -@unnumberedsubsubsec The @code{kill-append} function -@findex kill-append - -@need 800 -The @code{kill-append} function looks like this: - -@c in GNU Emacs 22 -@smallexample -@group -(defun kill-append (string before-p &optional yank-handler) - "Append STRING to the end of the latest kill in the kill ring. -If BEFORE-P is non-nil, prepend STRING to the kill. -@dots{} " - (let* ((cur (car kill-ring))) - (kill-new (if before-p (concat string cur) (concat cur string)) - (or (= (length cur) 0) - (equal yank-handler - (get-text-property 0 'yank-handler cur))) - yank-handler))) -@end group -@end smallexample - -@ignore -was: -(defun kill-append (string before-p) - "Append STRING to the end of the latest kill in the kill ring. -If BEFORE-P is non-nil, prepend STRING to the kill. -If `interprogram-cut-function' is set, pass the resulting kill to -it." - (kill-new (if before-p - (concat string (car kill-ring)) - (concat (car kill-ring) string)) - t)) -@end ignore - -@noindent -The @code{kill-append} function is fairly straightforward. It uses -the @code{kill-new} function, which we will discuss in more detail in -a moment. - -(Also, the function provides an optional argument called -@code{yank-handler}; when invoked, this argument tells the function -how to deal with properties added to the text, such as `bold' or -`italics'.) - -@c !!! bug in GNU Emacs 22 version of kill-append ? -It has a @code{let*} function to set the value of the first element of -the kill ring to @code{cur}. (I do not know why the function does not -use @code{let} instead; only one value is set in the expression. -Perhaps this is a bug that produces no problems?) - -Consider the conditional that is one of the two arguments to -@code{kill-new}. It uses @code{concat} to concatenate the new text to -the @sc{car} of the kill ring. Whether it prepends or appends the -text depends on the results of an @code{if} expression: - -@smallexample -@group -(if before-p ; @r{if-part} - (concat string cur) ; @r{then-part} - (concat cur string)) ; @r{else-part} -@end group -@end smallexample - -@noindent -If the region being killed is before the region that was killed in the -last command, then it should be prepended before the material that was -saved in the previous kill; and conversely, if the killed text follows -what was just killed, it should be appended after the previous text. -The @code{if} expression depends on the predicate @code{before-p} to -decide whether the newly saved text should be put before or after the -previously saved text. - -The symbol @code{before-p} is the name of one of the arguments to -@code{kill-append}. When the @code{kill-append} function is -evaluated, it is bound to the value returned by evaluating the actual -argument. In this case, this is the expression @code{(< end beg)}. -This expression does not directly determine whether the killed text in -this command is located before or after the kill text of the last -command; what it does is determine whether the value of the variable -@code{end} is less than the value of the variable @code{beg}. If it -is, it means that the user is most likely heading towards the -beginning of the buffer. Also, the result of evaluating the predicate -expression, @code{(< end beg)}, will be true and the text will be -prepended before the previous text. On the other hand, if the value of -the variable @code{end} is greater than the value of the variable -@code{beg}, the text will be appended after the previous text. - -@need 800 -When the newly saved text will be prepended, then the string with the new -text will be concatenated before the old text: - -@smallexample -(concat string cur) -@end smallexample - -@need 1200 -@noindent -But if the text will be appended, it will be concatenated -after the old text: - -@smallexample -(concat cur string)) -@end smallexample - -To understand how this works, we first need to review the -@code{concat} function. The @code{concat} function links together or -unites two strings of text. The result is a string. For example: - -@smallexample -@group -(concat "abc" "def") - @result{} "abcdef" -@end group - -@group -(concat "new " - (car '("first element" "second element"))) - @result{} "new first element" - -(concat (car - '("first element" "second element")) " modified") - @result{} "first element modified" -@end group -@end smallexample - -We can now make sense of @code{kill-append}: it modifies the contents -of the kill ring. The kill ring is a list, each element of which is -saved text. The @code{kill-append} function uses the @code{kill-new} -function which in turn uses the @code{setcar} function. - -@node kill-new function, , kill-append function, copy-region-as-kill body -@unnumberedsubsubsec The @code{kill-new} function -@findex kill-new - -@c in GNU Emacs 22, additional documentation to kill-new: -@ignore -Optional third arguments YANK-HANDLER controls how the STRING is later -inserted into a buffer; see `insert-for-yank' for details. -When a yank handler is specified, STRING must be non-empty (the yank -handler, if non-nil, is stored as a `yank-handler' text property on STRING). - -When the yank handler has a non-nil PARAM element, the original STRING -argument is not used by `insert-for-yank'. However, since Lisp code -may access and use elements from the kill ring directly, the STRING -argument should still be a \"useful\" string for such uses." -@end ignore -@need 1200 -The @code{kill-new} function looks like this: - -@smallexample -@group -(defun kill-new (string &optional replace yank-handler) - "Make STRING the latest kill in the kill ring. -Set `kill-ring-yank-pointer' to point to it. - -If `interprogram-cut-function' is non-nil, apply it to STRING. -Optional second argument REPLACE non-nil means that STRING will replace -the front of the kill ring, rather than being added to the list. -@dots{}" -@end group -@group - (if (> (length string) 0) - (if yank-handler - (put-text-property 0 (length string) - 'yank-handler yank-handler string)) - (if yank-handler - (signal 'args-out-of-range - (list string "yank-handler specified for empty string")))) -@end group -@group - (if (fboundp 'menu-bar-update-yank-menu) - (menu-bar-update-yank-menu string (and replace (car kill-ring)))) -@end group -@group - (if (and replace kill-ring) - (setcar kill-ring string) - (push string kill-ring) - (if (> (length kill-ring) kill-ring-max) - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) -@end group -@group - (setq kill-ring-yank-pointer kill-ring) - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end group -@end smallexample -@ignore -was: -(defun kill-new (string &optional replace) - "Make STRING the latest kill in the kill ring. -Set the kill-ring-yank pointer to point to it. -If `interprogram-cut-function' is non-nil, apply it to STRING. -Optional second argument REPLACE non-nil means that STRING will replace -the front of the kill ring, rather than being added to the list." - (and (fboundp 'menu-bar-update-yank-menu) - (menu-bar-update-yank-menu string (and replace (car kill-ring)))) - (if (and replace kill-ring) - (setcar kill-ring string) - (setq kill-ring (cons string kill-ring)) - (if (> (length kill-ring) kill-ring-max) - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) - (setq kill-ring-yank-pointer kill-ring) - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end ignore - -(Notice that the function is not interactive.) - -As usual, we can look at this function in parts. - -The function definition has an optional @code{yank-handler} argument, -which when invoked tells the function how to deal with properties -added to the text, such as `bold' or `italics'. We will skip that. - -@need 1200 -The first line of the documentation makes sense: - -@smallexample -Make STRING the latest kill in the kill ring. -@end smallexample - -@noindent -Let's skip over the rest of the documentation for the moment. - -@noindent -Also, let's skip over the initial @code{if} expression and those lines -of code involving @code{menu-bar-update-yank-menu}. We will explain -them below. - -@need 1200 -The critical lines are these: - -@smallexample -@group - (if (and replace kill-ring) - ;; @r{then} - (setcar kill-ring string) -@end group -@group - ;; @r{else} - (push string kill-ring) -@end group -@group - (setq kill-ring (cons string kill-ring)) - (if (> (length kill-ring) kill-ring-max) - ;; @r{avoid overly long kill ring} - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) -@end group -@group - (setq kill-ring-yank-pointer kill-ring) - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end group -@end smallexample - -The conditional test is @w{@code{(and replace kill-ring)}}. -This will be true when two conditions are met: the kill ring has -something in it, and the @code{replace} variable is true. - -@need 1250 -When the @code{kill-append} function sets @code{replace} to be true -and when the kill ring has at least one item in it, the @code{setcar} -expression is executed: - -@smallexample -(setcar kill-ring string) -@end smallexample - -The @code{setcar} function actually changes the first element of the -@code{kill-ring} list to the value of @code{string}. It replaces the -first element. - -@need 1250 -On the other hand, if the kill ring is empty, or replace is false, the -else-part of the condition is executed: - -@smallexample -(push string kill-ring) -@end smallexample - -@noindent -@need 1250 -@code{push} puts its first argument onto the second. It is similar to -the older - -@smallexample -(setq kill-ring (cons string kill-ring)) -@end smallexample - -@noindent -@need 1250 -or the newer - -@smallexample -(add-to-list kill-ring string) -@end smallexample - -@noindent -When it is false, the expression first constructs a new version of the -kill ring by prepending @code{string} to the existing kill ring as a -new element (that is what the @code{push} does). Then it executes a -second @code{if} clause. This second @code{if} clause keeps the kill -ring from growing too long. - -Let's look at these two expressions in order. - -The @code{push} line of the else-part sets the new value of the kill -ring to what results from adding the string being killed to the old -kill ring. - -We can see how this works with an example. - -@need 800 -First, - -@smallexample -(setq example-list '("here is a clause" "another clause")) -@end smallexample - -@need 1200 -@noindent -After evaluating this expression with @kbd{C-x C-e}, you can evaluate -@code{example-list} and see what it returns: - -@smallexample -@group -example-list - @result{} ("here is a clause" "another clause") -@end group -@end smallexample - -@need 1200 -@noindent -Now, we can add a new element on to this list by evaluating the -following expression: -@findex push, @r{example} - -@smallexample -(push "a third clause" example-list) -@end smallexample - -@need 800 -@noindent -When we evaluate @code{example-list}, we find its value is: - -@smallexample -@group -example-list - @result{} ("a third clause" "here is a clause" "another clause") -@end group -@end smallexample - -@noindent -Thus, the third clause is added to the list by @code{push}. - -@need 1200 -Now for the second part of the @code{if} clause. This expression -keeps the kill ring from growing too long. It looks like this: - -@smallexample -@group -(if (> (length kill-ring) kill-ring-max) - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)) -@end group -@end smallexample - -The code checks whether the length of the kill ring is greater than -the maximum permitted length. This is the value of -@code{kill-ring-max} (which is 60, by default). If the length of the -kill ring is too long, then this code sets the last element of the -kill ring to @code{nil}. It does this by using two functions, -@code{nthcdr} and @code{setcdr}. - -We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}). -It sets the @sc{cdr} of a list, just as @code{setcar} sets the -@sc{car} of a list. In this case, however, @code{setcdr} will not be -setting the @sc{cdr} of the whole kill ring; the @code{nthcdr} -function is used to cause it to set the @sc{cdr} of the next to last -element of the kill ring---this means that since the @sc{cdr} of the -next to last element is the last element of the kill ring, it will set -the last element of the kill ring. - -@findex nthcdr, @r{example} -The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a -list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr} -@dots{} It does this @var{N} times and returns the results. -(@xref{nthcdr, , @code{nthcdr}}.) - -@findex setcdr, @r{example} -Thus, if we had a four element list that was supposed to be three -elements long, we could set the @sc{cdr} of the next to last element -to @code{nil}, and thereby shorten the list. (If you set the last -element to some other value than @code{nil}, which you could do, then -you would not have shortened the list. @xref{setcdr, , -@code{setcdr}}.) - -You can see shortening by evaluating the following three expressions -in turn. First set the value of @code{trees} to @code{(maple oak pine -birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil} -and then find the value of @code{trees}: - -@smallexample -@group -(setq trees '(maple oak pine birch)) - @result{} (maple oak pine birch) -@end group - -@group -(setcdr (nthcdr 2 trees) nil) - @result{} nil - -trees - @result{} (maple oak pine) -@end group -@end smallexample - -@noindent -(The value returned by the @code{setcdr} expression is @code{nil} since -that is what the @sc{cdr} is set to.) - -To repeat, in @code{kill-new}, the @code{nthcdr} function takes the -@sc{cdr} a number of times that is one less than the maximum permitted -size of the kill ring and @code{setcdr} sets the @sc{cdr} of that -element (which will be the rest of the elements in the kill ring) to -@code{nil}. This prevents the kill ring from growing too long. - -@need 800 -The next to last expression in the @code{kill-new} function is - -@smallexample -(setq kill-ring-yank-pointer kill-ring) -@end smallexample - -The @code{kill-ring-yank-pointer} is a global variable that is set to be -the @code{kill-ring}. - -Even though the @code{kill-ring-yank-pointer} is called a -@samp{pointer}, it is a variable just like the kill ring. However, the -name has been chosen to help humans understand how the variable is used. - -@need 1200 -Now, to return to an early expression in the body of the function: - -@smallexample -@group - (if (fboundp 'menu-bar-update-yank-menu) - (menu-bar-update-yank-menu string (and replace (car kill-ring)))) -@end group -@end smallexample - -@noindent -It starts with an @code{if} expression - -In this case, the expression tests first to see whether -@code{menu-bar-update-yank-menu} exists as a function, and if so, -calls it. The @code{fboundp} function returns true if the symbol it -is testing has a function definition that `is not void'. If the -symbol's function definition were void, we would receive an error -message, as we did when we created errors intentionally (@pxref{Making -Errors, , Generate an Error Message}). - -@noindent -The then-part contains an expression whose first element is the -function @code{and}. - -@findex and -The @code{and} special form evaluates each of its arguments until one -of the arguments returns a value of @code{nil}, in which case the -@code{and} expression returns @code{nil}; however, if none of the -arguments returns a value of @code{nil}, the value resulting from -evaluating the last argument is returned. (Since such a value is not -@code{nil}, it is considered true in Emacs Lisp.) In other words, an -@code{and} expression returns a true value only if all its arguments -are true. (@xref{Second Buffer Related Review}.) - -The expression determines whether the second argument to -@code{menu-bar-update-yank-menu} is true or not. -@ignore - ;; If we're supposed to be extending an existing string, and that - ;; string really is at the front of the menu, then update it in place. -@end ignore - -@code{menu-bar-update-yank-menu} is one of the functions that make it -possible to use the `Select and Paste' menu in the Edit item of a menu -bar; using a mouse, you can look at the various pieces of text you -have saved and select one piece to paste. - -The last expression in the @code{kill-new} function adds the newly -copied string to whatever facility exists for copying and pasting -among different programs running in a windowing system. In the X -Windowing system, for example, the @code{x-select-text} function takes -the string and stores it in memory operated by X. You can paste the -string in another program, such as an Xterm. - -@need 1200 -The expression looks like this: - -@smallexample -@group - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end group -@end smallexample - -If an @code{interprogram-cut-function} exists, then Emacs executes -@code{funcall}, which in turn calls its first argument as a function -and passes the remaining arguments to it. (Incidentally, as far as I -can see, this @code{if} expression could be replaced by an @code{and} -expression similar to the one in the first part of the function.) - -We are not going to discuss windowing systems and other programs -further, but merely note that this is a mechanism that enables GNU -Emacs to work easily and well with other programs. - -This code for placing text in the kill ring, either concatenated with -an existing element or as a new element, leads us to the code for -bringing back text that has been cut out of the buffer---the yank -commands. However, before discussing the yank commands, it is better -to learn how lists are implemented in a computer. This will make -clear such mysteries as the use of the term `pointer'. But before -that, we will digress into C. - -@ignore -@c is this true in Emacs 22? Does not seems to be - - (If the @w{@code{(< end beg))}} -expression is true, @code{kill-append} prepends the string to the just -previously clipped text. For a detailed discussion, see -@ref{kill-append function, , The @code{kill-append} function}.) - -If you then yank back the text, i.e., `paste' it, you get both -pieces of text at once. That way, if you delete two words in a row, -and then yank them back, you get both words, in their proper order, -with one yank. (The @w{@code{(< end beg))}} expression makes sure the -order is correct.) - -On the other hand, if the previous command is not @code{kill-region}, -then the @code{kill-new} function is called, which adds the text to -the kill ring as the latest item, and sets the -@code{kill-ring-yank-pointer} variable to point to it. -@end ignore -@ignore - -@c Evidently, changed for Emacs 22. The zap-to-char command does not -@c use the delete-and-extract-region function - -2006 Oct 26, the Digression into C is now OK but should come after -copy-region-as-kill and filter-buffer-substring - -2006 Oct 24 -In Emacs 22, -copy-region-as-kill is short, 12 lines, and uses -filter-buffer-substring, which is longer, 39 lines -and has delete-and-extract-region in it. -delete-and-extract-region is written in C. - -see Initializing a Variable with @code{defvar} -@end ignore - -@node Digression into C, defvar, copy-region-as-kill, Cutting & Storing Text -@comment node-name, next, previous, up -@section Digression into C -@findex delete-and-extract-region -@cindex C, a digression into -@cindex Digression into C - -The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, , -@code{copy-region-as-kill}}) uses the @code{filter-buffer-substring} -function, which in turn uses the @code{delete-and-extract-region} -function. It removes the contents of a region and you cannot get them -back. - -Unlike the other code discussed here, the -@code{delete-and-extract-region} function is not written in Emacs -Lisp; it is written in C and is one of the primitives of the GNU Emacs -system. Since it is very simple, I will digress briefly from Lisp and -describe it here. - -@c GNU Emacs 22 in /usr/local/src/emacs/src/editfns.c -@c the DEFUN for buffer-substring-no-properties - -@need 1500 -Like many of the other Emacs primitives, -@code{delete-and-extract-region} is written as an instance of a C -macro, a macro being a template for code. The complete macro looks -like this: - -@smallexample -@group -DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties, - Sbuffer_substring_no_properties, 2, 2, 0, - doc: /* Return the characters of part of the buffer, -without the text properties. -The two arguments START and END are character positions; -they can be in either order. */) - (start, end) - Lisp_Object start, end; -@{ - register int b, e; - - validate_region (&start, &end); - b = XINT (start); - e = XINT (end); - - return make_buffer_string (b, e, 0); -@} -@end group -@end smallexample - -Without going into the details of the macro writing process, let me -point out that this macro starts with the word @code{DEFUN}. The word -@code{DEFUN} was chosen since the code serves the same purpose as -@code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in -@file{emacs/src/lisp.h}.) - -The word @code{DEFUN} is followed by seven parts inside of -parentheses: - -@itemize @bullet -@item -The first part is the name given to the function in Lisp, -@code{delete-and-extract-region}. - -@item -The second part is the name of the function in C, -@code{Fdelete_and_extract_region}. By convention, it starts with -@samp{F}. Since C does not use hyphens in names, underscores are used -instead. - -@item -The third part is the name for the C constant structure that records -information on this function for internal use. It is the name of the -function in C but begins with an @samp{S} instead of an @samp{F}. - -@item -The fourth and fifth parts specify the minimum and maximum number of -arguments the function can have. This function demands exactly 2 -arguments. - -@item -The sixth part is nearly like the argument that follows the -@code{interactive} declaration in a function written in Lisp: a letter -followed, perhaps, by a prompt. The only difference from the Lisp is -when the macro is called with no arguments. Then you write a @code{0} -(which is a `null string'), as in this macro. - -If you were to specify arguments, you would place them between -quotation marks. The C macro for @code{goto-char} includes -@code{"NGoto char: "} in this position to indicate that the function -expects a raw prefix, in this case, a numerical location in a buffer, -and provides a prompt. - -@item -The seventh part is a documentation string, just like the one for a -function written in Emacs Lisp, except that every newline must be -written explicitly as @samp{\n} followed by a backslash and carriage -return. - -@need 1000 -Thus, the first two lines of documentation for @code{goto-char} are -written like this: - -@smallexample -@group - "Set point to POSITION, a number or marker.\n\ -Beginning of buffer is position (point-min), end is (point-max)." -@end group -@end smallexample -@end itemize - -@need 1200 -In a C macro, the formal parameters come next, with a statement of -what kind of object they are, followed by what might be called the `body' -of the macro. For @code{delete-and-extract-region} the `body' -consists of the following four lines: - -@smallexample -@group -validate_region (&start, &end); -if (XINT (start) == XINT (end)) - return build_string (""); -return del_range_1 (XINT (start), XINT (end), 1, 1); -@end group -@end smallexample - -The @code{validate_region} function checks whether the values -passed as the beginning and end of the region are the proper type and -are within range. If the beginning and end positions are the same, -then return and empty string. - -The @code{del_range_1} function actually deletes the text. It is a -complex function we will not look into. It updates the buffer and -does other things. However, it is worth looking at the two arguments -passed to @code{del_range}. These are @w{@code{XINT (start)}} and -@w{@code{XINT (end)}}. - -As far as the C language is concerned, @code{start} and @code{end} are -two integers that mark the beginning and end of the region to be -deleted@footnote{More precisely, and requiring more expert knowledge -to understand, the two integers are of type `Lisp_Object', which can -also be a C union instead of an integer type.}. - -In early versions of Emacs, these two numbers were thirty-two bits -long, but the code is slowly being generalized to handle other -lengths. Three of the available bits are used to specify the type of -information; the remaining bits are used as `content'. - -@samp{XINT} is a C macro that extracts the relevant number from the -longer collection of bits; the three other bits are discarded. - -@need 800 -The command in @code{delete-and-extract-region} looks like this: - -@smallexample -del_range_1 (XINT (start), XINT (end), 1, 1); -@end smallexample - -@noindent -It deletes the region between the beginning position, @code{start}, -and the ending position, @code{end}. - -From the point of view of the person writing Lisp, Emacs is all very -simple; but hidden underneath is a great deal of complexity to make it -all work. - -@node defvar, cons & search-fwd Review, Digression into C, Cutting & Storing Text -@comment node-name, next, previous, up -@section Initializing a Variable with @code{defvar} -@findex defvar -@cindex Initializing a variable -@cindex Variable initialization - -@ignore -2006 Oct 24 -In Emacs 22, -copy-region-as-kill is short, 12 lines, and uses -filter-buffer-substring, which is longer, 39 lines -and has delete-and-extract-region in it. -delete-and-extract-region is written in C. - -see Initializing a Variable with @code{defvar} - -@end ignore - -The @code{copy-region-as-kill} function is written in Emacs Lisp. Two -functions within it, @code{kill-append} and @code{kill-new}, copy a -region in a buffer and save it in a variable called the -@code{kill-ring}. This section describes how the @code{kill-ring} -variable is created and initialized using the @code{defvar} special -form. - -(Again we note that the term @code{kill-ring} is a misnomer. The text -that is clipped out of the buffer can be brought back; it is not a ring -of corpses, but a ring of resurrectable text.) - -In Emacs Lisp, a variable such as the @code{kill-ring} is created and -given an initial value by using the @code{defvar} special form. The -name comes from ``define variable''. - -The @code{defvar} special form is similar to @code{setq} in that it sets -the value of a variable. It is unlike @code{setq} in two ways: first, -it only sets the value of the variable if the variable does not already -have a value. If the variable already has a value, @code{defvar} does -not override the existing value. Second, @code{defvar} has a -documentation string. - -(Another special form, @code{defcustom}, is designed for variables -that people customize. It has more features than @code{defvar}. -(@xref{defcustom, , Setting Variables with @code{defcustom}}.) - -@menu -* See variable current value:: -* defvar and asterisk:: -@end menu - -@node See variable current value, defvar and asterisk, defvar, defvar -@ifnottex -@unnumberedsubsec Seeing the Current Value of a Variable -@end ifnottex - -You can see the current value of a variable, any variable, by using -the @code{describe-variable} function, which is usually invoked by -typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring} -(followed by @key{RET}) when prompted, you will see what is in your -current kill ring---this may be quite a lot! Conversely, if you have -been doing nothing this Emacs session except read this document, you -may have nothing in it. Also, you will see the documentation for -@code{kill-ring}: - -@smallexample -@group -Documentation: -List of killed text sequences. -Since the kill ring is supposed to interact nicely with cut-and-paste -facilities offered by window systems, use of this variable should -@end group -@group -interact nicely with `interprogram-cut-function' and -`interprogram-paste-function'. The functions `kill-new', -`kill-append', and `current-kill' are supposed to implement this -interaction; you may want to use them instead of manipulating the kill -ring directly. -@end group -@end smallexample - -@need 800 -The kill ring is defined by a @code{defvar} in the following way: - -@smallexample -@group -(defvar kill-ring nil - "List of killed text sequences. -@dots{}") -@end group -@end smallexample - -@noindent -In this variable definition, the variable is given an initial value of -@code{nil}, which makes sense, since if you have saved nothing, you want -nothing back if you give a @code{yank} command. The documentation -string is written just like the documentation string of a @code{defun}. -As with the documentation string of the @code{defun}, the first line of -the documentation should be a complete sentence, since some commands, -like @code{apropos}, print only the first line of documentation. -Succeeding lines should not be indented; otherwise they look odd when -you use @kbd{C-h v} (@code{describe-variable}). - -@node defvar and asterisk, , See variable current value, defvar -@subsection @code{defvar} and an asterisk -@findex defvar @r{for a user customizable variable} -@findex defvar @r{with an asterisk} - -In the past, Emacs used the @code{defvar} special form both for -internal variables that you would not expect a user to change and for -variables that you do expect a user to change. Although you can still -use @code{defvar} for user customizable variables, please use -@code{defcustom} instead, since that special form provides a path into -the Customization commands. (@xref{defcustom, , Specifying Variables -using @code{defcustom}}.) - -When you specified a variable using the @code{defvar} special form, -you could distinguish a readily settable variable from others by -typing an asterisk, @samp{*}, in the first column of its documentation -string. For example: - -@smallexample -@group -(defvar shell-command-default-error-buffer nil - "*Buffer name for `shell-command' @dots{} error output. -@dots{} ") -@end group -@end smallexample - -@findex set-variable -@noindent -You could (and still can) use the @code{set-variable} command to -change the value of @code{shell-command-default-error-buffer} -temporarily. However, options set using @code{set-variable} are set -only for the duration of your editing session. The new values are not -saved between sessions. Each time Emacs starts, it reads the original -value, unless you change the value within your @file{.emacs} file, -either by setting it manually or by using @code{customize}. -@xref{Emacs Initialization, , Your @file{.emacs} File}. - -For me, the major use of the @code{set-variable} command is to suggest -variables that I might want to set in my @file{.emacs} file. There -are now more than 700 such variables --- far too many to remember -readily. Fortunately, you can press @key{TAB} after calling the -@code{M-x set-variable} command to see the list of variables. -(@xref{Examining, , Examining and Setting Variables, emacs, -The GNU Emacs Manual}.) - -@need 1250 -@node cons & search-fwd Review, search Exercises, defvar, Cutting & Storing Text -@comment node-name, next, previous, up -@section Review - -Here is a brief summary of some recently introduced functions. - -@table @code -@item car -@itemx cdr -@code{car} returns the first element of a list; @code{cdr} returns the -second and subsequent elements of a list. - -@need 1250 -For example: - -@smallexample -@group -(car '(1 2 3 4 5 6 7)) - @result{} 1 -(cdr '(1 2 3 4 5 6 7)) - @result{} (2 3 4 5 6 7) -@end group -@end smallexample - -@item cons -@code{cons} constructs a list by prepending its first argument to its -second argument. - -@need 1250 -For example: - -@smallexample -@group -(cons 1 '(2 3 4)) - @result{} (1 2 3 4) -@end group -@end smallexample - -@item funcall -@code{funcall} evaluates its first argument as a function. It passes -its remaining arguments to its first argument. - -@item nthcdr -Return the result of taking @sc{cdr} `n' times on a list. -@iftex -The -@tex -$n^{th}$ -@end tex -@code{cdr}. -@end iftex -The `rest of the rest', as it were. - -@need 1250 -For example: - -@smallexample -@group -(nthcdr 3 '(1 2 3 4 5 6 7)) - @result{} (4 5 6 7) -@end group -@end smallexample - -@item setcar -@itemx setcdr -@code{setcar} changes the first element of a list; @code{setcdr} -changes the second and subsequent elements of a list. - -@need 1250 -For example: - -@smallexample -@group -(setq triple '(1 2 3)) - -(setcar triple '37) - -triple - @result{} (37 2 3) - -(setcdr triple '("foo" "bar")) - -triple - @result{} (37 "foo" "bar") -@end group -@end smallexample - -@item progn -Evaluate each argument in sequence and then return the value of the -last. - -@need 1250 -For example: - -@smallexample -@group -(progn 1 2 3 4) - @result{} 4 -@end group -@end smallexample - -@item save-restriction -Record whatever narrowing is in effect in the current buffer, if any, -and restore that narrowing after evaluating the arguments. - -@item search-forward -Search for a string, and if the string is found, move point. With a -regular expression, use the similar @code{re-search-forward}. -(@xref{Regexp Search, , Regular Expression Searches}, for an -explanation of regular expression patterns and searches.) - -@need 1250 -@noindent -@code{search-forward} and @code{re-search-forward} take four -arguments: - -@enumerate -@item -The string or regular expression to search for. - -@item -Optionally, the limit of the search. - -@item -Optionally, what to do if the search fails, return @code{nil} or an -error message. - -@item -Optionally, how many times to repeat the search; if negative, the -search goes backwards. -@end enumerate - -@item kill-region -@itemx delete-and-extract-region -@itemx copy-region-as-kill - -@code{kill-region} cuts the text between point and mark from the -buffer and stores that text in the kill ring, so you can get it back -by yanking. - -@code{copy-region-as-kill} copies the text between point and mark into -the kill ring, from which you can get it by yanking. The function -does not cut or remove the text from the buffer. -@end table - -@code{delete-and-extract-region} removes the text between point and -mark from the buffer and throws it away. You cannot get it back. -(This is not an interactive command.) - -@need 1500 -@node search Exercises, , cons & search-fwd Review, Cutting & Storing Text -@section Searching Exercises - -@itemize @bullet -@item -Write an interactive function that searches for a string. If the -search finds the string, leave point after it and display a message -that says ``Found!''. (Do not use @code{search-forward} for the name -of this function; if you do, you will overwrite the existing version of -@code{search-forward} that comes with Emacs. Use a name such as -@code{test-search} instead.) - -@item -Write a function that prints the third element of the kill ring in the -echo area, if any; if the kill ring does not contain a third element, -print an appropriate message. -@end itemize - -@node List Implementation, Yanking, Cutting & Storing Text, Top -@comment node-name, next, previous, up -@chapter How Lists are Implemented -@cindex Lists in a computer - -In Lisp, atoms are recorded in a straightforward fashion; if the -implementation is not straightforward in practice, it is, nonetheless, -straightforward in theory. The atom @samp{rose}, for example, is -recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s}, -@samp{e}. A list, on the other hand, is kept differently. The mechanism -is equally simple, but it takes a moment to get used to the idea. A -list is kept using a series of pairs of pointers. In the series, the -first pointer in each pair points to an atom or to another list, and the -second pointer in each pair points to the next pair, or to the symbol -@code{nil}, which marks the end of the list. - -A pointer itself is quite simply the electronic address of what is -pointed to. Hence, a list is kept as a series of electronic addresses. - -@menu -* Lists diagrammed:: -* Symbols as Chest:: Exploring a powerful metaphor. -* List Exercise:: -@end menu - -@node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation -@ifnottex -@unnumberedsec Lists diagrammed -@end ifnottex - -For example, the list @code{(rose violet buttercup)} has three elements, -@samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the -electronic address of @samp{rose} is recorded in a segment of computer -memory along with the address that gives the electronic address of where -the atom @samp{violet} is located; and that address (the one that tells -where @samp{violet} is located) is kept along with an address that tells -where the address for the atom @samp{buttercup} is located. - -@need 1200 -This sounds more complicated than it is and is easier seen in a diagram: - -@c clear print-postscript-figures -@c !!! cons-cell-diagram #1 -@ifnottex -@smallexample -@group - ___ ___ ___ ___ ___ ___ - |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-1} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group - ___ ___ ___ ___ ___ ___ - |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -In the diagram, each box represents a word of computer memory that -holds a Lisp object, usually in the form of a memory address. The boxes, -i.e.@: the addresses, are in pairs. Each arrow points to what the address -is the address of, either an atom or another pair of addresses. The -first box is the electronic address of @samp{rose} and the arrow points -to @samp{rose}; the second box is the address of the next pair of boxes, -the first part of which is the address of @samp{violet} and the second -part of which is the address of the next pair. The very last box -points to the symbol @code{nil}, which marks the end of the list. - -@need 1200 -When a variable is set to a list with a function such as @code{setq}, -it stores the address of the first box in the variable. Thus, -evaluation of the expression - -@smallexample -(setq bouquet '(rose violet buttercup)) -@end smallexample - -@need 1250 -@noindent -creates a situation like this: - -@c cons-cell-diagram #2 -@ifnottex -@smallexample -@group -bouquet - | - | ___ ___ ___ ___ ___ ___ - --> |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-2} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -bouquet - | - | ___ ___ ___ ___ ___ ___ - --> |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -In this example, the symbol @code{bouquet} holds the address of the first -pair of boxes. - -@need 1200 -This same list can be illustrated in a different sort of box notation -like this: - -@c cons-cell-diagram #2a -@ifnottex -@smallexample -@group -bouquet - | - | -------------- --------------- ---------------- - | | car | cdr | | car | cdr | | car | cdr | - -->| rose | o------->| violet | o------->| butter- | nil | - | | | | | | | cup | | - -------------- --------------- ---------------- -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-2a} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -bouquet - | - | -------------- --------------- ---------------- - | | car | cdr | | car | cdr | | car | cdr | - -->| rose | o------->| violet | o------->| butter- | nil | - | | | | | | | cup | | - -------------- --------------- ---------------- -@end group -@end smallexample -@end iftex -@end ifclear - -(Symbols consist of more than pairs of addresses, but the structure of -a symbol is made up of addresses. Indeed, the symbol @code{bouquet} -consists of a group of address-boxes, one of which is the address of -the printed word @samp{bouquet}, a second of which is the address of a -function definition attached to the symbol, if any, a third of which -is the address of the first pair of address-boxes for the list -@code{(rose violet buttercup)}, and so on. Here we are showing that -the symbol's third address-box points to the first pair of -address-boxes for the list.) - -If a symbol is set to the @sc{cdr} of a list, the list itself is not -changed; the symbol simply has an address further down the list. (In -the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus, -evaluation of the following expression - -@smallexample -(setq flowers (cdr bouquet)) -@end smallexample - -@need 800 -@noindent -produces this: - -@c cons-cell-diagram #3 -@ifnottex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ | ___ ___ ___ ___ - --> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-3} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ | ___ ___ ___ ___ - --> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -@noindent -The value of @code{flowers} is @code{(violet buttercup)}, which is -to say, the symbol @code{flowers} holds the address of the pair of -address-boxes, the first of which holds the address of @code{violet}, -and the second of which holds the address of @code{buttercup}. - -A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted -pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp -Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair -Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more -information about cons cells and dotted pairs. - -@need 1200 -The function @code{cons} adds a new pair of addresses to the front of -a series of addresses like that shown above. For example, evaluating -the expression - -@smallexample -(setq bouquet (cons 'lily bouquet)) -@end smallexample - -@need 1500 -@noindent -produces: - -@c cons-cell-diagram #4 -@ifnottex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ ___ ___ | ___ ___ ___ ___ - --> | | | | | | --> | | | | | | - |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil - | | | | - | | | | - --> lily --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-4} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ ___ ___ | ___ ___ ___ ___ - --> | | | | | | --> | | | | | | - |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil - | | | | - | | | | - --> lily --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -@need 1200 -@noindent -However, this does not change the value of the symbol -@code{flowers}, as you can see by evaluating the following, - -@smallexample -(eq (cdr (cdr bouquet)) flowers) -@end smallexample - -@noindent -which returns @code{t} for true. - -Until it is reset, @code{flowers} still has the value -@code{(violet buttercup)}; that is, it has the address of the cons -cell whose first address is of @code{violet}. Also, this does not -alter any of the pre-existing cons cells; they are all still there. - -Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address -of the next cons cell in the series; to get the @sc{car} of a list, -you get the address of the first element of the list; to @code{cons} a -new element on a list, you add a new cons cell to the front of the list. -That is all there is to it! The underlying structure of Lisp is -brilliantly simple! - -And what does the last address in a series of cons cells refer to? It -is the address of the empty list, of @code{nil}. - -In summary, when a Lisp variable is set to a value, it is provided with -the address of the list to which the variable refers. - -@node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation -@section Symbols as a Chest of Drawers -@cindex Symbols as a Chest of Drawers -@cindex Chest of Drawers, metaphor for a symbol -@cindex Drawers, Chest of, metaphor for a symbol - -In an earlier section, I suggested that you might imagine a symbol as -being a chest of drawers. The function definition is put in one -drawer, the value in another, and so on. What is put in the drawer -holding the value can be changed without affecting the contents of the -drawer holding the function definition, and vice-verse. - -Actually, what is put in each drawer is the address of the value or -function definition. It is as if you found an old chest in the attic, -and in one of its drawers you found a map giving you directions to -where the buried treasure lies. - -(In addition to its name, symbol definition, and variable value, a -symbol has a `drawer' for a @dfn{property list} which can be used to -record other information. Property lists are not discussed here; see -@ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp -Reference Manual}.) - -@need 1500 -Here is a fanciful representation: - -@c chest-of-drawers diagram -@ifnottex -@sp 1 -@smallexample -@group - Chest of Drawers Contents of Drawers - - __ o0O0o __ - / \ - --------------------- - | directions to | [map to] - | symbol name | bouquet - | | - +---------------------+ - | directions to | - | symbol definition | [none] - | | - +---------------------+ - | directions to | [map to] - | variable value | (rose violet buttercup) - | | - +---------------------+ - | directions to | - | property list | [not described here] - | | - +---------------------+ - |/ \| -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{drawers} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@sp 1 -@smallexample -@group - Chest of Drawers Contents of Drawers - - __ o0O0o __ - / \ - --------------------- - | directions to | [map to] - | symbol name | bouquet - | | - +---------------------+ - | directions to | - | symbol definition | [none] - | | - +---------------------+ - | directions to | [map to] - | variable value | (rose violet buttercup) - | | - +---------------------+ - | directions to | - | property list | [not described here] - | | - +---------------------+ - |/ \| -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -@node List Exercise, , Symbols as Chest, List Implementation -@section Exercise - -Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two -more flowers on to this list and set this new list to -@code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish. -What does the @code{more-flowers} list now contain? - -@node Yanking, Loops & Recursion, List Implementation, Top -@comment node-name, next, previous, up -@chapter Yanking Text Back -@findex yank -@cindex Text retrieval -@cindex Retrieving text -@cindex Pasting text - -Whenever you cut text out of a buffer with a `kill' command in GNU Emacs, -you can bring it back with a `yank' command. The text that is cut out of -the buffer is put in the kill ring and the yank commands insert the -appropriate contents of the kill ring back into a buffer (not necessarily -the original buffer). - -A simple @kbd{C-y} (@code{yank}) command inserts the first item from -the kill ring into the current buffer. If the @kbd{C-y} command is -followed immediately by @kbd{M-y}, the first element is replaced by -the second element. Successive @kbd{M-y} commands replace the second -element with the third, fourth, or fifth element, and so on. When the -last element in the kill ring is reached, it is replaced by the first -element and the cycle is repeated. (Thus the kill ring is called a -`ring' rather than just a `list'. However, the actual data structure -that holds the text is a list. -@xref{Kill Ring, , Handling the Kill Ring}, for the details of how the -list is handled as a ring.) - -@menu -* Kill Ring Overview:: -* kill-ring-yank-pointer:: The kill ring is a list. -* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. -@end menu - -@node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking -@comment node-name, next, previous, up -@section Kill Ring Overview -@cindex Kill ring overview - -The kill ring is a list of textual strings. This is what it looks like: - -@smallexample -("some text" "a different piece of text" "yet more text") -@end smallexample - -If this were the contents of my kill ring and I pressed @kbd{C-y}, the -string of characters saying @samp{some text} would be inserted in this -buffer where my cursor is located. - -The @code{yank} command is also used for duplicating text by copying it. -The copied text is not cut from the buffer, but a copy of it is put on the -kill ring and is inserted by yanking it back. - -Three functions are used for bringing text back from the kill ring: -@code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop}, -which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer}, -which is used by the two other functions. - -These functions refer to the kill ring through a variable called the -@code{kill-ring-yank-pointer}. Indeed, the insertion code for both the -@code{yank} and @code{yank-pop} functions is: - -@smallexample -(insert (car kill-ring-yank-pointer)) -@end smallexample - -@noindent -(Well, no more. In GNU Emacs 22, the function has been replaced by -@code{insert-for-yank} which calls @code{insert-for-yank-1} -repetitively for each @code{yank-handler} segment. In turn, -@code{insert-for-yank-1} strips text properties from the inserted text -according to @code{yank-excluded-properties}. Otherwise, it is just -like @code{insert}. We will stick with plain @code{insert} since it -is easier to understand.) - -To begin to understand how @code{yank} and @code{yank-pop} work, it is -first necessary to look at the @code{kill-ring-yank-pointer} variable. - -@node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking -@comment node-name, next, previous, up -@section The @code{kill-ring-yank-pointer} Variable - -@code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is -a variable. It points to something by being bound to the value of what -it points to, like any other Lisp variable. - -@need 1000 -Thus, if the value of the kill ring is: - -@smallexample -("some text" "a different piece of text" "yet more text") -@end smallexample - -@need 1250 -@noindent -and the @code{kill-ring-yank-pointer} points to the second clause, the -value of @code{kill-ring-yank-pointer} is: - -@smallexample -("a different piece of text" "yet more text") -@end smallexample - -As explained in the previous chapter (@pxref{List Implementation}), the -computer does not keep two different copies of the text being pointed to -by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The -words ``a different piece of text'' and ``yet more text'' are not -duplicated. Instead, the two Lisp variables point to the same pieces of -text. Here is a diagram: - -@c cons-cell-diagram #5 -@ifnottex -@smallexample -@group -kill-ring kill-ring-yank-pointer - | | - | ___ ___ | ___ ___ ___ ___ - ---> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - | | --> "yet more text" - | | - | --> "a different piece of text" - | - --> "some text" -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-5} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -kill-ring kill-ring-yank-pointer - | | - | ___ ___ | ___ ___ ___ ___ - ---> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - | | --> "yet more text" - | | - | --> "a different piece of text - | - --> "some text" -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -Both the variable @code{kill-ring} and the variable -@code{kill-ring-yank-pointer} are pointers. But the kill ring itself is -usually described as if it were actually what it is composed of. The -@code{kill-ring} is spoken of as if it were the list rather than that it -points to the list. Conversely, the @code{kill-ring-yank-pointer} is -spoken of as pointing to a list. - -These two ways of talking about the same thing sound confusing at first but -make sense on reflection. The kill ring is generally thought of as the -complete structure of data that holds the information of what has recently -been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer} -on the other hand, serves to indicate---that is, to `point to'---that part -of the kill ring of which the first element (the @sc{car}) will be -inserted. - -@ignore -In GNU Emacs 22, the @code{kill-new} function calls - -@code{(setq kill-ring-yank-pointer kill-ring)} - -(defun rotate-yank-pointer (arg) - "Rotate the yanking point in the kill ring. -With argument, rotate that many kills forward (or backward, if negative)." - (interactive "p") - (current-kill arg)) - -(defun current-kill (n &optional do-not-move) - "Rotate the yanking point by N places, and then return that kill. -If N is zero, `interprogram-paste-function' is set, and calling it -returns a string, then that string is added to the front of the -kill ring and returned as the latest kill. -If optional arg DO-NOT-MOVE is non-nil, then don't actually move the -yanking point; just return the Nth kill forward." - (let ((interprogram-paste (and (= n 0) - interprogram-paste-function - (funcall interprogram-paste-function)))) - (if interprogram-paste - (progn - ;; Disable the interprogram cut function when we add the new - ;; text to the kill ring, so Emacs doesn't try to own the - ;; selection, with identical text. - (let ((interprogram-cut-function nil)) - (kill-new interprogram-paste)) - interprogram-paste) - (or kill-ring (error "Kill ring is empty")) - (let ((ARGth-kill-element - (nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) - (car ARGth-kill-element))))) - -@end ignore - -@need 1500 -@node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking -@section Exercises with @code{yank} and @code{nthcdr} - -@itemize @bullet -@item -Using @kbd{C-h v} (@code{describe-variable}), look at the value of -your kill ring. Add several items to your kill ring; look at its -value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way -around the kill ring. How many items were in your kill ring? Find -the value of @code{kill-ring-max}. Was your kill ring full, or could -you have kept more blocks of text within it? - -@item -Using @code{nthcdr} and @code{car}, construct a series of expressions -to return the first, second, third, and fourth elements of a list. -@end itemize - -@node Loops & Recursion, Regexp Search, Yanking, Top -@comment node-name, next, previous, up -@chapter Loops and Recursion -@cindex Loops and recursion -@cindex Recursion and loops -@cindex Repetition (loops) - -Emacs Lisp has two primary ways to cause an expression, or a series of -expressions, to be evaluated repeatedly: one uses a @code{while} -loop, and the other uses @dfn{recursion}. - -Repetition can be very valuable. For example, to move forward four -sentences, you need only write a program that will move forward one -sentence and then repeat the process four times. Since a computer does -not get bored or tired, such repetitive action does not have the -deleterious effects that excessive or the wrong kinds of repetition can -have on humans. - -People mostly write Emacs Lisp functions using @code{while} loops and -their kin; but you can use recursion, which provides a very powerful -way to think about and then to solve problems@footnote{You can write -recursive functions to be frugal or wasteful of mental or computer -resources; as it happens, methods that people find easy---that are -frugal of `mental resources'---sometimes use considerable computer -resources. Emacs was designed to run on machines that we now consider -limited and its default settings are conservative. You may want to -increase the values of @code{max-specpdl-size} and -@code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to -15 and 30 times their default value.}. - -@menu -* while:: Causing a stretch of code to repeat. -* dolist dotimes:: -* Recursion:: Causing a function to call itself. -* Looping exercise:: -@end menu - -@node while, dolist dotimes, Loops & Recursion, Loops & Recursion -@comment node-name, next, previous, up -@section @code{while} -@cindex Loops -@findex while - -The @code{while} special form tests whether the value returned by -evaluating its first argument is true or false. This is similar to what -the Lisp interpreter does with an @code{if}; what the interpreter does -next, however, is different. - -In a @code{while} expression, if the value returned by evaluating the -first argument is false, the Lisp interpreter skips the rest of the -expression (the @dfn{body} of the expression) and does not evaluate it. -However, if the value is true, the Lisp interpreter evaluates the body -of the expression and then again tests whether the first argument to -@code{while} is true or false. If the value returned by evaluating the -first argument is again true, the Lisp interpreter again evaluates the -body of the expression. - -@need 1200 -The template for a @code{while} expression looks like this: - -@smallexample -@group -(while @var{true-or-false-test} - @var{body}@dots{}) -@end group -@end smallexample - -@menu -* Looping with while:: Repeat so long as test returns true. -* Loop Example:: A @code{while} loop that uses a list. -* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. -* Incrementing Loop:: A loop with an incrementing counter. -* Incrementing Loop Details:: -* Decrementing Loop:: A loop with a decrementing counter. -@end menu - -@node Looping with while, Loop Example, while, while -@ifnottex -@unnumberedsubsec Looping with @code{while} -@end ifnottex - -So long as the true-or-false-test of the @code{while} expression -returns a true value when it is evaluated, the body is repeatedly -evaluated. This process is called a loop since the Lisp interpreter -repeats the same thing again and again, like an airplane doing a loop. -When the result of evaluating the true-or-false-test is false, the -Lisp interpreter does not evaluate the rest of the @code{while} -expression and `exits the loop'. - -Clearly, if the value returned by evaluating the first argument to -@code{while} is always true, the body following will be evaluated -again and again @dots{} and again @dots{} forever. Conversely, if the -value returned is never true, the expressions in the body will never -be evaluated. The craft of writing a @code{while} loop consists of -choosing a mechanism such that the true-or-false-test returns true -just the number of times that you want the subsequent expressions to -be evaluated, and then have the test return false. - -The value returned by evaluating a @code{while} is the value of the -true-or-false-test. An interesting consequence of this is that a -@code{while} loop that evaluates without error will return @code{nil} -or false regardless of whether it has looped 1 or 100 times or none at -all. A @code{while} expression that evaluates successfully never -returns a true value! What this means is that @code{while} is always -evaluated for its side effects, which is to say, the consequences of -evaluating the expressions within the body of the @code{while} loop. -This makes sense. It is not the mere act of looping that is desired, -but the consequences of what happens when the expressions in the loop -are repeatedly evaluated. - -@node Loop Example, print-elements-of-list, Looping with while, while -@comment node-name, next, previous, up -@subsection A @code{while} Loop and a List - -A common way to control a @code{while} loop is to test whether a list -has any elements. If it does, the loop is repeated; but if it does not, -the repetition is ended. Since this is an important technique, we will -create a short example to illustrate it. - -A simple way to test whether a list has elements is to evaluate the -list: if it has no elements, it is an empty list and will return the -empty list, @code{()}, which is a synonym for @code{nil} or false. On -the other hand, a list with elements will return those elements when it -is evaluated. Since Emacs Lisp considers as true any value that is not -@code{nil}, a list that returns elements will test true in a -@code{while} loop. - -@need 1200 -For example, you can set the variable @code{empty-list} to @code{nil} by -evaluating the following @code{setq} expression: - -@smallexample -(setq empty-list ()) -@end smallexample - -@noindent -After evaluating the @code{setq} expression, you can evaluate the -variable @code{empty-list} in the usual way, by placing the cursor after -the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your -echo area: - -@smallexample -empty-list -@end smallexample - -On the other hand, if you set a variable to be a list with elements, the -list will appear when you evaluate the variable, as you can see by -evaluating the following two expressions: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -animals -@end group -@end smallexample - -Thus, to create a @code{while} loop that tests whether there are any -items in the list @code{animals}, the first part of the loop will be -written like this: - -@smallexample -@group -(while animals - @dots{} -@end group -@end smallexample - -@noindent -When the @code{while} tests its first argument, the variable -@code{animals} is evaluated. It returns a list. So long as the list -has elements, the @code{while} considers the results of the test to be -true; but when the list is empty, it considers the results of the test -to be false. - -To prevent the @code{while} loop from running forever, some mechanism -needs to be provided to empty the list eventually. An oft-used -technique is to have one of the subsequent forms in the @code{while} -expression set the value of the list to be the @sc{cdr} of the list. -Each time the @code{cdr} function is evaluated, the list will be made -shorter, until eventually only the empty list will be left. At this -point, the test of the @code{while} loop will return false, and the -arguments to the @code{while} will no longer be evaluated. - -For example, the list of animals bound to the variable @code{animals} -can be set to be the @sc{cdr} of the original list with the -following expression: - -@smallexample -(setq animals (cdr animals)) -@end smallexample - -@noindent -If you have evaluated the previous expressions and then evaluate this -expression, you will see @code{(giraffe lion tiger)} appear in the echo -area. If you evaluate the expression again, @code{(lion tiger)} will -appear in the echo area. If you evaluate it again and yet again, -@code{(tiger)} appears and then the empty list, shown by @code{nil}. - -A template for a @code{while} loop that uses the @code{cdr} function -repeatedly to cause the true-or-false-test eventually to test false -looks like this: - -@smallexample -@group -(while @var{test-whether-list-is-empty} - @var{body}@dots{} - @var{set-list-to-cdr-of-list}) -@end group -@end smallexample - -This test and use of @code{cdr} can be put together in a function that -goes through a list and prints each element of the list on a line of its -own. - -@node print-elements-of-list, Incrementing Loop, Loop Example, while -@subsection An Example: @code{print-elements-of-list} -@findex print-elements-of-list - -The @code{print-elements-of-list} function illustrates a @code{while} -loop with a list. - -@cindex @file{*scratch*} buffer -The function requires several lines for its output. If you are -reading this in a recent instance of GNU Emacs, -@c GNU Emacs 21, GNU Emacs 22, or a later version, -you can evaluate the following expression inside of Info, as usual. - -If you are using an earlier version of Emacs, you need to copy the -necessary expressions to your @file{*scratch*} buffer and evaluate -them there. This is because the echo area had only one line in the -earlier versions. - -You can copy the expressions by marking the beginning of the region -with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to -the end of the region and then copying the region using @kbd{M-w} -(@code{kill-ring-save}, which calls @code{copy-region-as-kill} and -then provides visual feedback). In the @file{*scratch*} -buffer, you can yank the expressions back by typing @kbd{C-y} -(@code{yank}). - -After you have copied the expressions to the @file{*scratch*} buffer, -evaluate each expression in turn. Be sure to evaluate the last -expression, @code{(print-elements-of-list animals)}, by typing -@kbd{C-u C-x C-e}, that is, by giving an argument to -@code{eval-last-sexp}. This will cause the result of the evaluation -to be printed in the @file{*scratch*} buffer instead of being printed -in the echo area. (Otherwise you will see something like this in your -echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which -each @samp{^J} stands for a `newline'.) - -@need 1500 -In a recent instance of GNU Emacs, you can evaluate these expressions -directly in the Info buffer, and the echo area will grow to show the -results. - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun print-elements-of-list (list) - "Print each element of LIST on a line of its own." - (while list - (print (car list)) - (setq list (cdr list)))) - -(print-elements-of-list animals) -@end group -@end smallexample - -@need 1200 -@noindent -When you evaluate the three expressions in sequence, you will see -this: - -@smallexample -@group -gazelle - -giraffe - -lion - -tiger -nil -@end group -@end smallexample - -Each element of the list is printed on a line of its own (that is what -the function @code{print} does) and then the value returned by the -function is printed. Since the last expression in the function is the -@code{while} loop, and since @code{while} loops always return -@code{nil}, a @code{nil} is printed after the last element of the list. - -@node Incrementing Loop, Incrementing Loop Details, print-elements-of-list, while -@comment node-name, next, previous, up -@subsection A Loop with an Incrementing Counter - -A loop is not useful unless it stops when it ought. Besides -controlling a loop with a list, a common way of stopping a loop is to -write the first argument as a test that returns false when the correct -number of repetitions are complete. This means that the loop must -have a counter---an expression that counts how many times the loop -repeats itself. - -@node Incrementing Loop Details, Decrementing Loop, Incrementing Loop, while -@ifnottex -@unnumberedsubsec Details of an Incrementing Loop -@end ifnottex - -The test for a loop with an incrementing counter can be an expression -such as @code{(< count desired-number)} which returns @code{t} for -true if the value of @code{count} is less than the -@code{desired-number} of repetitions and @code{nil} for false if the -value of @code{count} is equal to or is greater than the -@code{desired-number}. The expression that increments the count can -be a simple @code{setq} such as @code{(setq count (1+ count))}, where -@code{1+} is a built-in function in Emacs Lisp that adds 1 to its -argument. (The expression @w{@code{(1+ count)}} has the same result -as @w{@code{(+ count 1)}}, but is easier for a human to read.) - -@need 1250 -The template for a @code{while} loop controlled by an incrementing -counter looks like this: - -@smallexample -@group -@var{set-count-to-initial-value} -(while (< count desired-number) ; @r{true-or-false-test} - @var{body}@dots{} - (setq count (1+ count))) ; @r{incrementer} -@end group -@end smallexample - -@noindent -Note that you need to set the initial value of @code{count}; usually it -is set to 1. - -@menu -* Incrementing Example:: Counting pebbles in a triangle. -* Inc Example parts:: The parts of the function definition. -* Inc Example altogether:: Putting the function definition together. -@end menu - -@node Incrementing Example, Inc Example parts, Incrementing Loop Details, Incrementing Loop Details -@unnumberedsubsubsec Example with incrementing counter - -Suppose you are playing on the beach and decide to make a triangle of -pebbles, putting one pebble in the first row, two in the second row, -three in the third row and so on, like this: - -@sp 1 -@c pebble diagram -@ifnottex -@smallexample -@group - * - * * - * * * - * * * * -@end group -@end smallexample -@end ifnottex -@iftex -@smallexample -@group - @bullet{} - @bullet{} @bullet{} - @bullet{} @bullet{} @bullet{} - @bullet{} @bullet{} @bullet{} @bullet{} -@end group -@end smallexample -@end iftex -@sp 1 - -@noindent -(About 2500 years ago, Pythagoras and others developed the beginnings of -number theory by considering questions such as this.) - -Suppose you want to know how many pebbles you will need to make a -triangle with 7 rows? - -Clearly, what you need to do is add up the numbers from 1 to 7. There -are two ways to do this; start with the smallest number, one, and add up -the list in sequence, 1, 2, 3, 4 and so on; or start with the largest -number and add the list going down: 7, 6, 5, 4 and so on. Because both -mechanisms illustrate common ways of writing @code{while} loops, we will -create two examples, one counting up and the other counting down. In -this first example, we will start with 1 and add 2, 3, 4 and so on. - -If you are just adding up a short list of numbers, the easiest way to do -it is to add up all the numbers at once. However, if you do not know -ahead of time how many numbers your list will have, or if you want to be -prepared for a very long list, then you need to design your addition so -that what you do is repeat a simple process many times instead of doing -a more complex process once. - -For example, instead of adding up all the pebbles all at once, what you -can do is add the number of pebbles in the first row, 1, to the number -in the second row, 2, and then add the total of those two rows to the -third row, 3. Then you can add the number in the fourth row, 4, to the -total of the first three rows; and so on. - -The critical characteristic of the process is that each repetitive -action is simple. In this case, at each step we add only two numbers, -the number of pebbles in the row and the total already found. This -process of adding two numbers is repeated again and again until the last -row has been added to the total of all the preceding rows. In a more -complex loop the repetitive action might not be so simple, but it will -be simpler than doing everything all at once. - -@node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop Details -@unnumberedsubsubsec The parts of the function definition - -The preceding analysis gives us the bones of our function definition: -first, we will need a variable that we can call @code{total} that will -be the total number of pebbles. This will be the value returned by -the function. - -Second, we know that the function will require an argument: this -argument will be the total number of rows in the triangle. It can be -called @code{number-of-rows}. - -Finally, we need a variable to use as a counter. We could call this -variable @code{counter}, but a better name is @code{row-number}. That -is because what the counter does in this function is count rows, and a -program should be written to be as understandable as possible. - -When the Lisp interpreter first starts evaluating the expressions in the -function, the value of @code{total} should be set to zero, since we have -not added anything to it. Then the function should add the number of -pebbles in the first row to the total, and then add the number of -pebbles in the second to the total, and then add the number of -pebbles in the third row to the total, and so on, until there are no -more rows left to add. - -Both @code{total} and @code{row-number} are used only inside the -function, so they can be declared as local variables with @code{let} -and given initial values. Clearly, the initial value for @code{total} -should be 0. The initial value of @code{row-number} should be 1, -since we start with the first row. This means that the @code{let} -statement will look like this: - -@smallexample -@group - (let ((total 0) - (row-number 1)) - @var{body}@dots{}) -@end group -@end smallexample - -After the internal variables are declared and bound to their initial -values, we can begin the @code{while} loop. The expression that serves -as the test should return a value of @code{t} for true so long as the -@code{row-number} is less than or equal to the @code{number-of-rows}. -(If the expression tests true only so long as the row number is less -than the number of rows in the triangle, the last row will never be -added to the total; hence the row number has to be either less than or -equal to the number of rows.) - -@need 1500 -@findex <= @r{(less than or equal)} -Lisp provides the @code{<=} function that returns true if the value of -its first argument is less than or equal to the value of its second -argument and false otherwise. So the expression that the @code{while} -will evaluate as its test should look like this: - -@smallexample -(<= row-number number-of-rows) -@end smallexample - -The total number of pebbles can be found by repeatedly adding the number -of pebbles in a row to the total already found. Since the number of -pebbles in the row is equal to the row number, the total can be found by -adding the row number to the total. (Clearly, in a more complex -situation, the number of pebbles in the row might be related to the row -number in a more complicated way; if this were the case, the row number -would be replaced by the appropriate expression.) - -@smallexample -(setq total (+ total row-number)) -@end smallexample - -@noindent -What this does is set the new value of @code{total} to be equal to the -sum of adding the number of pebbles in the row to the previous total. - -After setting the value of @code{total}, the conditions need to be -established for the next repetition of the loop, if there is one. This -is done by incrementing the value of the @code{row-number} variable, -which serves as a counter. After the @code{row-number} variable has -been incremented, the true-or-false-test at the beginning of the -@code{while} loop tests whether its value is still less than or equal to -the value of the @code{number-of-rows} and if it is, adds the new value -of the @code{row-number} variable to the @code{total} of the previous -repetition of the loop. - -@need 1200 -The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the -@code{row-number} variable can be incremented with this expression: - -@smallexample -(setq row-number (1+ row-number)) -@end smallexample - -@node Inc Example altogether, , Inc Example parts, Incrementing Loop Details -@unnumberedsubsubsec Putting the function definition together - -We have created the parts for the function definition; now we need to -put them together. - -@need 800 -First, the contents of the @code{while} expression: - -@smallexample -@group -(while (<= row-number number-of-rows) ; @r{true-or-false-test} - (setq total (+ total row-number)) - (setq row-number (1+ row-number))) ; @r{incrementer} -@end group -@end smallexample - -Along with the @code{let} expression varlist, this very nearly -completes the body of the function definition. However, it requires -one final element, the need for which is somewhat subtle. - -The final touch is to place the variable @code{total} on a line by -itself after the @code{while} expression. Otherwise, the value returned -by the whole function is the value of the last expression that is -evaluated in the body of the @code{let}, and this is the value -returned by the @code{while}, which is always @code{nil}. - -This may not be evident at first sight. It almost looks as if the -incrementing expression is the last expression of the whole function. -But that expression is part of the body of the @code{while}; it is the -last element of the list that starts with the symbol @code{while}. -Moreover, the whole of the @code{while} loop is a list within the body -of the @code{let}. - -@need 1250 -In outline, the function will look like this: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (let (@var{varlist}) - (while (@var{true-or-false-test}) - @var{body-of-while}@dots{} ) - @dots{} )) ; @r{Need final expression here.} -@end group -@end smallexample - -The result of evaluating the @code{let} is what is going to be returned -by the @code{defun} since the @code{let} is not embedded within any -containing list, except for the @code{defun} as a whole. However, if -the @code{while} is the last element of the @code{let} expression, the -function will always return @code{nil}. This is not what we want! -Instead, what we want is the value of the variable @code{total}. This -is returned by simply placing the symbol as the last element of the list -starting with @code{let}. It gets evaluated after the preceding -elements of the list are evaluated, which means it gets evaluated after -it has been assigned the correct value for the total. - -It may be easier to see this by printing the list starting with -@code{let} all on one line. This format makes it evident that the -@var{varlist} and @code{while} expressions are the second and third -elements of the list starting with @code{let}, and the @code{total} is -the last element: - -@smallexample -@group -(let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total) -@end group -@end smallexample - -@need 1200 -Putting everything together, the @code{triangle} function definition -looks like this: - -@smallexample -@group -(defun triangle (number-of-rows) ; @r{Version with} - ; @r{ incrementing counter.} - "Add up the number of pebbles in a triangle. -The first row has one pebble, the second row two pebbles, -the third row three pebbles, and so on. -The argument is NUMBER-OF-ROWS." -@end group -@group - (let ((total 0) - (row-number 1)) - (while (<= row-number number-of-rows) - (setq total (+ total row-number)) - (setq row-number (1+ row-number))) - total)) -@end group -@end smallexample - -@need 1200 -After you have installed @code{triangle} by evaluating the function, you -can try it out. Here are two examples: - -@smallexample -@group -(triangle 4) - -(triangle 7) -@end group -@end smallexample - -@noindent -The sum of the first four numbers is 10 and the sum of the first seven -numbers is 28. - -@node Decrementing Loop, , Incrementing Loop Details, while -@comment node-name, next, previous, up -@subsection Loop with a Decrementing Counter - -Another common way to write a @code{while} loop is to write the test -so that it determines whether a counter is greater than zero. So long -as the counter is greater than zero, the loop is repeated. But when -the counter is equal to or less than zero, the loop is stopped. For -this to work, the counter has to start out greater than zero and then -be made smaller and smaller by a form that is evaluated -repeatedly. - -The test will be an expression such as @code{(> counter 0)} which -returns @code{t} for true if the value of @code{counter} is greater -than zero, and @code{nil} for false if the value of @code{counter} is -equal to or less than zero. The expression that makes the number -smaller and smaller can be a simple @code{setq} such as @code{(setq -counter (1- counter))}, where @code{1-} is a built-in function in -Emacs Lisp that subtracts 1 from its argument. - -@need 1250 -The template for a decrementing @code{while} loop looks like this: - -@smallexample -@group -(while (> counter 0) ; @r{true-or-false-test} - @var{body}@dots{} - (setq counter (1- counter))) ; @r{decrementer} -@end group -@end smallexample - -@menu -* Decrementing Example:: More pebbles on the beach. -* Dec Example parts:: The parts of the function definition. -* Dec Example altogether:: Putting the function definition together. -@end menu - -@node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop -@unnumberedsubsubsec Example with decrementing counter - -To illustrate a loop with a decrementing counter, we will rewrite the -@code{triangle} function so the counter decreases to zero. - -This is the reverse of the earlier version of the function. In this -case, to find out how many pebbles are needed to make a triangle with -3 rows, add the number of pebbles in the third row, 3, to the number -in the preceding row, 2, and then add the total of those two rows to -the row that precedes them, which is 1. - -Likewise, to find the number of pebbles in a triangle with 7 rows, add -the number of pebbles in the seventh row, 7, to the number in the -preceding row, which is 6, and then add the total of those two rows to -the row that precedes them, which is 5, and so on. As in the previous -example, each addition only involves adding two numbers, the total of -the rows already added up and the number of pebbles in the row that is -being added to the total. This process of adding two numbers is -repeated again and again until there are no more pebbles to add. - -We know how many pebbles to start with: the number of pebbles in the -last row is equal to the number of rows. If the triangle has seven -rows, the number of pebbles in the last row is 7. Likewise, we know how -many pebbles are in the preceding row: it is one less than the number in -the row. - -@node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop -@unnumberedsubsubsec The parts of the function definition - -We start with three variables: the total number of rows in the -triangle; the number of pebbles in a row; and the total number of -pebbles, which is what we want to calculate. These variables can be -named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and -@code{total}, respectively. - -Both @code{total} and @code{number-of-pebbles-in-row} are used only -inside the function and are declared with @code{let}. The initial -value of @code{total} should, of course, be zero. However, the -initial value of @code{number-of-pebbles-in-row} should be equal to -the number of rows in the triangle, since the addition will start with -the longest row. - -@need 1250 -This means that the beginning of the @code{let} expression will look -like this: - -@smallexample -@group -(let ((total 0) - (number-of-pebbles-in-row number-of-rows)) - @var{body}@dots{}) -@end group -@end smallexample - -The total number of pebbles can be found by repeatedly adding the number -of pebbles in a row to the total already found, that is, by repeatedly -evaluating the following expression: - -@smallexample -(setq total (+ total number-of-pebbles-in-row)) -@end smallexample - -@noindent -After the @code{number-of-pebbles-in-row} is added to the @code{total}, -the @code{number-of-pebbles-in-row} should be decremented by one, since -the next time the loop repeats, the preceding row will be -added to the total. - -The number of pebbles in a preceding row is one less than the number of -pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be -used to compute the number of pebbles in the preceding row. This can be -done with the following expression: - -@smallexample -@group -(setq number-of-pebbles-in-row - (1- number-of-pebbles-in-row)) -@end group -@end smallexample - -Finally, we know that the @code{while} loop should stop making repeated -additions when there are no pebbles in a row. So the test for -the @code{while} loop is simply: - -@smallexample -(while (> number-of-pebbles-in-row 0) -@end smallexample - -@node Dec Example altogether, , Dec Example parts, Decrementing Loop -@unnumberedsubsubsec Putting the function definition together - -We can put these expressions together to create a function definition -that works. However, on examination, we find that one of the local -variables is unneeded! - -@need 1250 -The function definition looks like this: - -@smallexample -@group -;;; @r{First subtractive version.} -(defun triangle (number-of-rows) - "Add up the number of pebbles in a triangle." - (let ((total 0) - (number-of-pebbles-in-row number-of-rows)) - (while (> number-of-pebbles-in-row 0) - (setq total (+ total number-of-pebbles-in-row)) - (setq number-of-pebbles-in-row - (1- number-of-pebbles-in-row))) - total)) -@end group -@end smallexample - -As written, this function works. - -However, we do not need @code{number-of-pebbles-in-row}. - -@cindex Argument as local variable -When the @code{triangle} function is evaluated, the symbol -@code{number-of-rows} will be bound to a number, giving it an initial -value. That number can be changed in the body of the function as if -it were a local variable, without any fear that such a change will -effect the value of the variable outside of the function. This is a -very useful characteristic of Lisp; it means that the variable -@code{number-of-rows} can be used anywhere in the function where -@code{number-of-pebbles-in-row} is used. - -@need 800 -Here is a second version of the function written a bit more cleanly: - -@smallexample -@group -(defun triangle (number) ; @r{Second version.} - "Return sum of numbers 1 through NUMBER inclusive." - (let ((total 0)) - (while (> number 0) - (setq total (+ total number)) - (setq number (1- number))) - total)) -@end group -@end smallexample - -In brief, a properly written @code{while} loop will consist of three parts: - -@enumerate -@item -A test that will return false after the loop has repeated itself the -correct number of times. - -@item -An expression the evaluation of which will return the value desired -after being repeatedly evaluated. - -@item -An expression to change the value passed to the true-or-false-test so -that the test returns false after the loop has repeated itself the right -number of times. -@end enumerate - -@node dolist dotimes, Recursion, while, Loops & Recursion -@comment node-name, next, previous, up -@section Save your time: @code{dolist} and @code{dotimes} - -In addition to @code{while}, both @code{dolist} and @code{dotimes} -provide for looping. Sometimes these are quicker to write than the -equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, , -Macros, elisp, The GNU Emacs Lisp Reference Manual}. ) - -@code{dolist} works like a @code{while} loop that `@sc{cdr}s down a -list': @code{dolist} automatically shortens the list each time it -loops---takes the @sc{cdr} of the list---and binds the @sc{car} of -each shorter version of the list to the first of its arguments. - -@code{dotimes} loops a specific number of times: you specify the number. - -@menu -* dolist:: -* dotimes:: -@end menu - -@node dolist, dotimes, dolist dotimes, dolist dotimes -@unnumberedsubsubsec The @code{dolist} Macro -@findex dolist - -Suppose, for example, you want to reverse a list, so that -``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''. - -@need 1250 -In practice, you would use the @code{reverse} function, like this: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(reverse animals) -@end group -@end smallexample - -@need 800 -@noindent -Here is how you could reverse the list using a @code{while} loop: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun reverse-list-with-while (list) - "Using while, reverse the order of LIST." - (let (value) ; make sure list starts empty - (while list - (setq value (cons (car list) value)) - (setq list (cdr list))) - value)) - -(reverse-list-with-while animals) -@end group -@end smallexample - -@need 800 -@noindent -And here is how you could use the @code{dolist} macro: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun reverse-list-with-dolist (list) - "Using dolist, reverse the order of LIST." - (let (value) ; make sure list starts empty - (dolist (element list value) - (setq value (cons element value))))) - -(reverse-list-with-dolist animals) -@end group -@end smallexample - -@need 1250 -@noindent -In Info, you can place your cursor after the closing parenthesis of -each expression and type @kbd{C-x C-e}; in each case, you should see - -@smallexample -(tiger lion giraffe gazelle) -@end smallexample - -@noindent -in the echo area. - -For this example, the existing @code{reverse} function is obviously best. -The @code{while} loop is just like our first example (@pxref{Loop -Example, , A @code{while} Loop and a List}). The @code{while} first -checks whether the list has elements; if so, it constructs a new list -by adding the first element of the list to the existing list (which in -the first iteration of the loop is @code{nil}). Since the second -element is prepended in front of the first element, and the third -element is prepended in front of the second element, the list is reversed. - -In the expression using a @code{while} loop, -the @w{@code{(setq list (cdr list))}} -expression shortens the list, so the @code{while} loop eventually -stops. In addition, it provides the @code{cons} expression with a new -first element by creating a new and shorter list at each repetition of -the loop. - -The @code{dolist} expression does very much the same as the -@code{while} expression, except that the @code{dolist} macro does some -of the work you have to do when writing a @code{while} expression. - -Like a @code{while} loop, a @code{dolist} loops. What is different is -that it automatically shortens the list each time it loops --- it -`@sc{cdr}s down the list' on its own --- and it automatically binds -the @sc{car} of each shorter version of the list to the first of its -arguments. - -In the example, the @sc{car} of each shorter version of the list is -referred to using the symbol @samp{element}, the list itself is called -@samp{list}, and the value returned is called @samp{value}. The -remainder of the @code{dolist} expression is the body. - -The @code{dolist} expression binds the @sc{car} of each shorter -version of the list to @code{element} and then evaluates the body of -the expression; and repeats the loop. The result is returned in -@code{value}. - -@node dotimes, , dolist, dolist dotimes -@unnumberedsubsubsec The @code{dotimes} Macro -@findex dotimes - -The @code{dotimes} macro is similar to @code{dolist}, except that it -loops a specific number of times. - -The first argument to @code{dotimes} is assigned the numbers 0, 1, 2 -and so forth each time around the loop, and the value of the third -argument is returned. You need to provide the value of the second -argument, which is how many times the macro loops. - -@need 1250 -For example, the following binds the numbers from 0 up to, but not -including, the number 3 to the first argument, @var{number}, and then -constructs a list of the three numbers. (The first number is 0, the -second number is 1, and the third number is 2; this makes a total of -three numbers in all, starting with zero as the first number.) - -@smallexample -@group -(let (value) ; otherwise a value is a void variable - (dotimes (number 3 value) - (setq value (cons number value)))) - -@result{} (2 1 0) -@end group -@end smallexample - -@noindent -@code{dotimes} returns @code{value}, so the way to use -@code{dotimes} is to operate on some expression @var{number} number of -times and then return the result, either as a list or an atom. - -@need 1250 -Here is an example of a @code{defun} that uses @code{dotimes} to add -up the number of pebbles in a triangle. - -@smallexample -@group -(defun triangle-using-dotimes (number-of-rows) - "Using dotimes, add up the number of pebbles in a triangle." -(let ((total 0)) ; otherwise a total is a void variable - (dotimes (number number-of-rows total) - (setq total (+ total (1+ number)))))) - -(triangle-using-dotimes 4) -@end group -@end smallexample - -@node Recursion, Looping exercise, dolist dotimes, Loops & Recursion -@comment node-name, next, previous, up -@section Recursion -@cindex Recursion - -A recursive function contains code that tells the Lisp interpreter to -call a program that runs exactly like itself, but with slightly -different arguments. The code runs exactly the same because it has -the same name. However, even though the program has the same name, it -is not the same entity. It is different. In the jargon, it is a -different `instance'. - -Eventually, if the program is written correctly, the `slightly -different arguments' will become sufficiently different from the first -arguments that the final instance will stop. - -@menu -* Building Robots:: Same model, different serial number ... -* Recursive Definition Parts:: Walk until you stop ... -* Recursion with list:: Using a list as the test whether to recurse. -* Recursive triangle function:: -* Recursion with cond:: -* Recursive Patterns:: Often used templates. -* No Deferment:: Don't store up work ... -* No deferment solution:: -@end menu - -@node Building Robots, Recursive Definition Parts, Recursion, Recursion -@comment node-name, next, previous, up -@subsection Building Robots: Extending the Metaphor -@cindex Building robots -@cindex Robots, building - -It is sometimes helpful to think of a running program as a robot that -does a job. In doing its job, a recursive function calls on a second -robot to help it. The second robot is identical to the first in every -way, except that the second robot helps the first and has been -passed different arguments than the first. - -In a recursive function, the second robot may call a third; and the -third may call a fourth, and so on. Each of these is a different -entity; but all are clones. - -Since each robot has slightly different instructions---the arguments -will differ from one robot to the next---the last robot should know -when to stop. - -Let's expand on the metaphor in which a computer program is a robot. - -A function definition provides the blueprints for a robot. When you -install a function definition, that is, when you evaluate a -@code{defun} special form, you install the necessary equipment to -build robots. It is as if you were in a factory, setting up an -assembly line. Robots with the same name are built according to the -same blueprints. So they have, as it were, the same `model number', -but a different `serial number'. - -We often say that a recursive function `calls itself'. What we mean -is that the instructions in a recursive function cause the Lisp -interpreter to run a different function that has the same name and -does the same job as the first, but with different arguments. - -It is important that the arguments differ from one instance to the -next; otherwise, the process will never stop. - -@node Recursive Definition Parts, Recursion with list, Building Robots, Recursion -@comment node-name, next, previous, up -@subsection The Parts of a Recursive Definition -@cindex Parts of a Recursive Definition -@cindex Recursive Definition Parts - -A recursive function typically contains a conditional expression which -has three parts: - -@enumerate -@item -A true-or-false-test that determines whether the function is called -again, here called the @dfn{do-again-test}. - -@item -The name of the function. When this name is called, a new instance of -the function---a new robot, as it were---is created and told what to do. - -@item -An expression that returns a different value each time the function is -called, here called the @dfn{next-step-expression}. Consequently, the -argument (or arguments) passed to the new instance of the function -will be different from that passed to the previous instance. This -causes the conditional expression, the @dfn{do-again-test}, to test -false after the correct number of repetitions. -@end enumerate - -Recursive functions can be much simpler than any other kind of -function. Indeed, when people first start to use them, they often look -so mysteriously simple as to be incomprehensible. Like riding a -bicycle, reading a recursive function definition takes a certain knack -which is hard at first but then seems simple. - -@need 1200 -There are several different common recursive patterns. A very simple -pattern looks like this: - -@smallexample -@group -(defun @var{name-of-recursive-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (if @var{do-again-test} - @var{body}@dots{} - (@var{name-of-recursive-function} - @var{next-step-expression}))) -@end group -@end smallexample - -Each time a recursive function is evaluated, a new instance of it is -created and told what to do. The arguments tell the instance what to do. - -An argument is bound to the value of the next-step-expression. Each -instance runs with a different value of the next-step-expression. - -The value in the next-step-expression is used in the do-again-test. - -The value returned by the next-step-expression is passed to the new -instance of the function, which evaluates it (or some -transmogrification of it) to determine whether to continue or stop. -The next-step-expression is designed so that the do-again-test returns -false when the function should no longer be repeated. - -The do-again-test is sometimes called the @dfn{stop condition}, -since it stops the repetitions when it tests false. - -@node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion -@comment node-name, next, previous, up -@subsection Recursion with a List - -The example of a @code{while} loop that printed the elements of a list -of numbers can be written recursively. Here is the code, including -an expression to set the value of the variable @code{animals} to a list. - -If you are using GNU Emacs 20 or before, this example must be copied -to the @file{*scratch*} buffer and each expression must be evaluated -there. Use @kbd{C-u C-x C-e} to evaluate the -@code{(print-elements-recursively animals)} expression so that the -results are printed in the buffer; otherwise the Lisp interpreter will -try to squeeze the results into the one line of the echo area. - -Also, place your cursor immediately after the last closing parenthesis -of the @code{print-elements-recursively} function, before the comment. -Otherwise, the Lisp interpreter will try to evaluate the comment. - -If you are using a more recent version of Emacs, you can evaluate this -expression directly in Info. - -@findex print-elements-recursively -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun print-elements-recursively (list) - "Print each element of LIST on a line of its own. -Uses recursion." - (when list ; @r{do-again-test} - (print (car list)) ; @r{body} - (print-elements-recursively ; @r{recursive call} - (cdr list)))) ; @r{next-step-expression} - -(print-elements-recursively animals) -@end group -@end smallexample - -The @code{print-elements-recursively} function first tests whether -there is any content in the list; if there is, the function prints the -first element of the list, the @sc{car} of the list. Then the -function `invokes itself', but gives itself as its argument, not the -whole list, but the second and subsequent elements of the list, the -@sc{cdr} of the list. - -Put another way, if the list is not empty, the function invokes -another instance of code that is similar to the initial code, but is a -different thread of execution, with different arguments than the first -instance. - -Put in yet another way, if the list is not empty, the first robot -assemblies a second robot and tells it what to do; the second robot is -a different individual from the first, but is the same model. - -When the second evaluation occurs, the @code{when} expression is -evaluated and if true, prints the first element of the list it -receives as its argument (which is the second element of the original -list). Then the function `calls itself' with the @sc{cdr} of the list -it is invoked with, which (the second time around) is the @sc{cdr} of -the @sc{cdr} of the original list. - -Note that although we say that the function `calls itself', what we -mean is that the Lisp interpreter assembles and instructs a new -instance of the program. The new instance is a clone of the first, -but is a separate individual. - -Each time the function `invokes itself', it invokes itself on a -shorter version of the original list. It creates a new instance that -works on a shorter list. - -Eventually, the function invokes itself on an empty list. It creates -a new instance whose argument is @code{nil}. The conditional expression -tests the value of @code{list}. Since the value of @code{list} is -@code{nil}, the @code{when} expression tests false so the then-part is -not evaluated. The function as a whole then returns @code{nil}. - -@need 1200 -When you evaluate @code{(print-elements-recursively animals)} in the -@file{*scratch*} buffer, you see this result: - -@smallexample -@group -gazelle - -giraffe - -lion - -tiger -nil -@end group -@end smallexample - -@need 2000 -@node Recursive triangle function, Recursion with cond, Recursion with list, Recursion -@comment node-name, next, previous, up -@subsection Recursion in Place of a Counter -@findex triangle-recursively - -@need 1200 -The @code{triangle} function described in a previous section can also -be written recursively. It looks like this: - -@smallexample -@group -(defun triangle-recursively (number) - "Return the sum of the numbers 1 through NUMBER inclusive. -Uses recursion." - (if (= number 1) ; @r{do-again-test} - 1 ; @r{then-part} - (+ number ; @r{else-part} - (triangle-recursively ; @r{recursive call} - (1- number))))) ; @r{next-step-expression} - -(triangle-recursively 7) -@end group -@end smallexample - -@noindent -You can install this function by evaluating it and then try it by -evaluating @code{(triangle-recursively 7)}. (Remember to put your -cursor immediately after the last parenthesis of the function -definition, before the comment.) The function evaluates to 28. - -To understand how this function works, let's consider what happens in the -various cases when the function is passed 1, 2, 3, or 4 as the value of -its argument. - -@menu -* Recursive Example arg of 1 or 2:: -* Recursive Example arg of 3 or 4:: -@end menu - -@node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function -@ifnottex -@unnumberedsubsubsec An argument of 1 or 2 -@end ifnottex - -First, what happens if the value of the argument is 1? - -The function has an @code{if} expression after the documentation -string. It tests whether the value of @code{number} is equal to 1; if -so, Emacs evaluates the then-part of the @code{if} expression, which -returns the number 1 as the value of the function. (A triangle with -one row has one pebble in it.) - -Suppose, however, that the value of the argument is 2. In this case, -Emacs evaluates the else-part of the @code{if} expression. - -@need 1200 -The else-part consists of an addition, the recursive call to -@code{triangle-recursively} and a decrementing action; and it looks like -this: - -@smallexample -(+ number (triangle-recursively (1- number))) -@end smallexample - -When Emacs evaluates this expression, the innermost expression is -evaluated first; then the other parts in sequence. Here are the steps -in detail: - -@table @i -@item Step 1 @w{ } Evaluate the innermost expression. - -The innermost expression is @code{(1- number)} so Emacs decrements the -value of @code{number} from 2 to 1. - -@item Step 2 @w{ } Evaluate the @code{triangle-recursively} function. - -The Lisp interpreter creates an individual instance of -@code{triangle-recursively}. It does not matter that this function is -contained within itself. Emacs passes the result Step 1 as the -argument used by this instance of the @code{triangle-recursively} -function - -In this case, Emacs evaluates @code{triangle-recursively} with an -argument of 1. This means that this evaluation of -@code{triangle-recursively} returns 1. - -@item Step 3 @w{ } Evaluate the value of @code{number}. - -The variable @code{number} is the second element of the list that -starts with @code{+}; its value is 2. - -@item Step 4 @w{ } Evaluate the @code{+} expression. - -The @code{+} expression receives two arguments, the first -from the evaluation of @code{number} (Step 3) and the second from the -evaluation of @code{triangle-recursively} (Step 2). - -The result of the addition is the sum of 2 plus 1, and the number 3 is -returned, which is correct. A triangle with two rows has three -pebbles in it. -@end table - -@node Recursive Example arg of 3 or 4, , Recursive Example arg of 1 or 2, Recursive triangle function -@unnumberedsubsubsec An argument of 3 or 4 - -Suppose that @code{triangle-recursively} is called with an argument of -3. - -@table @i -@item Step 1 @w{ } Evaluate the do-again-test. - -The @code{if} expression is evaluated first. This is the do-again -test and returns false, so the else-part of the @code{if} expression -is evaluated. (Note that in this example, the do-again-test causes -the function to call itself when it tests false, not when it tests -true.) - -@item Step 2 @w{ } Evaluate the innermost expression of the else-part. - -The innermost expression of the else-part is evaluated, which decrements -3 to 2. This is the next-step-expression. - -@item Step 3 @w{ } Evaluate the @code{triangle-recursively} function. - -The number 2 is passed to the @code{triangle-recursively} function. - -We know what happens when Emacs evaluates @code{triangle-recursively} with -an argument of 2. After going through the sequence of actions described -earlier, it returns a value of 3. So that is what will happen here. - -@item Step 4 @w{ } Evaluate the addition. - -3 will be passed as an argument to the addition and will be added to the -number with which the function was called, which is 3. -@end table - -@noindent -The value returned by the function as a whole will be 6. - -Now that we know what will happen when @code{triangle-recursively} is -called with an argument of 3, it is evident what will happen if it is -called with an argument of 4: - -@quotation -@need 800 -In the recursive call, the evaluation of - -@smallexample -(triangle-recursively (1- 4)) -@end smallexample - -@need 800 -@noindent -will return the value of evaluating - -@smallexample -(triangle-recursively 3) -@end smallexample - -@noindent -which is 6 and this value will be added to 4 by the addition in the -third line. -@end quotation - -@noindent -The value returned by the function as a whole will be 10. - -Each time @code{triangle-recursively} is evaluated, it evaluates a -version of itself---a different instance of itself---with a smaller -argument, until the argument is small enough so that it does not -evaluate itself. - -Note that this particular design for a recursive function -requires that operations be deferred. - -Before @code{(triangle-recursively 7)} can calculate its answer, it -must call @code{(triangle-recursively 6)}; and before -@code{(triangle-recursively 6)} can calculate its answer, it must call -@code{(triangle-recursively 5)}; and so on. That is to say, the -calculation that @code{(triangle-recursively 7)} makes must be -deferred until @code{(triangle-recursively 6)} makes its calculation; -and @code{(triangle-recursively 6)} must defer until -@code{(triangle-recursively 5)} completes; and so on. - -If each of these instances of @code{triangle-recursively} are thought -of as different robots, the first robot must wait for the second to -complete its job, which must wait until the third completes, and so -on. - -There is a way around this kind of waiting, which we will discuss in -@ref{No Deferment, , Recursion without Deferments}. - -@node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion -@comment node-name, next, previous, up -@subsection Recursion Example Using @code{cond} -@findex cond - -The version of @code{triangle-recursively} described earlier is written -with the @code{if} special form. It can also be written using another -special form called @code{cond}. The name of the special form -@code{cond} is an abbreviation of the word @samp{conditional}. - -Although the @code{cond} special form is not used as often in the -Emacs Lisp sources as @code{if}, it is used often enough to justify -explaining it. - -@need 800 -The template for a @code{cond} expression looks like this: - -@smallexample -@group -(cond - @var{body}@dots{}) -@end group -@end smallexample - -@noindent -where the @var{body} is a series of lists. - -@need 800 -Written out more fully, the template looks like this: - -@smallexample -@group -(cond - (@var{first-true-or-false-test} @var{first-consequent}) - (@var{second-true-or-false-test} @var{second-consequent}) - (@var{third-true-or-false-test} @var{third-consequent}) - @dots{}) -@end group -@end smallexample - -When the Lisp interpreter evaluates the @code{cond} expression, it -evaluates the first element (the @sc{car} or true-or-false-test) of -the first expression in a series of expressions within the body of the -@code{cond}. - -If the true-or-false-test returns @code{nil} the rest of that -expression, the consequent, is skipped and the true-or-false-test of the -next expression is evaluated. When an expression is found whose -true-or-false-test returns a value that is not @code{nil}, the -consequent of that expression is evaluated. The consequent can be one -or more expressions. If the consequent consists of more than one -expression, the expressions are evaluated in sequence and the value of -the last one is returned. If the expression does not have a consequent, -the value of the true-or-false-test is returned. - -If none of the true-or-false-tests test true, the @code{cond} expression -returns @code{nil}. - -@need 1250 -Written using @code{cond}, the @code{triangle} function looks like this: - -@smallexample -@group -(defun triangle-using-cond (number) - (cond ((<= number 0) 0) - ((= number 1) 1) - ((> number 1) - (+ number (triangle-using-cond (1- number)))))) -@end group -@end smallexample - -@noindent -In this example, the @code{cond} returns 0 if the number is less than or -equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+ -number (triangle-using-cond (1- number)))} if the number is greater than -1. - -@node Recursive Patterns, No Deferment, Recursion with cond, Recursion -@comment node-name, next, previous, up -@subsection Recursive Patterns -@cindex Recursive Patterns - -Here are three common recursive patterns. Each involves a list. -Recursion does not need to involve lists, but Lisp is designed for lists -and this provides a sense of its primal capabilities. - -@menu -* Every:: -* Accumulate:: -* Keep:: -@end menu - -@node Every, Accumulate, Recursive Patterns, Recursive Patterns -@comment node-name, next, previous, up -@unnumberedsubsubsec Recursive Pattern: @emph{every} -@cindex Every, type of recursive pattern -@cindex Recursive pattern: every - -In the @code{every} recursive pattern, an action is performed on every -element of a list. - -@need 1500 -The basic pattern is: - -@itemize @bullet -@item -If a list be empty, return @code{nil}. -@item -Else, act on the beginning of the list (the @sc{car} of the list) - @itemize @minus - @item - through a recursive call by the function on the rest (the - @sc{cdr}) of the list, - @item - and, optionally, combine the acted-on element, using @code{cons}, - with the results of acting on the rest. - @end itemize -@end itemize - -@need 1500 -Here is example: - -@smallexample -@group -(defun square-each (numbers-list) - "Square each of a NUMBERS LIST, recursively." - (if (not numbers-list) ; do-again-test - nil - (cons - (* (car numbers-list) (car numbers-list)) - (square-each (cdr numbers-list))))) ; next-step-expression -@end group - -@group -(square-each '(1 2 3)) - @result{} (1 4 9) -@end group -@end smallexample - -@need 1200 -@noindent -If @code{numbers-list} is empty, do nothing. But if it has content, -construct a list combining the square of the first number in the list -with the result of the recursive call. - -(The example follows the pattern exactly: @code{nil} is returned if -the numbers' list is empty. In practice, you would write the -conditional so it carries out the action when the numbers' list is not -empty.) - -The @code{print-elements-recursively} function (@pxref{Recursion with -list, , Recursion with a List}) is another example of an @code{every} -pattern, except in this case, rather than bring the results together -using @code{cons}, we print each element of output. - -@need 1250 -The @code{print-elements-recursively} function looks like this: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) -@end group - -@group -(defun print-elements-recursively (list) - "Print each element of LIST on a line of its own. -Uses recursion." - (when list ; @r{do-again-test} - (print (car list)) ; @r{body} - (print-elements-recursively ; @r{recursive call} - (cdr list)))) ; @r{next-step-expression} - -(print-elements-recursively animals) -@end group -@end smallexample - -@need 1500 -The pattern for @code{print-elements-recursively} is: - -@itemize @bullet -@item -When the list is empty, do nothing. -@item -But when the list has at least one element, - @itemize @minus - @item - act on the beginning of the list (the @sc{car} of the list), - @item - and make a recursive call on the rest (the @sc{cdr}) of the list. - @end itemize -@end itemize - -@node Accumulate, Keep, Every, Recursive Patterns -@comment node-name, next, previous, up -@unnumberedsubsubsec Recursive Pattern: @emph{accumulate} -@cindex Accumulate, type of recursive pattern -@cindex Recursive pattern: accumulate - -Another recursive pattern is called the @code{accumulate} pattern. In -the @code{accumulate} recursive pattern, an action is performed on -every element of a list and the result of that action is accumulated -with the results of performing the action on the other elements. - -This is very like the `every' pattern using @code{cons}, except that -@code{cons} is not used, but some other combiner. - -@need 1500 -The pattern is: - -@itemize @bullet -@item -If a list be empty, return zero or some other constant. -@item -Else, act on the beginning of the list (the @sc{car} of the list), - @itemize @minus - @item - and combine that acted-on element, using @code{+} or - some other combining function, with - @item - a recursive call by the function on the rest (the @sc{cdr}) of the list. - @end itemize -@end itemize - -@need 1500 -Here is an example: - -@smallexample -@group -(defun add-elements (numbers-list) - "Add the elements of NUMBERS-LIST together." - (if (not numbers-list) - 0 - (+ (car numbers-list) (add-elements (cdr numbers-list))))) -@end group - -@group -(add-elements '(1 2 3 4)) - @result{} 10 -@end group -@end smallexample - -@xref{Files List, , Making a List of Files}, for an example of the -accumulate pattern. - -@node Keep, , Accumulate, Recursive Patterns -@comment node-name, next, previous, up -@unnumberedsubsubsec Recursive Pattern: @emph{keep} -@cindex Keep, type of recursive pattern -@cindex Recursive pattern: keep - -A third recursive pattern is called the @code{keep} pattern. -In the @code{keep} recursive pattern, each element of a list is tested; -the element is acted on and the results are kept only if the element -meets a criterion. - -Again, this is very like the `every' pattern, except the element is -skipped unless it meets a criterion. - -@need 1500 -The pattern has three parts: - -@itemize @bullet -@item -If a list be empty, return @code{nil}. -@item -Else, if the beginning of the list (the @sc{car} of the list) passes - a test - @itemize @minus - @item - act on that element and combine it, using @code{cons} with - @item - a recursive call by the function on the rest (the @sc{cdr}) of the list. - @end itemize -@item -Otherwise, if the beginning of the list (the @sc{car} of the list) fails -the test - @itemize @minus - @item - skip on that element, - @item - and, recursively call the function on the rest (the @sc{cdr}) of the list. - @end itemize -@end itemize - -@need 1500 -Here is an example that uses @code{cond}: - -@smallexample -@group -(defun keep-three-letter-words (word-list) - "Keep three letter words in WORD-LIST." - (cond - ;; First do-again-test: stop-condition - ((not word-list) nil) - - ;; Second do-again-test: when to act - ((eq 3 (length (symbol-name (car word-list)))) - ;; combine acted-on element with recursive call on shorter list - (cons (car word-list) (keep-three-letter-words (cdr word-list)))) - - ;; Third do-again-test: when to skip element; - ;; recursively call shorter list with next-step expression - (t (keep-three-letter-words (cdr word-list))))) -@end group - -@group -(keep-three-letter-words '(one two three four five six)) - @result{} (one two six) -@end group -@end smallexample - -It goes without saying that you need not use @code{nil} as the test for -when to stop; and you can, of course, combine these patterns. - -@node No Deferment, No deferment solution, Recursive Patterns, Recursion -@subsection Recursion without Deferments -@cindex Deferment in recursion -@cindex Recursion without Deferments - -Let's consider again what happens with the @code{triangle-recursively} -function. We will find that the intermediate calculations are -deferred until all can be done. - -@need 800 -Here is the function definition: - -@smallexample -@group -(defun triangle-recursively (number) - "Return the sum of the numbers 1 through NUMBER inclusive. -Uses recursion." - (if (= number 1) ; @r{do-again-test} - 1 ; @r{then-part} - (+ number ; @r{else-part} - (triangle-recursively ; @r{recursive call} - (1- number))))) ; @r{next-step-expression} -@end group -@end smallexample - -What happens when we call this function with a argument of 7? - -The first instance of the @code{triangle-recursively} function adds -the number 7 to the value returned by a second instance of -@code{triangle-recursively}, an instance that has been passed an -argument of 6. That is to say, the first calculation is: - -@smallexample -(+ 7 (triangle-recursively 6)) -@end smallexample - -@noindent -The first instance of @code{triangle-recursively}---you may want to -think of it as a little robot---cannot complete its job. It must hand -off the calculation for @code{(triangle-recursively 6)} to a second -instance of the program, to a second robot. This second individual is -completely different from the first one; it is, in the jargon, a -`different instantiation'. Or, put another way, it is a different -robot. It is the same model as the first; it calculates triangle -numbers recursively; but it has a different serial number. - -And what does @code{(triangle-recursively 6)} return? It returns the -number 6 added to the value returned by evaluating -@code{triangle-recursively} with an argument of 5. Using the robot -metaphor, it asks yet another robot to help it. - -@need 800 -Now the total is: - -@smallexample -(+ 7 6 (triangle-recursively 5)) -@end smallexample - -@need 800 -And what happens next? - -@smallexample -(+ 7 6 5 (triangle-recursively 4)) -@end smallexample - -Each time @code{triangle-recursively} is called, except for the last -time, it creates another instance of the program---another robot---and -asks it to make a calculation. - -@need 800 -Eventually, the full addition is set up and performed: - -@smallexample -(+ 7 6 5 4 3 2 1) -@end smallexample - -This design for the function defers the calculation of the first step -until the second can be done, and defers that until the third can be -done, and so on. Each deferment means the computer must remember what -is being waited on. This is not a problem when there are only a few -steps, as in this example. But it can be a problem when there are -more steps. - -@node No deferment solution, , No Deferment, Recursion -@subsection No Deferment Solution -@cindex No deferment solution -@cindex Defermentless solution -@cindex Solution without deferment - -The solution to the problem of deferred operations is to write in a -manner that does not defer operations@footnote{The phrase @dfn{tail -recursive} is used to describe such a process, one that uses -`constant space'.}. This requires -writing to a different pattern, often one that involves writing two -function definitions, an `initialization' function and a `helper' -function. - -The `initialization' function sets up the job; the `helper' function -does the work. - -@need 1200 -Here are the two function definitions for adding up numbers. They are -so simple, I find them hard to understand. - -@smallexample -@group -(defun triangle-initialization (number) - "Return the sum of the numbers 1 through NUMBER inclusive. -This is the `initialization' component of a two function -duo that uses recursion." - (triangle-recursive-helper 0 0 number)) -@end group -@end smallexample - -@smallexample -@group -(defun triangle-recursive-helper (sum counter number) - "Return SUM, using COUNTER, through NUMBER inclusive. -This is the `helper' component of a two function duo -that uses recursion." - (if (> counter number) - sum - (triangle-recursive-helper (+ sum counter) ; @r{sum} - (1+ counter) ; @r{counter} - number))) ; @r{number} -@end group -@end smallexample - -@need 1250 -Install both function definitions by evaluating them, then call -@code{triangle-initialization} with 2 rows: - -@smallexample -@group -(triangle-initialization 2) - @result{} 3 -@end group -@end smallexample - -The `initialization' function calls the first instance of the `helper' -function with three arguments: zero, zero, and a number which is the -number of rows in the triangle. - -The first two arguments passed to the `helper' function are -initialization values. These values are changed when -@code{triangle-recursive-helper} invokes new instances.@footnote{The -jargon is mildly confusing: @code{triangle-recursive-helper} uses a -process that is iterative in a procedure that is recursive. The -process is called iterative because the computer need only record the -three values, @code{sum}, @code{counter}, and @code{number}; the -procedure is recursive because the function `calls itself'. On the -other hand, both the process and the procedure used by -@code{triangle-recursively} are called recursive. The word -`recursive' has different meanings in the two contexts.} - -Let's see what happens when we have a triangle that has one row. (This -triangle will have one pebble in it!) - -@need 1200 -@code{triangle-initialization} will call its helper with -the arguments @w{@code{0 0 1}}. That function will run the conditional -test whether @code{(> counter number)}: - -@smallexample -(> 0 1) -@end smallexample - -@need 1200 -@noindent -and find that the result is false, so it will invoke -the else-part of the @code{if} clause: - -@smallexample -@group - (triangle-recursive-helper - (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} - (1+ counter) ; @r{increment counter} @result{} @r{counter} - number) ; @r{number stays the same} -@end group -@end smallexample - -@need 800 -@noindent -which will first compute: - -@smallexample -@group -(triangle-recursive-helper (+ 0 0) ; @r{sum} - (1+ 0) ; @r{counter} - 1) ; @r{number} -@exdent which is: - -(triangle-recursive-helper 0 1 1) -@end group -@end smallexample - -Again, @code{(> counter number)} will be false, so again, the Lisp -interpreter will evaluate @code{triangle-recursive-helper}, creating a -new instance with new arguments. - -@need 800 -This new instance will be; - -@smallexample -@group - (triangle-recursive-helper - (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} - (1+ counter) ; @r{increment counter} @result{} @r{counter} - number) ; @r{number stays the same} - -@exdent which is: - -(triangle-recursive-helper 1 2 1) -@end group -@end smallexample - -In this case, the @code{(> counter number)} test will be true! So the -instance will return the value of the sum, which will be 1, as -expected. - -Now, let's pass @code{triangle-initialization} an argument -of 2, to find out how many pebbles there are in a triangle with two rows. - -That function calls @code{(triangle-recursive-helper 0 0 2)}. - -@need 800 -In stages, the instances called will be: - -@smallexample -@group - @r{sum counter number} -(triangle-recursive-helper 0 1 2) - -(triangle-recursive-helper 1 2 2) - -(triangle-recursive-helper 3 3 2) -@end group -@end smallexample - -When the last instance is called, the @code{(> counter number)} test -will be true, so the instance will return the value of @code{sum}, -which will be 3. - -This kind of pattern helps when you are writing functions that can use -many resources in a computer. - -@need 1500 -@node Looping exercise, , Recursion, Loops & Recursion -@section Looping Exercise - -@itemize @bullet -@item -Write a function similar to @code{triangle} in which each row has a -value which is the square of the row number. Use a @code{while} loop. - -@item -Write a function similar to @code{triangle} that multiplies instead of -adds the values. - -@item -Rewrite these two functions recursively. Rewrite these functions -using @code{cond}. - -@c comma in printed title causes problem in Info cross reference -@item -Write a function for Texinfo mode that creates an index entry at the -beginning of a paragraph for every @samp{@@dfn} within the paragraph. -(In a Texinfo file, @samp{@@dfn} marks a definition. This book is -written in Texinfo.) - -Many of the functions you will need are described in two of the -previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing -Text}, and @ref{Yanking, , Yanking Text Back}. If you use -@code{forward-paragraph} to put the index entry at the beginning of -the paragraph, you will have to use @w{@kbd{C-h f}} -(@code{describe-function}) to find out how to make the command go -backwards. - -For more information, see -@ifinfo -@ref{Indicating, , Indicating Definitions, texinfo}. -@end ifinfo -@ifhtml -@ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to -a Texinfo manual in the current directory. Or, if you are on the -Internet, see -@uref{http://www.gnu.org/software/texinfo/manual/texinfo/} -@end ifhtml -@iftex -``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU -Documentation Format}. -@end iftex -@end itemize - -@node Regexp Search, Counting Words, Loops & Recursion, Top -@comment node-name, next, previous, up -@chapter Regular Expression Searches -@cindex Searches, illustrating -@cindex Regular expression searches -@cindex Patterns, searching for -@cindex Motion by sentence and paragraph -@cindex Sentences, movement by -@cindex Paragraphs, movement by - -Regular expression searches are used extensively in GNU Emacs. The -two functions, @code{forward-sentence} and @code{forward-paragraph}, -illustrate these searches well. They use regular expressions to find -where to move point. The phrase `regular expression' is often written -as `regexp'. - -Regular expression searches are described in @ref{Regexp Search, , -Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in -@ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference -Manual}. In writing this chapter, I am presuming that you have at -least a mild acquaintance with them. The major point to remember is -that regular expressions permit you to search for patterns as well as -for literal strings of characters. For example, the code in -@code{forward-sentence} searches for the pattern of possible -characters that could mark the end of a sentence, and moves point to -that spot. - -Before looking at the code for the @code{forward-sentence} function, it -is worth considering what the pattern that marks the end of a sentence -must be. The pattern is discussed in the next section; following that -is a description of the regular expression search function, -@code{re-search-forward}. The @code{forward-sentence} function -is described in the section following. Finally, the -@code{forward-paragraph} function is described in the last section of -this chapter. @code{forward-paragraph} is a complex function that -introduces several new features. - -@menu -* sentence-end:: The regular expression for @code{sentence-end}. -* re-search-forward:: Very similar to @code{search-forward}. -* forward-sentence:: A straightforward example of regexp search. -* forward-paragraph:: A somewhat complex example. -* etags:: How to create your own @file{TAGS} table. -* Regexp Review:: -* re-search Exercises:: -@end menu - -@node sentence-end, re-search-forward, Regexp Search, Regexp Search -@comment node-name, next, previous, up -@section The Regular Expression for @code{sentence-end} -@findex sentence-end - -The symbol @code{sentence-end} is bound to the pattern that marks the -end of a sentence. What should this regular expression be? - -Clearly, a sentence may be ended by a period, a question mark, or an -exclamation mark. Indeed, in English, only clauses that end with one -of those three characters should be considered the end of a sentence. -This means that the pattern should include the character set: - -@smallexample -[.?!] -@end smallexample - -However, we do not want @code{forward-sentence} merely to jump to a -period, a question mark, or an exclamation mark, because such a character -might be used in the middle of a sentence. A period, for example, is -used after abbreviations. So other information is needed. - -According to convention, you type two spaces after every sentence, but -only one space after a period, a question mark, or an exclamation mark in -the body of a sentence. So a period, a question mark, or an exclamation -mark followed by two spaces is a good indicator of an end of sentence. -However, in a file, the two spaces may instead be a tab or the end of a -line. This means that the regular expression should include these three -items as alternatives. - -@need 800 -This group of alternatives will look like this: - -@smallexample -@group -\\($\\| \\| \\) - ^ ^^ - TAB SPC -@end group -@end smallexample - -@noindent -Here, @samp{$} indicates the end of the line, and I have pointed out -where the tab and two spaces are inserted in the expression. Both are -inserted by putting the actual characters into the expression. - -Two backslashes, @samp{\\}, are required before the parentheses and -vertical bars: the first backslash quotes the following backslash in -Emacs; and the second indicates that the following character, the -parenthesis or the vertical bar, is special. - -@need 1000 -Also, a sentence may be followed by one or more carriage returns, like -this: - -@smallexample -@group -[ -]* -@end group -@end smallexample - -@noindent -Like tabs and spaces, a carriage return is inserted into a regular -expression by inserting it literally. The asterisk indicates that the -@key{RET} is repeated zero or more times. - -But a sentence end does not consist only of a period, a question mark or -an exclamation mark followed by appropriate space: a closing quotation -mark or a closing brace of some kind may precede the space. Indeed more -than one such mark or brace may precede the space. These require a -expression that looks like this: - -@smallexample -[]\"')@}]* -@end smallexample - -In this expression, the first @samp{]} is the first character in the -expression; the second character is @samp{"}, which is preceded by a -@samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last -three characters are @samp{'}, @samp{)}, and @samp{@}}. - -All this suggests what the regular expression pattern for matching the -end of a sentence should be; and, indeed, if we evaluate -@code{sentence-end} we find that it returns the following value: - -@smallexample -@group -sentence-end - @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[ -]*" -@end group -@end smallexample - -@noindent -(Well, not in GNU Emacs 22; that is because of an effort to make the -process simpler and to handle more glyphs and languages. When the -value of @code{sentence-end} is @code{nil}, then use the value defined -by the function @code{sentence-end}. (Here is a use of the difference -between a value and a function in Emacs Lisp.) The function returns a -value constructed from the variables @code{sentence-end-base}, -@code{sentence-end-double-space}, @code{sentence-end-without-period}, -and @code{sentence-end-without-space}. The critical variable is -@code{sentence-end-base}; its global value is similar to the one -described above but it also contains two additional quotation marks. -These have differing degrees of curliness. The -@code{sentence-end-without-period} variable, when true, tells Emacs -that a sentence may end without a period, such as text in Thai.) - -@ignore -@noindent -(Note that here the @key{TAB}, two spaces, and @key{RET} are shown -literally in the pattern.) - -This regular expression can be deciphered as follows: - -@table @code -@item [.?!] -The first part of the pattern is the three characters, a period, a question -mark and an exclamation mark, within square brackets. The pattern must -begin with one or other of these characters. - -@item []\"')@}]* -The second part of the pattern is the group of closing braces and -quotation marks, which can appear zero or more times. These may follow -the period, question mark or exclamation mark. In a regular expression, -the backslash, @samp{\}, followed by the double quotation mark, -@samp{"}, indicates the class of string-quote characters. Usually, the -double quotation mark is the only character in this class. The -asterisk, @samp{*}, indicates that the items in the previous group (the -group surrounded by square brackets, @samp{[]}) may be repeated zero or -more times. - -@item \\($\\| \\| \\) -The third part of the pattern is one or other of: either the end of a -line, or two blank spaces, or a tab. The double back-slashes are used -to prevent Emacs from reading the parentheses and vertical bars as part -of the search pattern; the parentheses are used to mark the group and -the vertical bars are used to indicated that the patterns to either side -of them are alternatives. The dollar sign is used to indicate the end -of a line and both the two spaces and the tab are each inserted as is to -indicate what they are. - -@item [@key{RET}]* -Finally, the last part of the pattern indicates that the end of the line -or the whitespace following the period, question mark or exclamation -mark may, but need not, be followed by one or more carriage returns. In -the pattern, the carriage return is inserted as an actual carriage -return between square brackets but here it is shown as @key{RET}. -@end table -@end ignore - -@node re-search-forward, forward-sentence, sentence-end, Regexp Search -@comment node-name, next, previous, up -@section The @code{re-search-forward} Function -@findex re-search-forward - -The @code{re-search-forward} function is very like the -@code{search-forward} function. (@xref{search-forward, , The -@code{search-forward} Function}.) - -@code{re-search-forward} searches for a regular expression. If the -search is successful, it leaves point immediately after the last -character in the target. If the search is backwards, it leaves point -just before the first character in the target. You may tell -@code{re-search-forward} to return @code{t} for true. (Moving point -is therefore a `side effect'.) - -Like @code{search-forward}, the @code{re-search-forward} function takes -four arguments: - -@enumerate -@item -The first argument is the regular expression that the function searches -for. The regular expression will be a string between quotations marks. - -@item -The optional second argument limits how far the function will search; it is a -bound, which is specified as a position in the buffer. - -@item -The optional third argument specifies how the function responds to -failure: @code{nil} as the third argument causes the function to -signal an error (and print a message) when the search fails; any other -value causes it to return @code{nil} if the search fails and @code{t} -if the search succeeds. - -@item -The optional fourth argument is the repeat count. A negative repeat -count causes @code{re-search-forward} to search backwards. -@end enumerate - -@need 800 -The template for @code{re-search-forward} looks like this: - -@smallexample -@group -(re-search-forward "@var{regular-expression}" - @var{limit-of-search} - @var{what-to-do-if-search-fails} - @var{repeat-count}) -@end group -@end smallexample - -The second, third, and fourth arguments are optional. However, if you -want to pass a value to either or both of the last two arguments, you -must also pass a value to all the preceding arguments. Otherwise, the -Lisp interpreter will mistake which argument you are passing the value -to. - -@need 1200 -In the @code{forward-sentence} function, the regular expression will be -the value of the variable @code{sentence-end}. In simple form, that is: - -@smallexample -@group -"[.?!][]\"')@}]*\\($\\| \\| \\)[ -]*" -@end group -@end smallexample - -@noindent -The limit of the search will be the end of the paragraph (since a -sentence cannot go beyond a paragraph). If the search fails, the -function will return @code{nil}; and the repeat count will be provided -by the argument to the @code{forward-sentence} function. - -@node forward-sentence, forward-paragraph, re-search-forward, Regexp Search -@comment node-name, next, previous, up -@section @code{forward-sentence} -@findex forward-sentence - -The command to move the cursor forward a sentence is a straightforward -illustration of how to use regular expression searches in Emacs Lisp. -Indeed, the function looks longer and more complicated than it is; this -is because the function is designed to go backwards as well as forwards; -and, optionally, over more than one sentence. The function is usually -bound to the key command @kbd{M-e}. - -@menu -* Complete forward-sentence:: -* fwd-sentence while loops:: Two @code{while} loops. -* fwd-sentence re-search:: A regular expression search. -@end menu - -@node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence -@ifnottex -@unnumberedsubsec Complete @code{forward-sentence} function definition -@end ifnottex - -@need 1250 -Here is the code for @code{forward-sentence}: - -@c in GNU Emacs 22 -@smallexample -@group -(defun forward-sentence (&optional arg) - "Move forward to next `sentence-end'. With argument, repeat. -With negative argument, move backward repeatedly to `sentence-beginning'. - -The variable `sentence-end' is a regular expression that matches ends of -sentences. Also, every paragraph boundary terminates sentences as well." -@end group -@group - (interactive "p") - (or arg (setq arg 1)) - (let ((opoint (point)) - (sentence-end (sentence-end))) - (while (< arg 0) - (let ((pos (point)) - (par-beg (save-excursion (start-of-paragraph-text) (point)))) - (if (and (re-search-backward sentence-end par-beg t) - (or (< (match-end 0) pos) - (re-search-backward sentence-end par-beg t))) - (goto-char (match-end 0)) - (goto-char par-beg))) - (setq arg (1+ arg))) -@end group -@group - (while (> arg 0) - (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) - (if (re-search-forward sentence-end par-end t) - (skip-chars-backward " \t\n") - (goto-char par-end))) - (setq arg (1- arg))) - (constrain-to-field nil opoint t))) -@end group -@end smallexample - -@ignore -GNU Emacs 21 -@smallexample -@group -(defun forward-sentence (&optional arg) - "Move forward to next sentence-end. With argument, repeat. -With negative argument, move backward repeatedly to sentence-beginning. -Sentence ends are identified by the value of sentence-end -treated as a regular expression. Also, every paragraph boundary -terminates sentences as well." -@end group -@group - (interactive "p") - (or arg (setq arg 1)) - (while (< arg 0) - (let ((par-beg - (save-excursion (start-of-paragraph-text) (point)))) - (if (re-search-backward - (concat sentence-end "[^ \t\n]") par-beg t) - (goto-char (1- (match-end 0))) - (goto-char par-beg))) - (setq arg (1+ arg))) - (while (> arg 0) - (let ((par-end - (save-excursion (end-of-paragraph-text) (point)))) - (if (re-search-forward sentence-end par-end t) - (skip-chars-backward " \t\n") - (goto-char par-end))) - (setq arg (1- arg)))) -@end group -@end smallexample -@end ignore - -The function looks long at first sight and it is best to look at its -skeleton first, and then its muscle. The way to see the skeleton is to -look at the expressions that start in the left-most columns: - -@smallexample -@group -(defun forward-sentence (&optional arg) - "@var{documentation}@dots{}" - (interactive "p") - (or arg (setq arg 1)) - (let ((opoint (point)) (sentence-end (sentence-end))) - (while (< arg 0) - (let ((pos (point)) - (par-beg (save-excursion (start-of-paragraph-text) (point)))) - @var{rest-of-body-of-while-loop-when-going-backwards} - (while (> arg 0) - (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) - @var{rest-of-body-of-while-loop-when-going-forwards} - @var{handle-forms-and-equivalent} -@end group -@end smallexample - -This looks much simpler! The function definition consists of -documentation, an @code{interactive} expression, an @code{or} -expression, a @code{let} expression, and @code{while} loops. - -Let's look at each of these parts in turn. - -We note that the documentation is thorough and understandable. - -The function has an @code{interactive "p"} declaration. This means -that the processed prefix argument, if any, is passed to the -function as its argument. (This will be a number.) If the function -is not passed an argument (it is optional) then the argument -@code{arg} will be bound to 1. - -When @code{forward-sentence} is called non-interactively without an -argument, @code{arg} is bound to @code{nil}. The @code{or} expression -handles this. What it does is either leave the value of @code{arg} as -it is, but only if @code{arg} is bound to a value; or it sets the -value of @code{arg} to 1, in the case when @code{arg} is bound to -@code{nil}. - -Next is a @code{let}. That specifies the values of two local -variables, @code{point} and @code{sentence-end}. The local value of -point, from before the search, is used in the -@code{constrain-to-field} function which handles forms and -equivalents. The @code{sentence-end} variable is set by the -@code{sentence-end} function. - -@node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence -@unnumberedsubsec The @code{while} loops - -Two @code{while} loops follow. The first @code{while} has a -true-or-false-test that tests true if the prefix argument for -@code{forward-sentence} is a negative number. This is for going -backwards. The body of this loop is similar to the body of the second -@code{while} clause, but it is not exactly the same. We will skip -this @code{while} loop and concentrate on the second @code{while} -loop. - -@need 1500 -The second @code{while} loop is for moving point forward. Its skeleton -looks like this: - -@smallexample -@group -(while (> arg 0) ; @r{true-or-false-test} - (let @var{varlist} - (if (@var{true-or-false-test}) - @var{then-part} - @var{else-part} - (setq arg (1- arg)))) ; @code{while} @r{loop decrementer} -@end group -@end smallexample - -The @code{while} loop is of the decrementing kind. -(@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It -has a true-or-false-test that tests true so long as the counter (in -this case, the variable @code{arg}) is greater than zero; and it has a -decrementer that subtracts 1 from the value of the counter every time -the loop repeats. - -If no prefix argument is given to @code{forward-sentence}, which is -the most common way the command is used, this @code{while} loop will -run once, since the value of @code{arg} will be 1. - -The body of the @code{while} loop consists of a @code{let} expression, -which creates and binds a local variable, and has, as its body, an -@code{if} expression. - -@need 1250 -The body of the @code{while} loop looks like this: - -@smallexample -@group -(let ((par-end - (save-excursion (end-of-paragraph-text) (point)))) - (if (re-search-forward sentence-end par-end t) - (skip-chars-backward " \t\n") - (goto-char par-end))) -@end group -@end smallexample - -The @code{let} expression creates and binds the local variable -@code{par-end}. As we shall see, this local variable is designed to -provide a bound or limit to the regular expression search. If the -search fails to find a proper sentence ending in the paragraph, it will -stop on reaching the end of the paragraph. - -But first, let us examine how @code{par-end} is bound to the value of -the end of the paragraph. What happens is that the @code{let} sets the -value of @code{par-end} to the value returned when the Lisp interpreter -evaluates the expression - -@smallexample -@group -(save-excursion (end-of-paragraph-text) (point)) -@end group -@end smallexample - -@noindent -In this expression, @code{(end-of-paragraph-text)} moves point to the -end of the paragraph, @code{(point)} returns the value of point, and then -@code{save-excursion} restores point to its original position. Thus, -the @code{let} binds @code{par-end} to the value returned by the -@code{save-excursion} expression, which is the position of the end of -the paragraph. (The @code{end-of-paragraph-text} function uses -@code{forward-paragraph}, which we will discuss shortly.) - -@need 1200 -Emacs next evaluates the body of the @code{let}, which is an @code{if} -expression that looks like this: - -@smallexample -@group -(if (re-search-forward sentence-end par-end t) ; @r{if-part} - (skip-chars-backward " \t\n") ; @r{then-part} - (goto-char par-end))) ; @r{else-part} -@end group -@end smallexample - -The @code{if} tests whether its first argument is true and if so, -evaluates its then-part; otherwise, the Emacs Lisp interpreter -evaluates the else-part. The true-or-false-test of the @code{if} -expression is the regular expression search. - -It may seem odd to have what looks like the `real work' of -the @code{forward-sentence} function buried here, but this is a common -way this kind of operation is carried out in Lisp. - -@node fwd-sentence re-search, , fwd-sentence while loops, forward-sentence -@unnumberedsubsec The regular expression search - -The @code{re-search-forward} function searches for the end of the -sentence, that is, for the pattern defined by the @code{sentence-end} -regular expression. If the pattern is found---if the end of the sentence is -found---then the @code{re-search-forward} function does two things: - -@enumerate -@item -The @code{re-search-forward} function carries out a side effect, which -is to move point to the end of the occurrence found. - -@item -The @code{re-search-forward} function returns a value of true. This is -the value received by the @code{if}, and means that the search was -successful. -@end enumerate - -@noindent -The side effect, the movement of point, is completed before the -@code{if} function is handed the value returned by the successful -conclusion of the search. - -When the @code{if} function receives the value of true from a successful -call to @code{re-search-forward}, the @code{if} evaluates the then-part, -which is the expression @code{(skip-chars-backward " \t\n")}. This -expression moves backwards over any blank spaces, tabs or carriage -returns until a printed character is found and then leaves point after -the character. Since point has already been moved to the end of the -pattern that marks the end of the sentence, this action leaves point -right after the closing printed character of the sentence, which is -usually a period. - -On the other hand, if the @code{re-search-forward} function fails to -find a pattern marking the end of the sentence, the function returns -false. The false then causes the @code{if} to evaluate its third -argument, which is @code{(goto-char par-end)}: it moves point to the -end of the paragraph. - -(And if the text is in a form or equivalent, and point may not move -fully, then the @code{constrain-to-field} function comes into play.) - -Regular expression searches are exceptionally useful and the pattern -illustrated by @code{re-search-forward}, in which the search is the -test of an @code{if} expression, is handy. You will see or write code -incorporating this pattern often. - -@node forward-paragraph, etags, forward-sentence, Regexp Search -@comment node-name, next, previous, up -@section @code{forward-paragraph}: a Goldmine of Functions -@findex forward-paragraph - -@ignore -@c in GNU Emacs 22 -(defun forward-paragraph (&optional arg) - "Move forward to end of paragraph. -With argument ARG, do it ARG times; -a negative argument ARG = -N means move backward N paragraphs. - -A line which `paragraph-start' matches either separates paragraphs -\(if `paragraph-separate' matches it also) or is the first line of a paragraph. -A paragraph end is the beginning of a line which is not part of the paragraph -to which the end of the previous line belongs, or the end of the buffer. -Returns the count of paragraphs left to move." - (interactive "p") - (or arg (setq arg 1)) - (let* ((opoint (point)) - (fill-prefix-regexp - (and fill-prefix (not (equal fill-prefix "")) - (not paragraph-ignore-fill-prefix) - (regexp-quote fill-prefix))) - ;; Remove ^ from paragraph-start and paragraph-sep if they are there. - ;; These regexps shouldn't be anchored, because we look for them - ;; starting at the left-margin. This allows paragraph commands to - ;; work normally with indented text. - ;; This hack will not find problem cases like "whatever\\|^something". - (parstart (if (and (not (equal "" paragraph-start)) - (equal ?^ (aref paragraph-start 0))) - (substring paragraph-start 1) - paragraph-start)) - (parsep (if (and (not (equal "" paragraph-separate)) - (equal ?^ (aref paragraph-separate 0))) - (substring paragraph-separate 1) - paragraph-separate)) - (parsep - (if fill-prefix-regexp - (concat parsep "\\|" - fill-prefix-regexp "[ \t]*$") - parsep)) - ;; This is used for searching. - (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)")) - start found-start) - (while (and (< arg 0) (not (bobp))) - (if (and (not (looking-at parsep)) - (re-search-backward "^\n" (max (1- (point)) (point-min)) t) - (looking-at parsep)) - (setq arg (1+ arg)) - (setq start (point)) - ;; Move back over paragraph-separating lines. - (forward-char -1) (beginning-of-line) - (while (and (not (bobp)) - (progn (move-to-left-margin) - (looking-at parsep))) - (forward-line -1)) - (if (bobp) - nil - (setq arg (1+ arg)) - ;; Go to end of the previous (non-separating) line. - (end-of-line) - ;; Search back for line that starts or separates paragraphs. - (if (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart. - (let (multiple-lines) - (while (and (progn (beginning-of-line) (not (bobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (looking-at fill-prefix-regexp)) - (unless (= (point) start) - (setq multiple-lines t)) - (forward-line -1)) - (move-to-left-margin) - ;; This deleted code caused a long hanging-indent line - ;; not to be filled together with the following lines. - ;; ;; Don't move back over a line before the paragraph - ;; ;; which doesn't start with fill-prefix - ;; ;; unless that is the only line we've moved over. - ;; (and (not (looking-at fill-prefix-regexp)) - ;; multiple-lines - ;; (forward-line 1)) - (not (bobp))) - (while (and (re-search-backward sp-parstart nil 1) - (setq found-start t) - ;; Found a candidate, but need to check if it is a - ;; REAL parstart. - (progn (setq start (point)) - (move-to-left-margin) - (not (looking-at parsep))) - (not (and (looking-at parstart) - (or (not use-hard-newlines) - (bobp) - (get-text-property - (1- start) 'hard))))) - (setq found-start nil) - (goto-char start)) - found-start) - ;; Found one. - (progn - ;; Move forward over paragraph separators. - ;; We know this cannot reach the place we started - ;; because we know we moved back over a non-separator. - (while (and (not (eobp)) - (progn (move-to-left-margin) - (looking-at parsep))) - (forward-line 1)) - ;; If line before paragraph is just margin, back up to there. - (end-of-line 0) - (if (> (current-column) (current-left-margin)) - (forward-char 1) - (skip-chars-backward " \t") - (if (not (bolp)) - (forward-line 1)))) - ;; No starter or separator line => use buffer beg. - (goto-char (point-min)))))) - - (while (and (> arg 0) (not (eobp))) - ;; Move forward over separator lines... - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (looking-at parsep)) - (forward-line 1)) - (unless (eobp) (setq arg (1- arg))) - ;; ... and one more line. - (forward-line 1) - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart. - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) - (if (< (point) (point-max)) - (goto-char start)))) - (constrain-to-field nil opoint t) - ;; Return the number of steps that could not be done. - arg)) -@end ignore - -The @code{forward-paragraph} function moves point forward to the end -of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a -number of functions that are important in themselves, including -@code{let*}, @code{match-beginning}, and @code{looking-at}. - -The function definition for @code{forward-paragraph} is considerably -longer than the function definition for @code{forward-sentence} -because it works with a paragraph, each line of which may begin with a -fill prefix. - -A fill prefix consists of a string of characters that are repeated at -the beginning of each line. For example, in Lisp code, it is a -convention to start each line of a paragraph-long comment with -@samp{;;; }. In Text mode, four blank spaces make up another common -fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , , -emacs, The GNU Emacs Manual}, for more information about fill -prefixes.) - -The existence of a fill prefix means that in addition to being able to -find the end of a paragraph whose lines begin on the left-most -column, the @code{forward-paragraph} function must be able to find the -end of a paragraph when all or many of the lines in the buffer begin -with the fill prefix. - -Moreover, it is sometimes practical to ignore a fill prefix that -exists, especially when blank lines separate paragraphs. -This is an added complication. - -@menu -* forward-paragraph in brief:: Key parts of the function definition. -* fwd-para let:: The @code{let*} expression. -* fwd-para while:: The forward motion @code{while} loop. -@end menu - -@node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph -@ifnottex -@unnumberedsubsec Shortened @code{forward-paragraph} function definition -@end ifnottex - -Rather than print all of the @code{forward-paragraph} function, we -will only print parts of it. Read without preparation, the function -can be daunting! - -@need 800 -In outline, the function looks like this: - -@smallexample -@group -(defun forward-paragraph (&optional arg) - "@var{documentation}@dots{}" - (interactive "p") - (or arg (setq arg 1)) - (let* - @var{varlist} - (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code} - @dots{} - (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code} - @dots{} -@end group -@end smallexample - -The first parts of the function are routine: the function's argument -list consists of one optional argument. Documentation follows. - -The lower case @samp{p} in the @code{interactive} declaration means -that the processed prefix argument, if any, is passed to the function. -This will be a number, and is the repeat count of how many paragraphs -point will move. The @code{or} expression in the next line handles -the common case when no argument is passed to the function, which occurs -if the function is called from other code rather than interactively. -This case was described earlier. (@xref{forward-sentence, The -@code{forward-sentence} function}.) Now we reach the end of the -familiar part of this function. - -@node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph -@unnumberedsubsec The @code{let*} expression - -The next line of the @code{forward-paragraph} function begins a -@code{let*} expression. This is a different than @code{let}. The -symbol is @code{let*} not @code{let}. - -The @code{let*} special form is like @code{let} except that Emacs sets -each variable in sequence, one after another, and variables in the -latter part of the varlist can make use of the values to which Emacs -set variables in the earlier part of the varlist. - -@ignore -( refappend save-excursion, , code save-excursion in code append-to-buffer .) -@end ignore - -(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.) - -In the @code{let*} expression in this function, Emacs binds a total of -seven variables: @code{opoint}, @code{fill-prefix-regexp}, -@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and -@code{found-start}. - -The variable @code{parsep} appears twice, first, to remove instances -of @samp{^}, and second, to handle fill prefixes. - -The variable @code{opoint} is just the value of @code{point}. As you -can guess, it is used in a @code{constrain-to-field} expression, just -as in @code{forward-sentence}. - -The variable @code{fill-prefix-regexp} is set to the value returned by -evaluating the following list: - -@smallexample -@group -(and fill-prefix - (not (equal fill-prefix "")) - (not paragraph-ignore-fill-prefix) - (regexp-quote fill-prefix)) -@end group -@end smallexample - -@noindent -This is an expression whose first element is the @code{and} special form. - -As we learned earlier (@pxref{kill-new function, , The @code{kill-new} -function}), the @code{and} special form evaluates each of its -arguments until one of the arguments returns a value of @code{nil}, in -which case the @code{and} expression returns @code{nil}; however, if -none of the arguments returns a value of @code{nil}, the value -resulting from evaluating the last argument is returned. (Since such -a value is not @code{nil}, it is considered true in Lisp.) In other -words, an @code{and} expression returns a true value only if all its -arguments are true. -@findex and - -In this case, the variable @code{fill-prefix-regexp} is bound to a -non-@code{nil} value only if the following four expressions produce a -true (i.e., a non-@code{nil}) value when they are evaluated; otherwise, -@code{fill-prefix-regexp} is bound to @code{nil}. - -@table @code -@item fill-prefix -When this variable is evaluated, the value of the fill prefix, if any, -is returned. If there is no fill prefix, this variable returns -@code{nil}. - -@item (not (equal fill-prefix "") -This expression checks whether an existing fill prefix is an empty -string, that is, a string with no characters in it. An empty string is -not a useful fill prefix. - -@item (not paragraph-ignore-fill-prefix) -This expression returns @code{nil} if the variable -@code{paragraph-ignore-fill-prefix} has been turned on by being set to a -true value such as @code{t}. - -@item (regexp-quote fill-prefix) -This is the last argument to the @code{and} special form. If all the -arguments to the @code{and} are true, the value resulting from -evaluating this expression will be returned by the @code{and} expression -and bound to the variable @code{fill-prefix-regexp}, -@end table - -@findex regexp-quote -@noindent -The result of evaluating this @code{and} expression successfully is that -@code{fill-prefix-regexp} will be bound to the value of -@code{fill-prefix} as modified by the @code{regexp-quote} function. -What @code{regexp-quote} does is read a string and return a regular -expression that will exactly match the string and match nothing else. -This means that @code{fill-prefix-regexp} will be set to a value that -will exactly match the fill prefix if the fill prefix exists. -Otherwise, the variable will be set to @code{nil}. - -The next two local variables in the @code{let*} expression are -designed to remove instances of @samp{^} from @code{parstart} and -@code{parsep}, the local variables which indicate the paragraph start -and the paragraph separator. The next expression sets @code{parsep} -again. That is to handle fill prefixes. - -This is the setting that requires the definition call @code{let*} -rather than @code{let}. The true-or-false-test for the @code{if} -depends on whether the variable @code{fill-prefix-regexp} evaluates to -@code{nil} or some other value. - -If @code{fill-prefix-regexp} does not have a value, Emacs evaluates -the else-part of the @code{if} expression and binds @code{parsep} to -its local value. (@code{parsep} is a regular expression that matches -what separates paragraphs.) - -But if @code{fill-prefix-regexp} does have a value, Emacs evaluates -the then-part of the @code{if} expression and binds @code{parsep} to a -regular expression that includes the @code{fill-prefix-regexp} as part -of the pattern. - -Specifically, @code{parsep} is set to the original value of the -paragraph separate regular expression concatenated with an alternative -expression that consists of the @code{fill-prefix-regexp} followed by -optional whitespace to the end of the line. The whitespace is defined -by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the -regexp as an alternative to @code{parsep}. - -According to a comment in the code, the next local variable, -@code{sp-parstart}, is used for searching, and then the final two, -@code{start} and @code{found-start}, are set to @code{nil}. - -Now we get into the body of the @code{let*}. The first part of the body -of the @code{let*} deals with the case when the function is given a -negative argument and is therefore moving backwards. We will skip this -section. - -@node fwd-para while, , fwd-para let, forward-paragraph -@unnumberedsubsec The forward motion @code{while} loop - -The second part of the body of the @code{let*} deals with forward -motion. It is a @code{while} loop that repeats itself so long as the -value of @code{arg} is greater than zero. In the most common use of -the function, the value of the argument is 1, so the body of the -@code{while} loop is evaluated exactly once, and the cursor moves -forward one paragraph. - -@ignore -(while (and (> arg 0) (not (eobp))) - - ;; Move forward over separator lines... - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (looking-at parsep)) - (forward-line 1)) - (unless (eobp) (setq arg (1- arg))) - ;; ... and one more line. - (forward-line 1) - - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart. - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) - - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) - - (if (< (point) (point-max)) - (goto-char start)))) -@end ignore - -This part handles three situations: when point is between paragraphs, -when there is a fill prefix and when there is no fill prefix. - -@need 800 -The @code{while} loop looks like this: - -@smallexample -@group -;; @r{going forwards and not at the end of the buffer} -(while (and (> arg 0) (not (eobp))) - - ;; @r{between paragraphs} - ;; Move forward over separator lines... - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (looking-at parsep)) - (forward-line 1)) - ;; @r{This decrements the loop} - (unless (eobp) (setq arg (1- arg))) - ;; ... and one more line. - (forward-line 1) -@end group - -@group - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart; - ;; we go forward line by line - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) -@end group - -@group - ;; There is no fill prefix; - ;; we go forward character by character - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) -@end group - -@group - ;; and if there is no fill prefix and if we are not at the end, - ;; go to whatever was found in the regular expression search - ;; for sp-parstart - (if (< (point) (point-max)) - (goto-char start)))) -@end group -@end smallexample - -@findex eobp -We can see that this is a decrementing counter @code{while} loop, -using the expression @code{(setq arg (1- arg))} as the decrementer. -That expression is not far from the @code{while}, but is hidden in -another Lisp macro, an @code{unless} macro. Unless we are at the end -of the buffer --- that is what the @code{eobp} function determines; it -is an abbreviation of @samp{End Of Buffer P} --- we decrease the value -of @code{arg} by one. - -(If we are at the end of the buffer, we cannot go forward any more and -the next loop of the @code{while} expression will test false since the -test is an @code{and} with @code{(not (eobp))}. The @code{not} -function means exactly as you expect; it is another name for -@code{null}, a function that returns true when its argument is false.) - -Interestingly, the loop count is not decremented until we leave the -space between paragraphs, unless we come to the end of buffer or stop -seeing the local value of the paragraph separator. - -That second @code{while} also has a @code{(move-to-left-margin)} -expression. The function is self-explanatory. It is inside a -@code{progn} expression and not the last element of its body, so it is -only invoked for its side effect, which is to move point to the left -margin of the current line. - -@findex looking-at -The @code{looking-at} function is also self-explanatory; it returns -true if the text after point matches the regular expression given as -its argument. - -The rest of the body of the loop looks difficult at first, but makes -sense as you come to understand it. - -@need 800 -First consider what happens if there is a fill prefix: - -@smallexample -@group - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart; - ;; we go forward line by line - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) -@end group -@end smallexample - -@noindent -This expression moves point forward line by line so long -as four conditions are true: - -@enumerate -@item -Point is not at the end of the buffer. - -@item -We can move to the left margin of the text and are -not at the end of the buffer. - -@item -The text following point does not separate paragraphs. - -@item -The pattern following point is the fill prefix regular expression. -@end enumerate - -The last condition may be puzzling, until you remember that point was -moved to the beginning of the line early in the @code{forward-paragraph} -function. This means that if the text has a fill prefix, the -@code{looking-at} function will see it. - -@need 1250 -Consider what happens when there is no fill prefix. - -@smallexample -@group - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) -@end group -@end smallexample - -@noindent -This @code{while} loop has us searching forward for -@code{sp-parstart}, which is the combination of possible whitespace -with a the local value of the start of a paragraph or of a paragraph -separator. (The latter two are within an expression starting -@code{\(?:} so that they are not referenced by the -@code{match-beginning} function.) - -@need 800 -The two expressions, - -@smallexample -@group -(setq start (match-beginning 0)) -(goto-char start) -@end group -@end smallexample - -@noindent -mean go to the start of the text matched by the regular expression -search. - -The @code{(match-beginning 0)} expression is new. It returns a number -specifying the location of the start of the text that was matched by -the last search. - -The @code{match-beginning} function is used here because of a -characteristic of a forward search: a successful forward search, -regardless of whether it is a plain search or a regular expression -search, moves point to the end of the text that is found. In this -case, a successful search moves point to the end of the pattern for -@code{sp-parstart}. - -However, we want to put point at the end of the current paragraph, not -somewhere else. Indeed, since the search possibly includes the -paragraph separator, point may end up at the beginning of the next one -unless we use an expression that includes @code{match-beginning}. - -@findex match-beginning -When given an argument of 0, @code{match-beginning} returns the -position that is the start of the text matched by the most recent -search. In this case, the most recent search looks for -@code{sp-parstart}. The @code{(match-beginning 0)} expression returns -the beginning position of that pattern, rather than the end position -of that pattern. - -(Incidentally, when passed a positive number as an argument, the -@code{match-beginning} function returns the location of point at that -parenthesized expression in the last search unless that parenthesized -expression begins with @code{\(?:}. I don't know why @code{\(?:} -appears here since the argument is 0.) - -@need 1250 -The last expression when there is no fill prefix is - -@smallexample -@group -(if (< (point) (point-max)) - (goto-char start)))) -@end group -@end smallexample - -@noindent -This says that if there is no fill prefix and if we are not at the -end, point should move to the beginning of whatever was found by the -regular expression search for @code{sp-parstart}. - -The full definition for the @code{forward-paragraph} function not only -includes code for going forwards, but also code for going backwards. - -If you are reading this inside of GNU Emacs and you want to see the -whole function, you can type @kbd{C-h f} (@code{describe-function}) -and the name of the function. This gives you the function -documentation and the name of the library containing the function's -source. Place point over the name of the library and press the RET -key; you will be taken directly to the source. (Be sure to install -your sources! Without them, you are like a person who tries to drive -a car with his eyes shut!) - -@node etags, Regexp Review, forward-paragraph, Regexp Search -@section Create Your Own @file{TAGS} File -@findex etags -@cindex @file{TAGS} file, create own - -Besides @kbd{C-h f} (@code{describe-function}), another way to see the -source of a function is to type @kbd{M-.} (@code{find-tag}) and the -name of the function when prompted for it. This is a good habit to -get into. The @kbd{M-.} (@code{find-tag}) command takes you directly -to the source for a function, variable, or node. The function depends -on tags tables to tell it where to go. - -If the @code{find-tag} function first asks you for the name of a -@file{TAGS} table, give it the name of a @file{TAGS} file such as -@file{/usr/local/src/emacs/src/TAGS}. (The exact path to your -@file{TAGS} file depends on how your copy of Emacs was installed. I -just told you the location that provides both my C and my Emacs Lisp -sources.) - -You can also create your own @file{TAGS} file for directories that -lack one. - -You often need to build and install tags tables yourself. They are -not built automatically. A tags table is called a @file{TAGS} file; -the name is in upper case letters. - -You can create a @file{TAGS} file by calling the @code{etags} program -that comes as a part of the Emacs distribution. Usually, @code{etags} -is compiled and installed when Emacs is built. (@code{etags} is not -an Emacs Lisp function or a part of Emacs; it is a C program.) - -@need 1250 -To create a @file{TAGS} file, first switch to the directory in which -you want to create the file. In Emacs you can do this with the -@kbd{M-x cd} command, or by visiting a file in the directory, or by -listing the directory with @kbd{C-x d} (@code{dired}). Then run the -compile command, with @w{@code{etags *.el}} as the command to execute - -@smallexample -M-x compile RET etags *.el RET -@end smallexample - -@noindent -to create a @file{TAGS} file for Emacs Lisp. - -For example, if you have a large number of files in your -@file{~/emacs} directory, as I do---I have 137 @file{.el} files in it, -of which I load 12---you can create a @file{TAGS} file for the Emacs -Lisp files in that directory. - -@need 1250 -The @code{etags} program takes all the usual shell `wildcards'. For -example, if you have two directories for which you want a single -@file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where -@file{../elisp/} is the second directory: - -@smallexample -M-x compile RET etags *.el ../elisp/*.el RET -@end smallexample - -@need 1250 -Type - -@smallexample -M-x compile RET etags --help RET -@end smallexample - -@noindent -to see a list of the options accepted by @code{etags} as well as a -list of supported languages. - -The @code{etags} program handles more than 20 languages, including -Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java, -LaTeX, Pascal, Perl, Postscript, Python, TeX, Texinfo, makefiles, and -most assemblers. The program has no switches for specifying the -language; it recognizes the language in an input file according to its -file name and contents. - -@file{etags} is very helpful when you are writing code yourself and -want to refer back to functions you have already written. Just run -@code{etags} again at intervals as you write new functions, so they -become part of the @file{TAGS} file. - -If you think an appropriate @file{TAGS} file already exists for what -you want, but do not know where it is, you can use the @code{locate} -program to attempt to find it. - -Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list -for you the full path names of all your @file{TAGS} files. On my -system, this command lists 34 @file{TAGS} files. On the other hand, a -`plain vanilla' system I recently installed did not contain any -@file{TAGS} files. - -If the tags table you want has been created, you can use the @code{M-x -visit-tags-table} command to specify it. Otherwise, you will need to -create the tag table yourself and then use @code{M-x -visit-tags-table}. - -@subsubheading Building Tags in the Emacs sources -@cindex Building Tags in the Emacs sources -@cindex Tags in the Emacs sources -@findex make tags - -The GNU Emacs sources come with a @file{Makefile} that contains a -sophisticated @code{etags} command that creates, collects, and merges -tags tables from all over the Emacs sources and puts the information -into one @file{TAGS} file in the @file{src/} directory. (The -@file{src/} directory is below the top level of your Emacs directory.) - -@need 1250 -To build this @file{TAGS} file, go to the top level of your Emacs -source directory and run the compile command @code{make tags}: - -@smallexample -M-x compile RET make tags RET -@end smallexample - -@noindent -(The @code{make tags} command works well with the GNU Emacs sources, -as well as with some other source packages.) - -For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs -Manual}. - -@node Regexp Review, re-search Exercises, etags, Regexp Search -@comment node-name, next, previous, up -@section Review - -Here is a brief summary of some recently introduced functions. - -@table @code -@item while -Repeatedly evaluate the body of the expression so long as the first -element of the body tests true. Then return @code{nil}. (The -expression is evaluated only for its side effects.) - -@need 1250 -For example: - -@smallexample -@group -(let ((foo 2)) - (while (> foo 0) - (insert (format "foo is %d.\n" foo)) - (setq foo (1- foo)))) - - @result{} foo is 2. - foo is 1. - nil -@end group -@end smallexample - -@noindent -(The @code{insert} function inserts its arguments at point; the -@code{format} function returns a string formatted from its arguments -the way @code{message} formats its arguments; @code{\n} produces a new -line.) - -@item re-search-forward -Search for a pattern, and if the pattern is found, move point to rest -just after it. - -@noindent -Takes four arguments, like @code{search-forward}: - -@enumerate -@item -A regular expression that specifies the pattern to search for. -(Remember to put quotation marks around this argument!) - -@item -Optionally, the limit of the search. - -@item -Optionally, what to do if the search fails, return @code{nil} or an -error message. - -@item -Optionally, how many times to repeat the search; if negative, the -search goes backwards. -@end enumerate - -@item let* -Bind some variables locally to particular values, -and then evaluate the remaining arguments, returning the value of the -last one. While binding the local variables, use the local values of -variables bound earlier, if any. - -@need 1250 -For example: - -@smallexample -@group -(let* ((foo 7) - (bar (* 3 foo))) - (message "`bar' is %d." bar)) - @result{} `bar' is 21. -@end group -@end smallexample - -@item match-beginning -Return the position of the start of the text found by the last regular -expression search. - -@item looking-at -Return @code{t} for true if the text after point matches the argument, -which should be a regular expression. - -@item eobp -Return @code{t} for true if point is at the end of the accessible part -of a buffer. The end of the accessible part is the end of the buffer -if the buffer is not narrowed; it is the end of the narrowed part if -the buffer is narrowed. -@end table - -@need 1500 -@node re-search Exercises, , Regexp Review, Regexp Search -@section Exercises with @code{re-search-forward} - -@itemize @bullet -@item -Write a function to search for a regular expression that matches two -or more blank lines in sequence. - -@item -Write a function to search for duplicated words, such as `the the'. -@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs -Manual}, for information on how to write a regexp (a regular -expression) to match a string that is composed of two identical -halves. You can devise several regexps; some are better than others. -The function I use is described in an appendix, along with several -regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}. -@end itemize - -@node Counting Words, Words in a defun, Regexp Search, Top -@chapter Counting: Repetition and Regexps -@cindex Repetition for word counting -@cindex Regular expressions for word counting - -Repetition and regular expression searches are powerful tools that you -often use when you write code in Emacs Lisp. This chapter illustrates -the use of regular expression searches through the construction of -word count commands using @code{while} loops and recursion. - -@menu -* Why Count Words:: -* count-words-region:: Use a regexp, but find a problem. -* recursive-count-words:: Start with case of no words in region. -* Counting Exercise:: -@end menu - -@node Why Count Words, count-words-region, Counting Words, Counting Words -@ifnottex -@unnumberedsec Counting words -@end ifnottex - -The standard Emacs distribution contains a function for counting the -number of lines within a region. However, there is no corresponding -function for counting words. - -Certain types of writing ask you to count words. Thus, if you write -an essay, you may be limited to 800 words; if you write a novel, you -may discipline yourself to write 1000 words a day. It seems odd to me -that Emacs lacks a word count command. Perhaps people use Emacs -mostly for code or types of documentation that do not require word -counts; or perhaps they restrict themselves to the operating system -word count command, @code{wc}. Alternatively, people may follow -the publishers' convention and compute a word count by dividing the -number of characters in a document by five. In any event, here are -commands to count words. - -@node count-words-region, recursive-count-words, Why Count Words, Counting Words -@comment node-name, next, previous, up -@section The @code{count-words-region} Function -@findex count-words-region - -A word count command could count words in a line, paragraph, region, -or buffer. What should the command cover? You could design the -command to count the number of words in a complete buffer. However, -the Emacs tradition encourages flexibility---you may want to count -words in just a section, rather than all of a buffer. So it makes -more sense to design the command to count the number of words in a -region. Once you have a @code{count-words-region} command, you can, -if you wish, count words in a whole buffer by marking it with -@w{@kbd{C-x h}} (@code{mark-whole-buffer}). - -Clearly, counting words is a repetitive act: starting from the -beginning of the region, you count the first word, then the second -word, then the third word, and so on, until you reach the end of the -region. This means that word counting is ideally suited to recursion -or to a @code{while} loop. - -@menu -* Design count-words-region:: The definition using a @code{while} loop. -* Whitespace Bug:: The Whitespace Bug in @code{count-words-region}. -@end menu - -@node Design count-words-region, Whitespace Bug, count-words-region, count-words-region -@ifnottex -@unnumberedsubsec Designing @code{count-words-region} -@end ifnottex - -First, we will implement the word count command with a @code{while} -loop, then with recursion. The command will, of course, be -interactive. - -@need 800 -The template for an interactive function definition is, as always: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (@var{interactive-expression}@dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -What we need to do is fill in the slots. - -The name of the function should be self-explanatory and similar to the -existing @code{count-lines-region} name. This makes the name easier -to remember. @code{count-words-region} is a good choice. - -The function counts words within a region. This means that the -argument list must contain symbols that are bound to the two -positions, the beginning and end of the region. These two positions -can be called @samp{beginning} and @samp{end} respectively. The first -line of the documentation should be a single sentence, since that is -all that is printed as documentation by a command such as -@code{apropos}. The interactive expression will be of the form -@samp{(interactive "r")}, since that will cause Emacs to pass the -beginning and end of the region to the function's argument list. All -this is routine. - -The body of the function needs to be written to do three tasks: -first, to set up conditions under which the @code{while} loop can -count words, second, to run the @code{while} loop, and third, to send -a message to the user. - -When a user calls @code{count-words-region}, point may be at the -beginning or the end of the region. However, the counting process -must start at the beginning of the region. This means we will want -to put point there if it is not already there. Executing -@code{(goto-char beginning)} ensures this. Of course, we will want to -return point to its expected position when the function finishes its -work. For this reason, the body must be enclosed in a -@code{save-excursion} expression. - -The central part of the body of the function consists of a -@code{while} loop in which one expression jumps point forward word by -word, and another expression counts those jumps. The true-or-false-test -of the @code{while} loop should test true so long as point should jump -forward, and false when point is at the end of the region. - -We could use @code{(forward-word 1)} as the expression for moving point -forward word by word, but it is easier to see what Emacs identifies as a -`word' if we use a regular expression search. - -A regular expression search that finds the pattern for which it is -searching leaves point after the last character matched. This means -that a succession of successful word searches will move point forward -word by word. - -As a practical matter, we want the regular expression search to jump -over whitespace and punctuation between words as well as over the -words themselves. A regexp that refuses to jump over interword -whitespace would never jump more than one word! This means that -the regexp should include the whitespace and punctuation that follows -a word, if any, as well as the word itself. (A word may end a buffer -and not have any following whitespace or punctuation, so that part of -the regexp must be optional.) - -Thus, what we want for the regexp is a pattern defining one or more -word constituent characters followed, optionally, by one or more -characters that are not word constituents. The regular expression for -this is: - -@smallexample -\w+\W* -@end smallexample - -@noindent -The buffer's syntax table determines which characters are and are not -word constituents. (@xref{Syntax, , What Constitutes a Word or -Symbol?}, for more about syntax. Also, see @ref{Syntax, Syntax, The -Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , -Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.) - -@need 800 -The search expression looks like this: - -@smallexample -(re-search-forward "\\w+\\W*") -@end smallexample - -@noindent -(Note that paired backslashes precede the @samp{w} and @samp{W}. A -single backslash has special meaning to the Emacs Lisp interpreter. -It indicates that the following character is interpreted differently -than usual. For example, the two characters, @samp{\n}, stand for -@samp{newline}, rather than for a backslash followed by @samp{n}. Two -backslashes in a row stand for an ordinary, `unspecial' backslash, so -Emacs Lisp interpreter ends of seeing a single backslash followed by a -letter. So it discovers the letter is special.) - -We need a counter to count how many words there are; this variable -must first be set to 0 and then incremented each time Emacs goes -around the @code{while} loop. The incrementing expression is simply: - -@smallexample -(setq count (1+ count)) -@end smallexample - -Finally, we want to tell the user how many words there are in the -region. The @code{message} function is intended for presenting this -kind of information to the user. The message has to be phrased so -that it reads properly regardless of how many words there are in the -region: we don't want to say that ``there are 1 words in the region''. -The conflict between singular and plural is ungrammatical. We can -solve this problem by using a conditional expression that evaluates -different messages depending on the number of words in the region. -There are three possibilities: no words in the region, one word in the -region, and more than one word. This means that the @code{cond} -special form is appropriate. - -@need 1500 -All this leads to the following function definition: - -@smallexample -@group -;;; @r{First version; has bugs!} -(defun count-words-region (beginning end) - "Print number of words in the region. -Words are defined as at least one word-constituent -character followed by at least one character that -is not a word-constituent. The buffer's syntax -table determines which characters these are." - (interactive "r") - (message "Counting words in region ... ") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (save-excursion - (goto-char beginning) - (let ((count 0)) -@end group - -@group -;;; @r{2. Run the} while @r{loop.} - (while (< (point) end) - (re-search-forward "\\w+\\W*") - (setq count (1+ count))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message - "The region does NOT have any words.")) - ((= 1 count) - (message - "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -@noindent -As written, the function works, but not in all circumstances. - -@node Whitespace Bug, , Design count-words-region, count-words-region -@comment node-name, next, previous, up -@subsection The Whitespace Bug in @code{count-words-region} - -The @code{count-words-region} command described in the preceding -section has two bugs, or rather, one bug with two manifestations. -First, if you mark a region containing only whitespace in the middle -of some text, the @code{count-words-region} command tells you that the -region contains one word! Second, if you mark a region containing -only whitespace at the end of the buffer or the accessible portion of -a narrowed buffer, the command displays an error message that looks -like this: - -@smallexample -Search failed: "\\w+\\W*" -@end smallexample - -If you are reading this in Info in GNU Emacs, you can test for these -bugs yourself. - -First, evaluate the function in the usual manner to install it. -@ifinfo -Here is a copy of the definition. Place your cursor after the closing -parenthesis and type @kbd{C-x C-e} to install it. - -@smallexample -@group -;; @r{First version; has bugs!} -(defun count-words-region (beginning end) - "Print number of words in the region. -Words are defined as at least one word-constituent character followed -by at least one character that is not a word-constituent. The buffer's -syntax table determines which characters these are." -@end group -@group - (interactive "r") - (message "Counting words in region ... ") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (save-excursion - (goto-char beginning) - (let ((count 0)) -@end group - -@group -;;; @r{2. Run the} while @r{loop.} - (while (< (point) end) - (re-search-forward "\\w+\\W*") - (setq count (1+ count))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message "The region does NOT have any words.")) - ((= 1 count) (message "The region has 1 word.")) - (t (message "The region has %d words." count)))))) -@end group -@end smallexample -@end ifinfo - -@need 1000 -If you wish, you can also install this keybinding by evaluating it: - -@smallexample -(global-set-key "\C-c=" 'count-words-region) -@end smallexample - -To conduct the first test, set mark and point to the beginning and end -of the following line and then type @kbd{C-c =} (or @kbd{M-x -count-words-region} if you have not bound @kbd{C-c =}): - -@smallexample - one two three -@end smallexample - -@noindent -Emacs will tell you, correctly, that the region has three words. - -Repeat the test, but place mark at the beginning of the line and place -point just @emph{before} the word @samp{one}. Again type the command -@kbd{C-c =} (or @kbd{M-x count-words-region}). Emacs should tell you -that the region has no words, since it is composed only of the -whitespace at the beginning of the line. But instead Emacs tells you -that the region has one word! - -For the third test, copy the sample line to the end of the -@file{*scratch*} buffer and then type several spaces at the end of the -line. Place mark right after the word @samp{three} and point at the -end of line. (The end of the line will be the end of the buffer.) -Type @kbd{C-c =} (or @kbd{M-x count-words-region}) as you did before. -Again, Emacs should tell you that the region has no words, since it is -composed only of the whitespace at the end of the line. Instead, -Emacs displays an error message saying @samp{Search failed}. - -The two bugs stem from the same problem. - -Consider the first manifestation of the bug, in which the command -tells you that the whitespace at the beginning of the line contains -one word. What happens is this: The @code{M-x count-words-region} -command moves point to the beginning of the region. The @code{while} -tests whether the value of point is smaller than the value of -@code{end}, which it is. Consequently, the regular expression search -looks for and finds the first word. It leaves point after the word. -@code{count} is set to one. The @code{while} loop repeats; but this -time the value of point is larger than the value of @code{end}, the -loop is exited; and the function displays a message saying the number -of words in the region is one. In brief, the regular expression -search looks for and finds the word even though it is outside -the marked region. - -In the second manifestation of the bug, the region is whitespace at -the end of the buffer. Emacs says @samp{Search failed}. What happens -is that the true-or-false-test in the @code{while} loop tests true, so -the search expression is executed. But since there are no more words -in the buffer, the search fails. - -In both manifestations of the bug, the search extends or attempts to -extend outside of the region. - -The solution is to limit the search to the region---this is a fairly -simple action, but as you may have come to expect, it is not quite as -simple as you might think. - -As we have seen, the @code{re-search-forward} function takes a search -pattern as its first argument. But in addition to this first, -mandatory argument, it accepts three optional arguments. The optional -second argument bounds the search. The optional third argument, if -@code{t}, causes the function to return @code{nil} rather than signal -an error if the search fails. The optional fourth argument is a -repeat count. (In Emacs, you can see a function's documentation by -typing @kbd{C-h f}, the name of the function, and then @key{RET}.) - -In the @code{count-words-region} definition, the value of the end of -the region is held by the variable @code{end} which is passed as an -argument to the function. Thus, we can add @code{end} as an argument -to the regular expression search expression: - -@smallexample -(re-search-forward "\\w+\\W*" end) -@end smallexample - -However, if you make only this change to the @code{count-words-region} -definition and then test the new version of the definition on a -stretch of whitespace, you will receive an error message saying -@samp{Search failed}. - -What happens is this: the search is limited to the region, and fails -as you expect because there are no word-constituent characters in the -region. Since it fails, we receive an error message. But we do not -want to receive an error message in this case; we want to receive the -message that "The region does NOT have any words." - -The solution to this problem is to provide @code{re-search-forward} -with a third argument of @code{t}, which causes the function to return -@code{nil} rather than signal an error if the search fails. - -However, if you make this change and try it, you will see the message -``Counting words in region ... '' and @dots{} you will keep on seeing -that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}). - -Here is what happens: the search is limited to the region, as before, -and it fails because there are no word-constituent characters in the -region, as expected. Consequently, the @code{re-search-forward} -expression returns @code{nil}. It does nothing else. In particular, -it does not move point, which it does as a side effect if it finds the -search target. After the @code{re-search-forward} expression returns -@code{nil}, the next expression in the @code{while} loop is evaluated. -This expression increments the count. Then the loop repeats. The -true-or-false-test tests true because the value of point is still less -than the value of end, since the @code{re-search-forward} expression -did not move point. @dots{} and the cycle repeats @dots{} - -The @code{count-words-region} definition requires yet another -modification, to cause the true-or-false-test of the @code{while} loop -to test false if the search fails. Put another way, there are two -conditions that must be satisfied in the true-or-false-test before the -word count variable is incremented: point must still be within the -region and the search expression must have found a word to count. - -Since both the first condition and the second condition must be true -together, the two expressions, the region test and the search -expression, can be joined with an @code{and} special form and embedded in -the @code{while} loop as the true-or-false-test, like this: - -@smallexample -(and (< (point) end) (re-search-forward "\\w+\\W*" end t)) -@end smallexample - -@c colon in printed section title causes problem in Info cross reference -@c also trouble with an overfull hbox -@iftex -@noindent -(For information about @code{and}, see -@ref{kill-new function, , The @code{kill-new} function}.) -@end iftex -@ifinfo -@noindent -(@xref{kill-new function, , The @code{kill-new} function}, for -information about @code{and}.) -@end ifinfo - -The @code{re-search-forward} expression returns @code{t} if the search -succeeds and as a side effect moves point. Consequently, as words are -found, point is moved through the region. When the search expression -fails to find another word, or when point reaches the end of the -region, the true-or-false-test tests false, the @code{while} loop -exits, and the @code{count-words-region} function displays one or -other of its messages. - -After incorporating these final changes, the @code{count-words-region} -works without bugs (or at least, without bugs that I have found!). -Here is what it looks like: - -@smallexample -@group -;;; @r{Final version:} @code{while} -(defun count-words-region (beginning end) - "Print number of words in the region." - (interactive "r") - (message "Counting words in region ... ") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (save-excursion - (let ((count 0)) - (goto-char beginning) -@end group - -@group -;;; @r{2. Run the} while @r{loop.} - (while (and (< (point) end) - (re-search-forward "\\w+\\W*" end t)) - (setq count (1+ count))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message - "The region does NOT have any words.")) - ((= 1 count) - (message - "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -@node recursive-count-words, Counting Exercise, count-words-region, Counting Words -@comment node-name, next, previous, up -@section Count Words Recursively -@cindex Count words recursively -@cindex Recursively counting words -@cindex Words, counted recursively - -You can write the function for counting words recursively as well as -with a @code{while} loop. Let's see how this is done. - -First, we need to recognize that the @code{count-words-region} -function has three jobs: it sets up the appropriate conditions for -counting to occur; it counts the words in the region; and it sends a -message to the user telling how many words there are. - -If we write a single recursive function to do everything, we will -receive a message for every recursive call. If the region contains 13 -words, we will receive thirteen messages, one right after the other. -We don't want this! Instead, we must write two functions to do the -job, one of which (the recursive function) will be used inside of the -other. One function will set up the conditions and display the -message; the other will return the word count. - -Let us start with the function that causes the message to be displayed. -We can continue to call this @code{count-words-region}. - -This is the function that the user will call. It will be interactive. -Indeed, it will be similar to our previous versions of this -function, except that it will call @code{recursive-count-words} to -determine how many words are in the region. - -@need 1250 -We can readily construct a template for this function, based on our -previous versions: - -@smallexample -@group -;; @r{Recursive version; uses regular expression search} -(defun count-words-region (beginning end) - "@var{documentation}@dots{}" - (@var{interactive-expression}@dots{}) -@end group -@group - -;;; @r{1. Set up appropriate conditions.} - (@var{explanatory message}) - (@var{set-up functions}@dots{} -@end group -@group - -;;; @r{2. Count the words.} - @var{recursive call} -@end group -@group - -;;; @r{3. Send a message to the user.} - @var{message providing word count})) -@end group -@end smallexample - -The definition looks straightforward, except that somehow the count -returned by the recursive call must be passed to the message -displaying the word count. A little thought suggests that this can be -done by making use of a @code{let} expression: we can bind a variable -in the varlist of a @code{let} expression to the number of words in -the region, as returned by the recursive call; and then the -@code{cond} expression, using binding, can display the value to the -user. - -Often, one thinks of the binding within a @code{let} expression as -somehow secondary to the `primary' work of a function. But in this -case, what you might consider the `primary' job of the function, -counting words, is done within the @code{let} expression. - -@need 1250 -Using @code{let}, the function definition looks like this: - -@smallexample -@group -(defun count-words-region (beginning end) - "Print number of words in the region." - (interactive "r") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (message "Counting words in region ... ") - (save-excursion - (goto-char beginning) -@end group - -@group -;;; @r{2. Count the words.} - (let ((count (recursive-count-words end))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message - "The region does NOT have any words.")) - ((= 1 count) - (message - "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -Next, we need to write the recursive counting function. - -A recursive function has at least three parts: the `do-again-test', the -`next-step-expression', and the recursive call. - -The do-again-test determines whether the function will or will not be -called again. Since we are counting words in a region and can use a -function that moves point forward for every word, the do-again-test -can check whether point is still within the region. The do-again-test -should find the value of point and determine whether point is before, -at, or after the value of the end of the region. We can use the -@code{point} function to locate point. Clearly, we must pass the -value of the end of the region to the recursive counting function as an -argument. - -In addition, the do-again-test should also test whether the search finds a -word. If it does not, the function should not call itself again. - -The next-step-expression changes a value so that when the recursive -function is supposed to stop calling itself, it stops. More -precisely, the next-step-expression changes a value so that at the -right time, the do-again-test stops the recursive function from -calling itself again. In this case, the next-step-expression can be -the expression that moves point forward, word by word. - -The third part of a recursive function is the recursive call. - -Somewhere, also, we also need a part that does the `work' of the -function, a part that does the counting. A vital part! - -@need 1250 -But already, we have an outline of the recursive counting function: - -@smallexample -@group -(defun recursive-count-words (region-end) - "@var{documentation}@dots{}" - @var{do-again-test} - @var{next-step-expression} - @var{recursive call}) -@end group -@end smallexample - -Now we need to fill in the slots. Let's start with the simplest cases -first: if point is at or beyond the end of the region, there cannot -be any words in the region, so the function should return zero. -Likewise, if the search fails, there are no words to count, so the -function should return zero. - -On the other hand, if point is within the region and the search -succeeds, the function should call itself again. - -@need 800 -Thus, the do-again-test should look like this: - -@smallexample -@group -(and (< (point) region-end) - (re-search-forward "\\w+\\W*" region-end t)) -@end group -@end smallexample - -Note that the search expression is part of the do-again-test---the -function returns @code{t} if its search succeeds and @code{nil} if it -fails. (@xref{Whitespace Bug, , The Whitespace Bug in -@code{count-words-region}}, for an explanation of how -@code{re-search-forward} works.) - -The do-again-test is the true-or-false test of an @code{if} clause. -Clearly, if the do-again-test succeeds, the then-part of the @code{if} -clause should call the function again; but if it fails, the else-part -should return zero since either point is outside the region or the -search failed because there were no words to find. - -But before considering the recursive call, we need to consider the -next-step-expression. What is it? Interestingly, it is the search -part of the do-again-test. - -In addition to returning @code{t} or @code{nil} for the -do-again-test, @code{re-search-forward} moves point forward as a side -effect of a successful search. This is the action that changes the -value of point so that the recursive function stops calling itself -when point completes its movement through the region. Consequently, -the @code{re-search-forward} expression is the next-step-expression. - -@need 1200 -In outline, then, the body of the @code{recursive-count-words} -function looks like this: - -@smallexample -@group -(if @var{do-again-test-and-next-step-combined} - ;; @r{then} - @var{recursive-call-returning-count} - ;; @r{else} - @var{return-zero}) -@end group -@end smallexample - -How to incorporate the mechanism that counts? - -If you are not used to writing recursive functions, a question like -this can be troublesome. But it can and should be approached -systematically. - -We know that the counting mechanism should be associated in some way -with the recursive call. Indeed, since the next-step-expression moves -point forward by one word, and since a recursive call is made for -each word, the counting mechanism must be an expression that adds one -to the value returned by a call to @code{recursive-count-words}. - -@need 800 -Consider several cases: - -@itemize @bullet -@item -If there are two words in the region, the function should return -a value resulting from adding one to the value returned when it counts -the first word, plus the number returned when it counts the remaining -words in the region, which in this case is one. - -@item -If there is one word in the region, the function should return -a value resulting from adding one to the value returned when it counts -that word, plus the number returned when it counts the remaining -words in the region, which in this case is zero. - -@item -If there are no words in the region, the function should return zero. -@end itemize - -From the sketch we can see that the else-part of the @code{if} returns -zero for the case of no words. This means that the then-part of the -@code{if} must return a value resulting from adding one to the value -returned from a count of the remaining words. - -@need 1200 -The expression will look like this, where @code{1+} is a function that -adds one to its argument. - -@smallexample -(1+ (recursive-count-words region-end)) -@end smallexample - -@need 1200 -The whole @code{recursive-count-words} function will then look like -this: - -@smallexample -@group -(defun recursive-count-words (region-end) - "@var{documentation}@dots{}" - -;;; @r{1. do-again-test} - (if (and (< (point) region-end) - (re-search-forward "\\w+\\W*" region-end t)) -@end group - -@group -;;; @r{2. then-part: the recursive call} - (1+ (recursive-count-words region-end)) - -;;; @r{3. else-part} - 0)) -@end group -@end smallexample - -@need 1250 -Let's examine how this works: - -If there are no words in the region, the else part of the @code{if} -expression is evaluated and consequently the function returns zero. - -If there is one word in the region, the value of point is less than -the value of @code{region-end} and the search succeeds. In this case, -the true-or-false-test of the @code{if} expression tests true, and the -then-part of the @code{if} expression is evaluated. The counting -expression is evaluated. This expression returns a value (which will -be the value returned by the whole function) that is the sum of one -added to the value returned by a recursive call. - -Meanwhile, the next-step-expression has caused point to jump over the -first (and in this case only) word in the region. This means that -when @code{(recursive-count-words region-end)} is evaluated a second -time, as a result of the recursive call, the value of point will be -equal to or greater than the value of region end. So this time, -@code{recursive-count-words} will return zero. The zero will be added -to one, and the original evaluation of @code{recursive-count-words} -will return one plus zero, which is one, which is the correct amount. - -Clearly, if there are two words in the region, the first call to -@code{recursive-count-words} returns one added to the value returned -by calling @code{recursive-count-words} on a region containing the -remaining word---that is, it adds one to one, producing two, which is -the correct amount. - -Similarly, if there are three words in the region, the first call to -@code{recursive-count-words} returns one added to the value returned -by calling @code{recursive-count-words} on a region containing the -remaining two words---and so on and so on. - -@need 1250 -@noindent -With full documentation the two functions look like this: - -@need 1250 -@noindent -The recursive function: - -@findex recursive-count-words -@smallexample -@group -(defun recursive-count-words (region-end) - "Number of words between point and REGION-END." -@end group - -@group -;;; @r{1. do-again-test} - (if (and (< (point) region-end) - (re-search-forward "\\w+\\W*" region-end t)) -@end group - -@group -;;; @r{2. then-part: the recursive call} - (1+ (recursive-count-words region-end)) - -;;; @r{3. else-part} - 0)) -@end group -@end smallexample - -@need 800 -@noindent -The wrapper: - -@smallexample -@group -;;; @r{Recursive version} -(defun count-words-region (beginning end) - "Print number of words in the region. -@end group - -@group -Words are defined as at least one word-constituent -character followed by at least one character that is -not a word-constituent. The buffer's syntax table -determines which characters these are." -@end group -@group - (interactive "r") - (message "Counting words in region ... ") - (save-excursion - (goto-char beginning) - (let ((count (recursive-count-words end))) -@end group -@group - (cond ((zerop count) - (message - "The region does NOT have any words.")) -@end group -@group - ((= 1 count) - (message "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -@node Counting Exercise, , recursive-count-words, Counting Words -@section Exercise: Counting Punctuation - -Using a @code{while} loop, write a function to count the number of -punctuation marks in a region---period, comma, semicolon, colon, -exclamation mark, and question mark. Do the same using recursion. - -@node Words in a defun, Readying a Graph, Counting Words, Top -@chapter Counting Words in a @code{defun} -@cindex Counting words in a @code{defun} -@cindex Word counting in a @code{defun} - -Our next project is to count the number of words in a function -definition. Clearly, this can be done using some variant of -@code{count-word-region}. @xref{Counting Words, , Counting Words: -Repetition and Regexps}. If we are just going to count the words in -one definition, it is easy enough to mark the definition with the -@kbd{C-M-h} (@code{mark-defun}) command, and then call -@code{count-word-region}. - -However, I am more ambitious: I want to count the words and symbols in -every definition in the Emacs sources and then print a graph that -shows how many functions there are of each length: how many contain 40 -to 49 words or symbols, how many contain 50 to 59 words or symbols, -and so on. I have often been curious how long a typical function is, -and this will tell. - -@menu -* Divide and Conquer:: -* Words and Symbols:: What to count? -* Syntax:: What constitutes a word or symbol? -* count-words-in-defun:: Very like @code{count-words}. -* Several defuns:: Counting several defuns in a file. -* Find a File:: Do you want to look at a file? -* lengths-list-file:: A list of the lengths of many definitions. -* Several files:: Counting in definitions in different files. -* Several files recursively:: Recursively counting in different files. -* Prepare the data:: Prepare the data for display in a graph. -@end menu - -@node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun -@ifnottex -@unnumberedsec Divide and Conquer -@end ifnottex - -Described in one phrase, the histogram project is daunting; but -divided into numerous small steps, each of which we can take one at a -time, the project becomes less fearsome. Let us consider what the -steps must be: - -@itemize @bullet -@item -First, write a function to count the words in one definition. This -includes the problem of handling symbols as well as words. - -@item -Second, write a function to list the numbers of words in each function -in a file. This function can use the @code{count-words-in-defun} -function. - -@item -Third, write a function to list the numbers of words in each function -in each of several files. This entails automatically finding the -various files, switching to them, and counting the words in the -definitions within them. - -@item -Fourth, write a function to convert the list of numbers that we -created in step three to a form that will be suitable for printing as -a graph. - -@item -Fifth, write a function to print the results as a graph. -@end itemize - -This is quite a project! But if we take each step slowly, it will not -be difficult. - -@node Words and Symbols, Syntax, Divide and Conquer, Words in a defun -@section What to Count? -@cindex Words and symbols in defun - -When we first start thinking about how to count the words in a -function definition, the first question is (or ought to be) what are -we going to count? When we speak of `words' with respect to a Lisp -function definition, we are actually speaking, in large part, of -`symbols'. For example, the following @code{multiply-by-seven} -function contains the five symbols @code{defun}, -@code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In -addition, in the documentation string, it contains the four words -@samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The -symbol @samp{number} is repeated, so the definition contains a total -of ten words and symbols. - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) -@end group -@end smallexample - -@noindent -However, if we mark the @code{multiply-by-seven} definition with -@kbd{C-M-h} (@code{mark-defun}), and then call -@code{count-words-region} on it, we will find that -@code{count-words-region} claims the definition has eleven words, not -ten! Something is wrong! - -The problem is twofold: @code{count-words-region} does not count the -@samp{*} as a word, and it counts the single symbol, -@code{multiply-by-seven}, as containing three words. The hyphens are -treated as if they were interword spaces rather than intraword -connectors: @samp{multiply-by-seven} is counted as if it were written -@samp{multiply by seven}. - -The cause of this confusion is the regular expression search within -the @code{count-words-region} definition that moves point forward word -by word. In the canonical version of @code{count-words-region}, the -regexp is: - -@smallexample -"\\w+\\W*" -@end smallexample - -@noindent -This regular expression is a pattern defining one or more word -constituent characters possibly followed by one or more characters -that are not word constituents. What is meant by `word constituent -characters' brings us to the issue of syntax, which is worth a section -of its own. - -@node Syntax, count-words-in-defun, Words and Symbols, Words in a defun -@section What Constitutes a Word or Symbol? -@cindex Syntax categories and tables - -Emacs treats different characters as belonging to different -@dfn{syntax categories}. For example, the regular expression, -@samp{\\w+}, is a pattern specifying one or more @emph{word -constituent} characters. Word constituent characters are members of -one syntax category. Other syntax categories include the class of -punctuation characters, such as the period and the comma, and the -class of whitespace characters, such as the blank space and the tab -character. (For more information, see @ref{Syntax, Syntax, The Syntax -Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , Syntax -Tables, elisp, The GNU Emacs Lisp Reference Manual}.) - -Syntax tables specify which characters belong to which categories. -Usually, a hyphen is not specified as a `word constituent character'. -Instead, it is specified as being in the `class of characters that are -part of symbol names but not words.' This means that the -@code{count-words-region} function treats it in the same way it treats -an interword white space, which is why @code{count-words-region} -counts @samp{multiply-by-seven} as three words. - -There are two ways to cause Emacs to count @samp{multiply-by-seven} as -one symbol: modify the syntax table or modify the regular expression. - -We could redefine a hyphen as a word constituent character by -modifying the syntax table that Emacs keeps for each mode. This -action would serve our purpose, except that a hyphen is merely the -most common character within symbols that is not typically a word -constituent character; there are others, too. - -Alternatively, we can redefine the regular expression used in the -@code{count-words} definition so as to include symbols. This -procedure has the merit of clarity, but the task is a little tricky. - -@need 1200 -The first part is simple enough: the pattern must match ``at least one -character that is a word or symbol constituent''. Thus: - -@smallexample -"\\(\\w\\|\\s_\\)+" -@end smallexample - -@noindent -The @samp{\\(} is the first part of the grouping construct that -includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated -by the @samp{\\|}. The @samp{\\w} matches any word-constituent -character and the @samp{\\s_} matches any character that is part of a -symbol name but not a word-constituent character. The @samp{+} -following the group indicates that the word or symbol constituent -characters must be matched at least once. - -However, the second part of the regexp is more difficult to design. -What we want is to follow the first part with ``optionally one or more -characters that are not constituents of a word or symbol''. At first, -I thought I could define this with the following: - -@smallexample -"\\(\\W\\|\\S_\\)*" -@end smallexample - -@noindent -The upper case @samp{W} and @samp{S} match characters that are -@emph{not} word or symbol constituents. Unfortunately, this -expression matches any character that is either not a word constituent -or not a symbol constituent. This matches any character! - -I then noticed that every word or symbol in my test region was -followed by white space (blank space, tab, or newline). So I tried -placing a pattern to match one or more blank spaces after the pattern -for one or more word or symbol constituents. This failed, too. Words -and symbols are often separated by whitespace, but in actual code -parentheses may follow symbols and punctuation may follow words. So -finally, I designed a pattern in which the word or symbol constituents -are followed optionally by characters that are not white space and -then followed optionally by white space. - -@need 800 -Here is the full regular expression: - -@smallexample -"\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" -@end smallexample - -@node count-words-in-defun, Several defuns, Syntax, Words in a defun -@section The @code{count-words-in-defun} Function -@cindex Counting words in a @code{defun} - -We have seen that there are several ways to write a -@code{count-word-region} function. To write a -@code{count-words-in-defun}, we need merely adapt one of these -versions. - -The version that uses a @code{while} loop is easy to understand, so I -am going to adapt that. Because @code{count-words-in-defun} will be -part of a more complex program, it need not be interactive and it need -not display a message but just return the count. These considerations -simplify the definition a little. - -On the other hand, @code{count-words-in-defun} will be used within a -buffer that contains function definitions. Consequently, it is -reasonable to ask that the function determine whether it is called -when point is within a function definition, and if it is, to return -the count for that definition. This adds complexity to the -definition, but saves us from needing to pass arguments to the -function. - -@need 1250 -These considerations lead us to prepare the following template: - -@smallexample -@group -(defun count-words-in-defun () - "@var{documentation}@dots{}" - (@var{set up}@dots{} - (@var{while loop}@dots{}) - @var{return count}) -@end group -@end smallexample - -@noindent -As usual, our job is to fill in the slots. - -First, the set up. - -We are presuming that this function will be called within a buffer -containing function definitions. Point will either be within a -function definition or not. For @code{count-words-in-defun} to work, -point must move to the beginning of the definition, a counter must -start at zero, and the counting loop must stop when point reaches the -end of the definition. - -The @code{beginning-of-defun} function searches backwards for an -opening delimiter such as a @samp{(} at the beginning of a line, and -moves point to that position, or else to the limit of the search. In -practice, this means that @code{beginning-of-defun} moves point to the -beginning of an enclosing or preceding function definition, or else to -the beginning of the buffer. We can use @code{beginning-of-defun} to -place point where we wish to start. - -The @code{while} loop requires a counter to keep track of the words or -symbols being counted. A @code{let} expression can be used to create -a local variable for this purpose, and bind it to an initial value of zero. - -The @code{end-of-defun} function works like @code{beginning-of-defun} -except that it moves point to the end of the definition. -@code{end-of-defun} can be used as part of an expression that -determines the position of the end of the definition. - -The set up for @code{count-words-in-defun} takes shape rapidly: first -we move point to the beginning of the definition, then we create a -local variable to hold the count, and finally, we record the position -of the end of the definition so the @code{while} loop will know when to stop -looping. - -@need 1250 -The code looks like this: - -@smallexample -@group -(beginning-of-defun) -(let ((count 0) - (end (save-excursion (end-of-defun) (point)))) -@end group -@end smallexample - -@noindent -The code is simple. The only slight complication is likely to concern -@code{end}: it is bound to the position of the end of the definition -by a @code{save-excursion} expression that returns the value of point -after @code{end-of-defun} temporarily moves it to the end of the -definition. - -The second part of the @code{count-words-in-defun}, after the set up, -is the @code{while} loop. - -The loop must contain an expression that jumps point forward word by -word and symbol by symbol, and another expression that counts the -jumps. The true-or-false-test for the @code{while} loop should test -true so long as point should jump forward, and false when point is at -the end of the definition. We have already redefined the regular -expression for this (@pxref{Syntax}), so the loop is straightforward: - -@smallexample -@group -(while (and (< (point) end) - (re-search-forward - "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t) - (setq count (1+ count))) -@end group -@end smallexample - -The third part of the function definition returns the count of words -and symbols. This part is the last expression within the body of the -@code{let} expression, and can be, very simply, the local variable -@code{count}, which when evaluated returns the count. - -@need 1250 -Put together, the @code{count-words-in-defun} definition looks like this: - -@findex count-words-in-defun -@smallexample -@group -(defun count-words-in-defun () - "Return the number of words and symbols in a defun." - (beginning-of-defun) - (let ((count 0) - (end (save-excursion (end-of-defun) (point)))) -@end group -@group - (while - (and (< (point) end) - (re-search-forward - "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" - end t)) - (setq count (1+ count))) - count)) -@end group -@end smallexample - -How to test this? The function is not interactive, but it is easy to -put a wrapper around the function to make it interactive; we can use -almost the same code as for the recursive version of -@code{count-words-region}: - -@smallexample -@group -;;; @r{Interactive version.} -(defun count-words-defun () - "Number of words and symbols in a function definition." - (interactive) - (message - "Counting words and symbols in function definition ... ") -@end group -@group - (let ((count (count-words-in-defun))) - (cond - ((zerop count) - (message - "The definition does NOT have any words or symbols.")) -@end group -@group - ((= 1 count) - (message - "The definition has 1 word or symbol.")) - (t - (message - "The definition has %d words or symbols." count))))) -@end group -@end smallexample - -@need 800 -@noindent -Let's re-use @kbd{C-c =} as a convenient keybinding: - -@smallexample -(global-set-key "\C-c=" 'count-words-defun) -@end smallexample - -Now we can try out @code{count-words-defun}: install both -@code{count-words-in-defun} and @code{count-words-defun}, and set the -keybinding, and then place the cursor within the following definition: - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) - @result{} 10 -@end group -@end smallexample - -@noindent -Success! The definition has 10 words and symbols. - -The next problem is to count the numbers of words and symbols in -several definitions within a single file. - -@node Several defuns, Find a File, count-words-in-defun, Words in a defun -@section Count Several @code{defuns} Within a File - -A file such as @file{simple.el} may have a hundred or more function -definitions within it. Our long term goal is to collect statistics on -many files, but as a first step, our immediate goal is to collect -statistics on one file. - -The information will be a series of numbers, each number being the -length of a function definition. We can store the numbers in a list. - -We know that we will want to incorporate the information regarding one -file with information about many other files; this means that the -function for counting definition lengths within one file need only -return the list of lengths. It need not and should not display any -messages. - -The word count commands contain one expression to jump point forward -word by word and another expression to count the jumps. The function -to return the lengths of definitions can be designed to work the same -way, with one expression to jump point forward definition by -definition and another expression to construct the lengths' list. - -This statement of the problem makes it elementary to write the -function definition. Clearly, we will start the count at the -beginning of the file, so the first command will be @code{(goto-char -(point-min))}. Next, we start the @code{while} loop; and the -true-or-false test of the loop can be a regular expression search for -the next function definition---so long as the search succeeds, point -is moved forward and then the body of the loop is evaluated. The body -needs an expression that constructs the lengths' list. @code{cons}, -the list construction command, can be used to create the list. That -is almost all there is to it. - -@need 800 -Here is what this fragment of code looks like: - -@smallexample -@group -(goto-char (point-min)) -(while (re-search-forward "^(defun" nil t) - (setq lengths-list - (cons (count-words-in-defun) lengths-list))) -@end group -@end smallexample - -What we have left out is the mechanism for finding the file that -contains the function definitions. - -In previous examples, we either used this, the Info file, or we -switched back and forth to some other buffer, such as the -@file{*scratch*} buffer. - -Finding a file is a new process that we have not yet discussed. - -@node Find a File, lengths-list-file, Several defuns, Words in a defun -@comment node-name, next, previous, up -@section Find a File -@cindex Find a File - -To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file}) -command. This command is almost, but not quite right for the lengths -problem. - -@need 1200 -Let's look at the source for @code{find-file}: - -@smallexample -@group -(defun find-file (filename) - "Edit file FILENAME. -Switch to a buffer visiting file FILENAME, -creating one if none already exists." - (interactive "FFind file: ") - (switch-to-buffer (find-file-noselect filename))) -@end group -@end smallexample - -@noindent -(The most recent version of the @code{find-file} function definition -permits you to specify optional wildcards to visit multiple files; that -makes the definition more complex and we will not discuss it here, -since it is not relevant. You can see its source using either -@kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).) - -@ignore -In Emacs 22 -(defun find-file (filename &optional wildcards) - "Edit file FILENAME. -Switch to a buffer visiting file FILENAME, -creating one if none already exists. -Interactively, the default if you just type RET is the current directory, -but the visited file name is available through the minibuffer history: -type M-n to pull it into the minibuffer. - -Interactively, or if WILDCARDS is non-nil in a call from Lisp, -expand wildcards (if any) and visit multiple files. You can -suppress wildcard expansion by setting `find-file-wildcards' to nil. - -To visit a file without any kind of conversion and without -automatically choosing a major mode, use \\[find-file-literally]." - (interactive (find-file-read-args "Find file: " nil)) - (let ((value (find-file-noselect filename nil nil wildcards))) - (if (listp value) - (mapcar 'switch-to-buffer (nreverse value)) - (switch-to-buffer value)))) -@end ignore - -The definition I am showing possesses short but complete documentation -and an interactive specification that prompts you for a file name when -you use the command interactively. The body of the definition -contains two functions, @code{find-file-noselect} and -@code{switch-to-buffer}. - -According to its documentation as shown by @kbd{C-h f} (the -@code{describe-function} command), the @code{find-file-noselect} -function reads the named file into a buffer and returns the buffer. -(Its most recent version includes an optional wildcards argument, -too, as well as another to read a file literally and an other you -suppress warning messages. These optional arguments are irrelevant.) - -However, the @code{find-file-noselect} function does not select the -buffer in which it puts the file. Emacs does not switch its attention -(or yours if you are using @code{find-file-noselect}) to the selected -buffer. That is what @code{switch-to-buffer} does: it switches the -buffer to which Emacs attention is directed; and it switches the -buffer displayed in the window to the new buffer. We have discussed -buffer switching elsewhere. (@xref{Switching Buffers}.) - -In this histogram project, we do not need to display each file on the -screen as the program determines the length of each definition within -it. Instead of employing @code{switch-to-buffer}, we can work with -@code{set-buffer}, which redirects the attention of the computer -program to a different buffer but does not redisplay it on the screen. -So instead of calling on @code{find-file} to do the job, we must write -our own expression. - -The task is easy: use @code{find-file-noselect} and @code{set-buffer}. - -@node lengths-list-file, Several files, Find a File, Words in a defun -@section @code{lengths-list-file} in Detail - -The core of the @code{lengths-list-file} function is a @code{while} -loop containing a function to move point forward `defun by defun' and -a function to count the number of words and symbols in each defun. -This core must be surrounded by functions that do various other tasks, -including finding the file, and ensuring that point starts out at the -beginning of the file. The function definition looks like this: -@findex lengths-list-file - -@smallexample -@group -(defun lengths-list-file (filename) - "Return list of definitions' lengths within FILE. -The returned list is a list of numbers. -Each number is the number of words or -symbols in one function definition." -@end group -@group - (message "Working on `%s' ... " filename) - (save-excursion - (let ((buffer (find-file-noselect filename)) - (lengths-list)) - (set-buffer buffer) - (setq buffer-read-only t) - (widen) - (goto-char (point-min)) - (while (re-search-forward "^(defun" nil t) - (setq lengths-list - (cons (count-words-in-defun) lengths-list))) - (kill-buffer buffer) - lengths-list))) -@end group -@end smallexample - -@noindent -The function is passed one argument, the name of the file on which it -will work. It has four lines of documentation, but no interactive -specification. Since people worry that a computer is broken if they -don't see anything going on, the first line of the body is a -message. - -The next line contains a @code{save-excursion} that returns Emacs' -attention to the current buffer when the function completes. This is -useful in case you embed this function in another function that -presumes point is restored to the original buffer. - -In the varlist of the @code{let} expression, Emacs finds the file and -binds the local variable @code{buffer} to the buffer containing the -file. At the same time, Emacs creates @code{lengths-list} as a local -variable. - -Next, Emacs switches its attention to the buffer. - -In the following line, Emacs makes the buffer read-only. Ideally, -this line is not necessary. None of the functions for counting words -and symbols in a function definition should change the buffer. -Besides, the buffer is not going to be saved, even if it were changed. -This line is entirely the consequence of great, perhaps excessive, -caution. The reason for the caution is that this function and those -it calls work on the sources for Emacs and it is inconvenient if they -are inadvertently modified. It goes without saying that I did not -realize a need for this line until an experiment went awry and started -to modify my Emacs source files @dots{} - -Next comes a call to widen the buffer if it is narrowed. This -function is usually not needed---Emacs creates a fresh buffer if none -already exists; but if a buffer visiting the file already exists Emacs -returns that one. In this case, the buffer may be narrowed and must -be widened. If we wanted to be fully `user-friendly', we would -arrange to save the restriction and the location of point, but we -won't. - -The @code{(goto-char (point-min))} expression moves point to the -beginning of the buffer. - -Then comes a @code{while} loop in which the `work' of the function is -carried out. In the loop, Emacs determines the length of each -definition and constructs a lengths' list containing the information. - -Emacs kills the buffer after working through it. This is to save -space inside of Emacs. My version of GNU Emacs 19 contained over 300 -source files of interest; GNU Emacs 22 contains over a thousand source -files. Another function will apply @code{lengths-list-file} to each -of the files. - -Finally, the last expression within the @code{let} expression is the -@code{lengths-list} variable; its value is returned as the value of -the whole function. - -You can try this function by installing it in the usual fashion. Then -place your cursor after the following expression and type @kbd{C-x -C-e} (@code{eval-last-sexp}). - -@c !!! 22.1.1 lisp sources location here -@smallexample -(lengths-list-file - "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el") -@end smallexample - -@noindent -(You may need to change the pathname of the file; the one here is for -GNU Emacs version 22.1.1. To change the expression, copy it to -the @file{*scratch*} buffer and edit it. - -@need 1200 -@noindent -(Also, to see the full length of the list, rather than a truncated -version, you may have to evaluate the following: - -@smallexample -(custom-set-variables '(eval-expression-print-length nil)) -@end smallexample - -@noindent -(@xref{defcustom, , Specifying Variables using @code{defcustom}}. -Then evaluate the @code{lengths-list-file} expression.) - -@need 1200 -The lengths' list for @file{debug.el} takes less than a second to -produce and looks like this in GNU Emacs 22: - -@smallexample -(83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587) -@end smallexample - -@need 1500 -(Using my old machine, the version 19 lengths' list for @file{debug.el} -took seven seconds to produce and looked like this: - -@smallexample -(75 41 80 62 20 45 44 68 45 12 34 235) -@end smallexample - -(The newer version of @file{debug.el} contains more defuns than the -earlier one; and my new machine is much faster than the old one.) - -Note that the length of the last definition in the file is first in -the list. - -@node Several files, Several files recursively, lengths-list-file, Words in a defun -@section Count Words in @code{defuns} in Different Files - -In the previous section, we created a function that returns a list of -the lengths of each definition in a file. Now, we want to define a -function to return a master list of the lengths of the definitions in -a list of files. - -Working on each of a list of files is a repetitious act, so we can use -either a @code{while} loop or recursion. - -@menu -* lengths-list-many-files:: Return a list of the lengths of defuns. -* append:: Attach one list to another. -@end menu - -@node lengths-list-many-files, append, Several files, Several files -@ifnottex -@unnumberedsubsec Determine the lengths of @code{defuns} -@end ifnottex - -The design using a @code{while} loop is routine. The argument passed -the function is a list of files. As we saw earlier (@pxref{Loop -Example}), you can write a @code{while} loop so that the body of the -loop is evaluated if such a list contains elements, but to exit the -loop if the list is empty. For this design to work, the body of the -loop must contain an expression that shortens the list each time the -body is evaluated, so that eventually the list is empty. The usual -technique is to set the value of the list to the value of the @sc{cdr} -of the list each time the body is evaluated. - -@need 800 -The template looks like this: - -@smallexample -@group -(while @var{test-whether-list-is-empty} - @var{body}@dots{} - @var{set-list-to-cdr-of-list}) -@end group -@end smallexample - -Also, we remember that a @code{while} loop returns @code{nil} (the -result of evaluating the true-or-false-test), not the result of any -evaluation within its body. (The evaluations within the body of the -loop are done for their side effects.) However, the expression that -sets the lengths' list is part of the body---and that is the value -that we want returned by the function as a whole. To do this, we -enclose the @code{while} loop within a @code{let} expression, and -arrange that the last element of the @code{let} expression contains -the value of the lengths' list. (@xref{Incrementing Example, , Loop -Example with an Incrementing Counter}.) - -@findex lengths-list-many-files -@need 1250 -These considerations lead us directly to the function itself: - -@smallexample -@group -;;; @r{Use @code{while} loop.} -(defun lengths-list-many-files (list-of-files) - "Return list of lengths of defuns in LIST-OF-FILES." -@end group -@group - (let (lengths-list) - -;;; @r{true-or-false-test} - (while list-of-files - (setq lengths-list - (append - lengths-list - -;;; @r{Generate a lengths' list.} - (lengths-list-file - (expand-file-name (car list-of-files))))) -@end group - -@group -;;; @r{Make files' list shorter.} - (setq list-of-files (cdr list-of-files))) - -;;; @r{Return final value of lengths' list.} - lengths-list)) -@end group -@end smallexample - -@code{expand-file-name} is a built-in function that converts a file -name to the absolute, long, path name form. The function employs the -name of the directory in which the function is called. - -@c !!! 22.1.1 lisp sources location here -@need 1500 -Thus, if @code{expand-file-name} is called on @code{debug.el} when -Emacs is visiting the -@file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory, - -@smallexample -debug.el -@end smallexample - -@need 800 -@noindent -becomes - -@c !!! 22.1.1 lisp sources location here -@smallexample -/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el -@end smallexample - -The only other new element of this function definition is the as yet -unstudied function @code{append}, which merits a short section for -itself. - -@node append, , lengths-list-many-files, Several files -@subsection The @code{append} Function - -@need 800 -The @code{append} function attaches one list to another. Thus, - -@smallexample -(append '(1 2 3 4) '(5 6 7 8)) -@end smallexample - -@need 800 -@noindent -produces the list - -@smallexample -(1 2 3 4 5 6 7 8) -@end smallexample - -This is exactly how we want to attach two lengths' lists produced by -@code{lengths-list-file} to each other. The results contrast with -@code{cons}, - -@smallexample -(cons '(1 2 3 4) '(5 6 7 8)) -@end smallexample - -@need 1250 -@noindent -which constructs a new list in which the first argument to @code{cons} -becomes the first element of the new list: - -@smallexample -((1 2 3 4) 5 6 7 8) -@end smallexample - -@node Several files recursively, Prepare the data, Several files, Words in a defun -@section Recursively Count Words in Different Files - -Besides a @code{while} loop, you can work on each of a list of files -with recursion. A recursive version of @code{lengths-list-many-files} -is short and simple. - -The recursive function has the usual parts: the `do-again-test', the -`next-step-expression', and the recursive call. The `do-again-test' -determines whether the function should call itself again, which it -will do if the @code{list-of-files} contains any remaining elements; -the `next-step-expression' resets the @code{list-of-files} to the -@sc{cdr} of itself, so eventually the list will be empty; and the -recursive call calls itself on the shorter list. The complete -function is shorter than this description! -@findex recursive-lengths-list-many-files - -@smallexample -@group -(defun recursive-lengths-list-many-files (list-of-files) - "Return list of lengths of each defun in LIST-OF-FILES." - (if list-of-files ; @r{do-again-test} - (append - (lengths-list-file - (expand-file-name (car list-of-files))) - (recursive-lengths-list-many-files - (cdr list-of-files))))) -@end group -@end smallexample - -@noindent -In a sentence, the function returns the lengths' list for the first of -the @code{list-of-files} appended to the result of calling itself on -the rest of the @code{list-of-files}. - -Here is a test of @code{recursive-lengths-list-many-files}, along with -the results of running @code{lengths-list-file} on each of the files -individually. - -Install @code{recursive-lengths-list-many-files} and -@code{lengths-list-file}, if necessary, and then evaluate the -following expressions. You may need to change the files' pathnames; -those here work when this Info file and the Emacs sources are located -in their customary places. To change the expressions, copy them to -the @file{*scratch*} buffer, edit them, and then evaluate them. - -The results are shown after the @samp{@result{}}. (These results are -for files from Emacs version 22.1.1; files from other versions of -Emacs may produce different results.) - -@c !!! 22.1.1 lisp sources location here -@smallexample -@group -(cd "/usr/local/share/emacs/22.1.1/") - -(lengths-list-file "./lisp/macros.el") - @result{} (283 263 480 90) -@end group - -@group -(lengths-list-file "./lisp/mail/mailalias.el") - @result{} (38 32 29 95 178 180 321 218 324) -@end group - -@group -(lengths-list-file "./lisp/makesum.el") - @result{} (85 181) -@end group - -@group - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mail/mailalias.el" - "./lisp/makesum.el")) - @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181) -@end group -@end smallexample - -The @code{recursive-lengths-list-many-files} function produces the -output we want. - -The next step is to prepare the data in the list for display in a graph. - -@node Prepare the data, , Several files recursively, Words in a defun -@section Prepare the Data for Display in a Graph - -The @code{recursive-lengths-list-many-files} function returns a list -of numbers. Each number records the length of a function definition. -What we need to do now is transform this data into a list of numbers -suitable for generating a graph. The new list will tell how many -functions definitions contain less than 10 words and -symbols, how many contain between 10 and 19 words and symbols, how -many contain between 20 and 29 words and symbols, and so on. - -In brief, we need to go through the lengths' list produced by the -@code{recursive-lengths-list-many-files} function and count the number -of defuns within each range of lengths, and produce a list of those -numbers. - -@menu -* Data for Display in Detail:: -* Sorting:: Sorting lists. -* Files List:: Making a list of files. -* Counting function definitions:: -@end menu - -@node Data for Display in Detail, Sorting, Prepare the data, Prepare the data -@ifnottex -@unnumberedsubsec The Data for Display in Detail -@end ifnottex - -Based on what we have done before, we can readily foresee that it -should not be too hard to write a function that `@sc{cdr}s' down the -lengths' list, looks at each element, determines which length range it -is in, and increments a counter for that range. - -However, before beginning to write such a function, we should consider -the advantages of sorting the lengths' list first, so the numbers are -ordered from smallest to largest. First, sorting will make it easier -to count the numbers in each range, since two adjacent numbers will -either be in the same length range or in adjacent ranges. Second, by -inspecting a sorted list, we can discover the highest and lowest -number, and thereby determine the largest and smallest length range -that we will need. - -@node Sorting, Files List, Data for Display in Detail, Prepare the data -@subsection Sorting Lists -@findex sort - -Emacs contains a function to sort lists, called (as you might guess) -@code{sort}. The @code{sort} function takes two arguments, the list -to be sorted, and a predicate that determines whether the first of -two list elements is ``less'' than the second. - -As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong -Type Object as an Argument}), a predicate is a function that -determines whether some property is true or false. The @code{sort} -function will reorder a list according to whatever property the -predicate uses; this means that @code{sort} can be used to sort -non-numeric lists by non-numeric criteria---it can, for example, -alphabetize a list. - -@need 1250 -The @code{<} function is used when sorting a numeric list. For example, - -@smallexample -(sort '(4 8 21 17 33 7 21 7) '<) -@end smallexample - -@need 800 -@noindent -produces this: - -@smallexample -(4 7 7 8 17 21 21 33) -@end smallexample - -@noindent -(Note that in this example, both the arguments are quoted so that the -symbols are not evaluated before being passed to @code{sort} as -arguments.) - -Sorting the list returned by the -@code{recursive-lengths-list-many-files} function is straightforward; -it uses the @code{<} function: - -@ignore -2006 Oct 29 -In GNU Emacs 22, eval -(progn - (cd "/usr/local/share/emacs/22.0.50/") - (sort - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mail/mailalias.el" - "./lisp/makesum.el")) - '<)) - -@end ignore - -@smallexample -@group -(sort - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mailalias.el" - "./lisp/makesum.el")) - '<) -@end group -@end smallexample - -@need 800 -@noindent -which produces: - -@smallexample -(29 32 38 85 90 95 178 180 181 218 263 283 321 324 480) -@end smallexample - -@noindent -(Note that in this example, the first argument to @code{sort} is not -quoted, since the expression must be evaluated so as to produce the -list that is passed to @code{sort}.) - -@node Files List, Counting function definitions, Sorting, Prepare the data -@subsection Making a List of Files - -The @code{recursive-lengths-list-many-files} function requires a list -of files as its argument. For our test examples, we constructed such -a list by hand; but the Emacs Lisp source directory is too large for -us to do for that. Instead, we will write a function to do the job -for us. In this function, we will use both a @code{while} loop and a -recursive call. - -@findex directory-files -We did not have to write a function like this for older versions of -GNU Emacs, since they placed all the @samp{.el} files in one -directory. Instead, we were able to use the @code{directory-files} -function, which lists the names of files that match a specified -pattern within a single directory. - -However, recent versions of Emacs place Emacs Lisp files in -sub-directories of the top level @file{lisp} directory. This -re-arrangement eases navigation. For example, all the mail related -files are in a @file{lisp} sub-directory called @file{mail}. But at -the same time, this arrangement forces us to create a file listing -function that descends into the sub-directories. - -@findex files-in-below-directory -We can create this function, called @code{files-in-below-directory}, -using familiar functions such as @code{car}, @code{nthcdr}, and -@code{substring} in conjunction with an existing function called -@code{directory-files-and-attributes}. This latter function not only -lists all the filenames in a directory, including the names -of sub-directories, but also their attributes. - -To restate our goal: to create a function that will enable us -to feed filenames to @code{recursive-lengths-list-many-files} -as a list that looks like this (but with more elements): - -@smallexample -@group -("./lisp/macros.el" - "./lisp/mail/rmail.el" - "./lisp/makesum.el") -@end group -@end smallexample - -The @code{directory-files-and-attributes} function returns a list of -lists. Each of the lists within the main list consists of 13 -elements. The first element is a string that contains the name of the -file -- which, in GNU/Linux, may be a `directory file', that is to -say, a file with the special attributes of a directory. The second -element of the list is @code{t} for a directory, a string -for symbolic link (the string is the name linked to), or @code{nil}. - -For example, the first @samp{.el} file in the @file{lisp/} directory -is @file{abbrev.el}. Its name is -@file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a -directory or a symbolic link. - -@need 1000 -This is how @code{directory-files-and-attributes} lists that file and -its attributes: - -@smallexample -@group -("abbrev.el" -nil -1 -1000 -100 -@end group -@group -(17733 259) -(17491 28834) -(17596 62124) -13157 -"-rw-rw-r--" -@end group -@group -nil -2971624 -773) -@end group -@end smallexample - -@need 1200 -On the other hand, @file{mail/} is a directory within the @file{lisp/} -directory. The beginning of its listing looks like this: - -@smallexample -@group -("mail" -t -@dots{} -) -@end group -@end smallexample - -(To learn about the different attributes, look at the documentation of -@code{file-attributes}. Bear in mind that the @code{file-attributes} -function does not list the filename, so its first element is -@code{directory-files-and-attributes}'s second element.) - -We will want our new function, @code{files-in-below-directory}, to -list the @samp{.el} files in the directory it is told to check, and in -any directories below that directory. - -This gives us a hint on how to construct -@code{files-in-below-directory}: within a directory, the function -should add @samp{.el} filenames to a list; and if, within a directory, -the function comes upon a sub-directory, it should go into that -sub-directory and repeat its actions. - -However, we should note that every directory contains a name that -refers to itself, called @file{.}, (``dot'') and a name that refers to -its parent directory, called @file{..} (``double dot''). (In -@file{/}, the root directory, @file{..} refers to itself, since -@file{/} has no parent.) Clearly, we do not want our -@code{files-in-below-directory} function to enter those directories, -since they always lead us, directly or indirectly, to the current -directory. - -Consequently, our @code{files-in-below-directory} function must do -several tasks: - -@itemize @bullet -@item -Check to see whether it is looking at a filename that ends in -@samp{.el}; and if so, add its name to a list. - -@item -Check to see whether it is looking at a filename that is the name of a -directory; and if so, - -@itemize @minus -@item -Check to see whether it is looking at @file{.} or @file{..}; and if -so skip it. - -@item -Or else, go into that directory and repeat the process. -@end itemize -@end itemize - -Let's write a function definition to do these tasks. We will use a -@code{while} loop to move from one filename to another within a -directory, checking what needs to be done; and we will use a recursive -call to repeat the actions on each sub-directory. The recursive -pattern is `accumulate' -(@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}), -using @code{append} as the combiner. - -@ignore -(directory-files "/usr/local/src/emacs/lisp/" t "\\.el$") -(shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'") - -(directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$") -(shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'") -@end ignore - -@c /usr/local/share/emacs/22.1.1/lisp/ - -@need 800 -Here is the function: - -@smallexample -@group -(defun files-in-below-directory (directory) - "List the .el files in DIRECTORY and in its sub-directories." - ;; Although the function will be used non-interactively, - ;; it will be easier to test if we make it interactive. - ;; The directory will have a name such as - ;; "/usr/local/share/emacs/22.1.1/lisp/" - (interactive "DDirectory name: ") -@end group -@group - (let (el-files-list - (current-directory-list - (directory-files-and-attributes directory t))) - ;; while we are in the current directory - (while current-directory-list -@end group -@group - (cond - ;; check to see whether filename ends in `.el' - ;; and if so, append its name to a list. - ((equal ".el" (substring (car (car current-directory-list)) -3)) - (setq el-files-list - (cons (car (car current-directory-list)) el-files-list))) -@end group -@group - ;; check whether filename is that of a directory - ((eq t (car (cdr (car current-directory-list)))) - ;; decide whether to skip or recurse - (if - (equal "." - (substring (car (car current-directory-list)) -1)) - ;; then do nothing since filename is that of - ;; current directory or parent, "." or ".." - () -@end group -@group - ;; else descend into the directory and repeat the process - (setq el-files-list - (append - (files-in-below-directory - (car (car current-directory-list))) - el-files-list))))) - ;; move to the next filename in the list; this also - ;; shortens the list so the while loop eventually comes to an end - (setq current-directory-list (cdr current-directory-list))) - ;; return the filenames - el-files-list)) -@end group -@end smallexample - -@c (files-in-below-directory "/usr/local/src/emacs/lisp/") -@c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") - -The @code{files-in-below-directory} @code{directory-files} function -takes one argument, the name of a directory. - -@need 1250 -Thus, on my system, - -@c (length (files-in-below-directory "/usr/local/src/emacs/lisp/")) - -@c !!! 22.1.1 lisp sources location here -@smallexample -@group -(length - (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")) -@end group -@end smallexample - -@noindent -tells me that in and below my Lisp sources directory are 1031 -@samp{.el} files. - -@code{files-in-below-directory} returns a list in reverse alphabetical -order. An expression to sort the list in alphabetical order looks -like this: - -@smallexample -@group -(sort - (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") - 'string-lessp) -@end group -@end smallexample - -@ignore -(defun test () - "Test how long it takes to find lengths of all sorted elisp defuns." - (insert "\n" (current-time-string) "\n") - (sit-for 0) - (sort - (recursive-lengths-list-many-files - (files-in-below-directory "/usr/local/src/emacs/lisp/")) - '<) - (insert (format "%s" (current-time-string)))) -@end ignore - -@node Counting function definitions, , Files List, Prepare the data -@subsection Counting function definitions - -Our immediate goal is to generate a list that tells us how many -function definitions contain fewer than 10 words and symbols, how many -contain between 10 and 19 words and symbols, how many contain between -20 and 29 words and symbols, and so on. - -With a sorted list of numbers, this is easy: count how many elements -of the list are smaller than 10, then, after moving past the numbers -just counted, count how many are smaller than 20, then, after moving -past the numbers just counted, count how many are smaller than 30, and -so on. Each of the numbers, 10, 20, 30, 40, and the like, is one -larger than the top of that range. We can call the list of such -numbers the @code{top-of-ranges} list. - -@need 1200 -If we wished, we could generate this list automatically, but it is -simpler to write a list manually. Here it is: -@vindex top-of-ranges - -@smallexample -@group -(defvar top-of-ranges - '(10 20 30 40 50 - 60 70 80 90 100 - 110 120 130 140 150 - 160 170 180 190 200 - 210 220 230 240 250 - 260 270 280 290 300) - "List specifying ranges for `defuns-per-range'.") -@end group -@end smallexample - -To change the ranges, we edit this list. - -Next, we need to write the function that creates the list of the -number of definitions within each range. Clearly, this function must -take the @code{sorted-lengths} and the @code{top-of-ranges} lists -as arguments. - -The @code{defuns-per-range} function must do two things again and -again: it must count the number of definitions within a range -specified by the current top-of-range value; and it must shift to the -next higher value in the @code{top-of-ranges} list after counting the -number of definitions in the current range. Since each of these -actions is repetitive, we can use @code{while} loops for the job. -One loop counts the number of definitions in the range defined by the -current top-of-range value, and the other loop selects each of the -top-of-range values in turn. - -Several entries of the @code{sorted-lengths} list are counted for each -range; this means that the loop for the @code{sorted-lengths} list -will be inside the loop for the @code{top-of-ranges} list, like a -small gear inside a big gear. - -The inner loop counts the number of definitions within the range. It -is a simple counting loop of the type we have seen before. -(@xref{Incrementing Loop, , A loop with an incrementing counter}.) -The true-or-false test of the loop tests whether the value from the -@code{sorted-lengths} list is smaller than the current value of the -top of the range. If it is, the function increments the counter and -tests the next value from the @code{sorted-lengths} list. - -@need 1250 -The inner loop looks like this: - -@smallexample -@group -(while @var{length-element-smaller-than-top-of-range} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) -@end group -@end smallexample - -The outer loop must start with the lowest value of the -@code{top-of-ranges} list, and then be set to each of the succeeding -higher values in turn. This can be done with a loop like this: - -@smallexample -@group -(while top-of-ranges - @var{body-of-loop}@dots{} - (setq top-of-ranges (cdr top-of-ranges))) -@end group -@end smallexample - -@need 1200 -Put together, the two loops look like this: - -@smallexample -@group -(while top-of-ranges - - ;; @r{Count the number of elements within the current range.} - (while @var{length-element-smaller-than-top-of-range} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) - - ;; @r{Move to next range.} - (setq top-of-ranges (cdr top-of-ranges))) -@end group -@end smallexample - -In addition, in each circuit of the outer loop, Emacs should record -the number of definitions within that range (the value of -@code{number-within-range}) in a list. We can use @code{cons} for -this purpose. (@xref{cons, , @code{cons}}.) - -The @code{cons} function works fine, except that the list it -constructs will contain the number of definitions for the highest -range at its beginning and the number of definitions for the lowest -range at its end. This is because @code{cons} attaches new elements -of the list to the beginning of the list, and since the two loops are -working their way through the lengths' list from the lower end first, -the @code{defuns-per-range-list} will end up largest number first. -But we will want to print our graph with smallest values first and the -larger later. The solution is to reverse the order of the -@code{defuns-per-range-list}. We can do this using the -@code{nreverse} function, which reverses the order of a list. -@findex nreverse - -@need 800 -For example, - -@smallexample -(nreverse '(1 2 3 4)) -@end smallexample - -@need 800 -@noindent -produces: - -@smallexample -(4 3 2 1) -@end smallexample - -Note that the @code{nreverse} function is ``destructive''---that is, -it changes the list to which it is applied; this contrasts with the -@code{car} and @code{cdr} functions, which are non-destructive. In -this case, we do not want the original @code{defuns-per-range-list}, -so it does not matter that it is destroyed. (The @code{reverse} -function provides a reversed copy of a list, leaving the original list -as is.) -@findex reverse - -@need 1250 -Put all together, the @code{defuns-per-range} looks like this: - -@smallexample -@group -(defun defuns-per-range (sorted-lengths top-of-ranges) - "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." - (let ((top-of-range (car top-of-ranges)) - (number-within-range 0) - defuns-per-range-list) -@end group - -@group - ;; @r{Outer loop.} - (while top-of-ranges -@end group - -@group - ;; @r{Inner loop.} - (while (and - ;; @r{Need number for numeric test.} - (car sorted-lengths) - (< (car sorted-lengths) top-of-range)) -@end group - -@group - ;; @r{Count number of definitions within current range.} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) - - ;; @r{Exit inner loop but remain within outer loop.} -@end group - -@group - (setq defuns-per-range-list - (cons number-within-range defuns-per-range-list)) - (setq number-within-range 0) ; @r{Reset count to zero.} -@end group - -@group - ;; @r{Move to next range.} - (setq top-of-ranges (cdr top-of-ranges)) - ;; @r{Specify next top of range value.} - (setq top-of-range (car top-of-ranges))) -@end group - -@group - ;; @r{Exit outer loop and count the number of defuns larger than} - ;; @r{ the largest top-of-range value.} - (setq defuns-per-range-list - (cons - (length sorted-lengths) - defuns-per-range-list)) -@end group - -@group - ;; @r{Return a list of the number of definitions within each range,} - ;; @r{ smallest to largest.} - (nreverse defuns-per-range-list))) -@end group -@end smallexample - -@need 1200 -@noindent -The function is straightforward except for one subtle feature. The -true-or-false test of the inner loop looks like this: - -@smallexample -@group -(and (car sorted-lengths) - (< (car sorted-lengths) top-of-range)) -@end group -@end smallexample - -@need 800 -@noindent -instead of like this: - -@smallexample -(< (car sorted-lengths) top-of-range) -@end smallexample - -The purpose of the test is to determine whether the first item in the -@code{sorted-lengths} list is less than the value of the top of the -range. - -The simple version of the test works fine unless the -@code{sorted-lengths} list has a @code{nil} value. In that case, the -@code{(car sorted-lengths)} expression function returns -@code{nil}. The @code{<} function cannot compare a number to -@code{nil}, which is an empty list, so Emacs signals an error and -stops the function from attempting to continue to execute. - -The @code{sorted-lengths} list always becomes @code{nil} when the -counter reaches the end of the list. This means that any attempt to -use the @code{defuns-per-range} function with the simple version of -the test will fail. - -We solve the problem by using the @code{(car sorted-lengths)} -expression in conjunction with the @code{and} expression. The -@code{(car sorted-lengths)} expression returns a non-@code{nil} -value so long as the list has at least one number within it, but -returns @code{nil} if the list is empty. The @code{and} expression -first evaluates the @code{(car sorted-lengths)} expression, and -if it is @code{nil}, returns false @emph{without} evaluating the -@code{<} expression. But if the @code{(car sorted-lengths)} -expression returns a non-@code{nil} value, the @code{and} expression -evaluates the @code{<} expression, and returns that value as the value -of the @code{and} expression. - -@c colon in printed section title causes problem in Info cross reference -This way, we avoid an error. -@iftex -@noindent -(For information about @code{and}, see -@ref{kill-new function, , The @code{kill-new} function}.) -@end iftex -@ifinfo -@noindent -(@xref{kill-new function, , The @code{kill-new} function}, for -information about @code{and}.) -@end ifinfo - -Here is a short test of the @code{defuns-per-range} function. First, -evaluate the expression that binds (a shortened) -@code{top-of-ranges} list to the list of values, then evaluate the -expression for binding the @code{sorted-lengths} list, and then -evaluate the @code{defuns-per-range} function. - -@smallexample -@group -;; @r{(Shorter list than we will use later.)} -(setq top-of-ranges - '(110 120 130 140 150 - 160 170 180 190 200)) - -(setq sorted-lengths - '(85 86 110 116 122 129 154 176 179 200 265 300 300)) - -(defuns-per-range sorted-lengths top-of-ranges) -@end group -@end smallexample - -@need 800 -@noindent -The list returned looks like this: - -@smallexample -(2 2 2 0 0 1 0 2 0 0 4) -@end smallexample - -@noindent -Indeed, there are two elements of the @code{sorted-lengths} list -smaller than 110, two elements between 110 and 119, two elements -between 120 and 129, and so on. There are four elements with a value -of 200 or larger. - -@c The next step is to turn this numbers' list into a graph. -@node Readying a Graph, Emacs Initialization, Words in a defun, Top -@chapter Readying a Graph -@cindex Readying a graph -@cindex Graph prototype -@cindex Prototype graph -@cindex Body of graph - -Our goal is to construct a graph showing the numbers of function -definitions of various lengths in the Emacs lisp sources. - -As a practical matter, if you were creating a graph, you would -probably use a program such as @code{gnuplot} to do the job. -(@code{gnuplot} is nicely integrated into GNU Emacs.) In this case, -however, we create one from scratch, and in the process we will -re-acquaint ourselves with some of what we learned before and learn -more. - -In this chapter, we will first write a simple graph printing function. -This first definition will be a @dfn{prototype}, a rapidly written -function that enables us to reconnoiter this unknown graph-making -territory. We will discover dragons, or find that they are myth. -After scouting the terrain, we will feel more confident and enhance -the function to label the axes automatically. - -@menu -* Columns of a graph:: -* graph-body-print:: How to print the body of a graph. -* recursive-graph-body-print:: -* Printed Axes:: -* Line Graph Exercise:: -@end menu - -@node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph -@ifnottex -@unnumberedsec Printing the Columns of a Graph -@end ifnottex - -Since Emacs is designed to be flexible and work with all kinds of -terminals, including character-only terminals, the graph will need to -be made from one of the `typewriter' symbols. An asterisk will do; as -we enhance the graph-printing function, we can make the choice of -symbol a user option. - -We can call this function @code{graph-body-print}; it will take a -@code{numbers-list} as its only argument. At this stage, we will not -label the graph, but only print its body. - -The @code{graph-body-print} function inserts a vertical column of -asterisks for each element in the @code{numbers-list}. The height of -each line is determined by the value of that element of the -@code{numbers-list}. - -Inserting columns is a repetitive act; that means that this function can -be written either with a @code{while} loop or recursively. - -Our first challenge is to discover how to print a column of asterisks. -Usually, in Emacs, we print characters onto a screen horizontally, -line by line, by typing. We have two routes we can follow: write our -own column-insertion function or discover whether one exists in Emacs. - -To see whether there is one in Emacs, we can use the @kbd{M-x apropos} -command. This command is like the @kbd{C-h a} (@code{command-apropos}) -command, except that the latter finds only those functions that are -commands. The @kbd{M-x apropos} command lists all symbols that match -a regular expression, including functions that are not interactive. -@findex apropos - -What we want to look for is some command that prints or inserts -columns. Very likely, the name of the function will contain either -the word `print' or the word `insert' or the word `column'. -Therefore, we can simply type @kbd{M-x apropos RET -print\|insert\|column RET} and look at the result. On my system, this -command once too takes quite some time, and then produced a list of 79 -functions and variables. Now it does not take much time at all and -produces a list of 211 functions and variables. Scanning down the -list, the only function that looks as if it might do the job is -@code{insert-rectangle}. - -@need 1200 -Indeed, this is the function we want; its documentation says: - -@smallexample -@group -insert-rectangle: -Insert text of RECTANGLE with upper left corner at point. -RECTANGLE's first line is inserted at point, -its second line is inserted at a point vertically under point, etc. -RECTANGLE should be a list of strings. -After this command, the mark is at the upper left corner -and point is at the lower right corner. -@end group -@end smallexample - -We can run a quick test, to make sure it does what we expect of it. - -Here is the result of placing the cursor after the -@code{insert-rectangle} expression and typing @kbd{C-u C-x C-e} -(@code{eval-last-sexp}). The function inserts the strings -@samp{"first"}, @samp{"second"}, and @samp{"third"} at and below -point. Also the function returns @code{nil}. - -@smallexample -@group -(insert-rectangle '("first" "second" "third"))first - second - thirdnil -@end group -@end smallexample - -@noindent -Of course, we won't be inserting the text of the -@code{insert-rectangle} expression itself into the buffer in which we -are making the graph, but will call the function from our program. We -shall, however, have to make sure that point is in the buffer at the -place where the @code{insert-rectangle} function will insert its -column of strings. - -If you are reading this in Info, you can see how this works by -switching to another buffer, such as the @file{*scratch*} buffer, -placing point somewhere in the buffer, typing @kbd{M-:}, typing the -@code{insert-rectangle} expression into the minibuffer at the prompt, -and then typing @key{RET}. This causes Emacs to evaluate the -expression in the minibuffer, but to use as the value of point the -position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the -keybinding for @code{eval-expression}. Also, @code{nil} does not -appear in the @file{*scratch*} buffer since the expression is -evaluated in the minibuffer.) - -We find when we do this that point ends up at the end of the last -inserted line---that is to say, this function moves point as a -side-effect. If we were to repeat the command, with point at this -position, the next insertion would be below and to the right of the -previous insertion. We don't want this! If we are going to make a -bar graph, the columns need to be beside each other. - -So we discover that each cycle of the column-inserting @code{while} -loop must reposition point to the place we want it, and that place -will be at the top, not the bottom, of the column. Moreover, we -remember that when we print a graph, we do not expect all the columns -to be the same height. This means that the top of each column may be -at a different height from the previous one. We cannot simply -reposition point to the same line each time, but moved over to the -right---or perhaps we can@dots{} - -We are planning to make the columns of the bar graph out of asterisks. -The number of asterisks in the column is the number specified by the -current element of the @code{numbers-list}. We need to construct a -list of asterisks of the right length for each call to -@code{insert-rectangle}. If this list consists solely of the requisite -number of asterisks, then we will have position point the right number -of lines above the base for the graph to print correctly. This could -be difficult. - -Alternatively, if we can figure out some way to pass -@code{insert-rectangle} a list of the same length each time, then we -can place point on the same line each time, but move it over one -column to the right for each new column. If we do this, however, some -of the entries in the list passed to @code{insert-rectangle} must be -blanks rather than asterisks. For example, if the maximum height of -the graph is 5, but the height of the column is 3, then -@code{insert-rectangle} requires an argument that looks like this: - -@smallexample -(" " " " "*" "*" "*") -@end smallexample - -This last proposal is not so difficult, so long as we can determine -the column height. There are two ways for us to specify the column -height: we can arbitrarily state what it will be, which would work -fine for graphs of that height; or we can search through the list of -numbers and use the maximum height of the list as the maximum height -of the graph. If the latter operation were difficult, then the former -procedure would be easiest, but there is a function built into Emacs -that determines the maximum of its arguments. We can use that -function. The function is called @code{max} and it returns the -largest of all its arguments, which must be numbers. Thus, for -example, - -@smallexample -(max 3 4 6 5 7 3) -@end smallexample - -@noindent -returns 7. (A corresponding function called @code{min} returns the -smallest of all its arguments.) -@findex max -@findex min - -However, we cannot simply call @code{max} on the @code{numbers-list}; -the @code{max} function expects numbers as its argument, not a list of -numbers. Thus, the following expression, - -@smallexample -(max '(3 4 6 5 7 3)) -@end smallexample - -@need 800 -@noindent -produces the following error message; - -@smallexample -Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3) -@end smallexample - -@findex apply -We need a function that passes a list of arguments to a function. -This function is @code{apply}. This function `applies' its first -argument (a function) to its remaining arguments, the last of which -may be a list. - -@need 1250 -For example, - -@smallexample -(apply 'max 3 4 7 3 '(4 8 5)) -@end smallexample - -@noindent -returns 8. - -(Incidentally, I don't know how you would learn of this function -without a book such as this. It is possible to discover other -functions, like @code{search-forward} or @code{insert-rectangle}, by -guessing at a part of their names and then using @code{apropos}. Even -though its base in metaphor is clear---`apply' its first argument to -the rest---I doubt a novice would come up with that particular word -when using @code{apropos} or other aid. Of course, I could be wrong; -after all, the function was first named by someone who had to invent -it.) - -The second and subsequent arguments to @code{apply} are optional, so -we can use @code{apply} to call a function and pass the elements of a -list to it, like this, which also returns 8: - -@smallexample -(apply 'max '(4 8 5)) -@end smallexample - -This latter way is how we will use @code{apply}. The -@code{recursive-lengths-list-many-files} function returns a numbers' -list to which we can apply @code{max} (we could also apply @code{max} to -the sorted numbers' list; it does not matter whether the list is -sorted or not.) - -@need 800 -Hence, the operation for finding the maximum height of the graph is this: - -@smallexample -(setq max-graph-height (apply 'max numbers-list)) -@end smallexample - -Now we can return to the question of how to create a list of strings -for a column of the graph. Told the maximum height of the graph -and the number of asterisks that should appear in the column, the -function should return a list of strings for the -@code{insert-rectangle} command to insert. - -Each column is made up of asterisks or blanks. Since the function is -passed the value of the height of the column and the number of -asterisks in the column, the number of blanks can be found by -subtracting the number of asterisks from the height of the column. -Given the number of blanks and the number of asterisks, two -@code{while} loops can be used to construct the list: - -@smallexample -@group -;;; @r{First version.} -(defun column-of-graph (max-graph-height actual-height) - "Return list of strings that is one column of a graph." - (let ((insert-list nil) - (number-of-top-blanks - (- max-graph-height actual-height))) -@end group - -@group - ;; @r{Fill in asterisks.} - (while (> actual-height 0) - (setq insert-list (cons "*" insert-list)) - (setq actual-height (1- actual-height))) -@end group - -@group - ;; @r{Fill in blanks.} - (while (> number-of-top-blanks 0) - (setq insert-list (cons " " insert-list)) - (setq number-of-top-blanks - (1- number-of-top-blanks))) -@end group - -@group - ;; @r{Return whole list.} - insert-list)) -@end group -@end smallexample - -If you install this function and then evaluate the following -expression you will see that it returns the list as desired: - -@smallexample -(column-of-graph 5 3) -@end smallexample - -@need 800 -@noindent -returns - -@smallexample -(" " " " "*" "*" "*") -@end smallexample - -As written, @code{column-of-graph} contains a major flaw: the symbols -used for the blank and for the marked entries in the column are -`hard-coded' as a space and asterisk. This is fine for a prototype, -but you, or another user, may wish to use other symbols. For example, -in testing the graph function, you many want to use a period in place -of the space, to make sure the point is being repositioned properly -each time the @code{insert-rectangle} function is called; or you might -want to substitute a @samp{+} sign or other symbol for the asterisk. -You might even want to make a graph-column that is more than one -display column wide. The program should be more flexible. The way to -do that is to replace the blank and the asterisk with two variables -that we can call @code{graph-blank} and @code{graph-symbol} and define -those variables separately. - -Also, the documentation is not well written. These considerations -lead us to the second version of the function: - -@smallexample -@group -(defvar graph-symbol "*" - "String used as symbol in graph, usually an asterisk.") -@end group - -@group -(defvar graph-blank " " - "String used as blank in graph, usually a blank space. -graph-blank must be the same number of columns wide -as graph-symbol.") -@end group -@end smallexample - -@noindent -(For an explanation of @code{defvar}, see -@ref{defvar, , Initializing a Variable with @code{defvar}}.) - -@smallexample -@group -;;; @r{Second version.} -(defun column-of-graph (max-graph-height actual-height) - "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols. - -@end group -@group -The graph-symbols are contiguous entries at the end -of the list. -The list will be inserted as one column of a graph. -The strings are either graph-blank or graph-symbol." -@end group - -@group - (let ((insert-list nil) - (number-of-top-blanks - (- max-graph-height actual-height))) -@end group - -@group - ;; @r{Fill in @code{graph-symbols}.} - (while (> actual-height 0) - (setq insert-list (cons graph-symbol insert-list)) - (setq actual-height (1- actual-height))) -@end group - -@group - ;; @r{Fill in @code{graph-blanks}.} - (while (> number-of-top-blanks 0) - (setq insert-list (cons graph-blank insert-list)) - (setq number-of-top-blanks - (1- number-of-top-blanks))) - - ;; @r{Return whole list.} - insert-list)) -@end group -@end smallexample - -If we wished, we could rewrite @code{column-of-graph} a third time to -provide optionally for a line graph as well as for a bar graph. This -would not be hard to do. One way to think of a line graph is that it -is no more than a bar graph in which the part of each bar that is -below the top is blank. To construct a column for a line graph, the -function first constructs a list of blanks that is one shorter than -the value, then it uses @code{cons} to attach a graph symbol to the -list; then it uses @code{cons} again to attach the `top blanks' to -the list. - -It is easy to see how to write such a function, but since we don't -need it, we will not do it. But the job could be done, and if it were -done, it would be done with @code{column-of-graph}. Even more -important, it is worth noting that few changes would have to be made -anywhere else. The enhancement, if we ever wish to make it, is -simple. - -Now, finally, we come to our first actual graph printing function. -This prints the body of a graph, not the labels for the vertical and -horizontal axes, so we can call this @code{graph-body-print}. - -@node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph -@section The @code{graph-body-print} Function -@findex graph-body-print - -After our preparation in the preceding section, the -@code{graph-body-print} function is straightforward. The function -will print column after column of asterisks and blanks, using the -elements of a numbers' list to specify the number of asterisks in each -column. This is a repetitive act, which means we can use a -decrementing @code{while} loop or recursive function for the job. In -this section, we will write the definition using a @code{while} loop. - -The @code{column-of-graph} function requires the height of the graph -as an argument, so we should determine and record that as a local variable. - -This leads us to the following template for the @code{while} loop -version of this function: - -@smallexample -@group -(defun graph-body-print (numbers-list) - "@var{documentation}@dots{}" - (let ((height @dots{} - @dots{})) -@end group - -@group - (while numbers-list - @var{insert-columns-and-reposition-point} - (setq numbers-list (cdr numbers-list))))) -@end group -@end smallexample - -@noindent -We need to fill in the slots of the template. - -Clearly, we can use the @code{(apply 'max numbers-list)} expression to -determine the height of the graph. - -The @code{while} loop will cycle through the @code{numbers-list} one -element at a time. As it is shortened by the @code{(setq numbers-list -(cdr numbers-list))} expression, the @sc{car} of each instance of the -list is the value of the argument for @code{column-of-graph}. - -At each cycle of the @code{while} loop, the @code{insert-rectangle} -function inserts the list returned by @code{column-of-graph}. Since -the @code{insert-rectangle} function moves point to the lower right of -the inserted rectangle, we need to save the location of point at the -time the rectangle is inserted, move back to that position after the -rectangle is inserted, and then move horizontally to the next place -from which @code{insert-rectangle} is called. - -If the inserted columns are one character wide, as they will be if -single blanks and asterisks are used, the repositioning command is -simply @code{(forward-char 1)}; however, the width of a column may be -greater than one. This means that the repositioning command should be -written @code{(forward-char symbol-width)}. The @code{symbol-width} -itself is the length of a @code{graph-blank} and can be found using -the expression @code{(length graph-blank)}. The best place to bind -the @code{symbol-width} variable to the value of the width of graph -column is in the varlist of the @code{let} expression. - -@need 1250 -These considerations lead to the following function definition: - -@smallexample -@group -(defun graph-body-print (numbers-list) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values." - - (let ((height (apply 'max numbers-list)) - (symbol-width (length graph-blank)) - from-position) -@end group - -@group - (while numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) - (goto-char from-position) - (forward-char symbol-width) -@end group -@group - ;; @r{Draw graph column by column.} - (sit-for 0) - (setq numbers-list (cdr numbers-list))) -@end group -@group - ;; @r{Place point for X axis labels.} - (forward-line height) - (insert "\n") -)) -@end group -@end smallexample - -@noindent -The one unexpected expression in this function is the -@w{@code{(sit-for 0)}} expression in the @code{while} loop. This -expression makes the graph printing operation more interesting to -watch than it would be otherwise. The expression causes Emacs to -`sit' or do nothing for a zero length of time and then redraw the -screen. Placed here, it causes Emacs to redraw the screen column by -column. Without it, Emacs would not redraw the screen until the -function exits. - -We can test @code{graph-body-print} with a short list of numbers. - -@enumerate -@item -Install @code{graph-symbol}, @code{graph-blank}, -@code{column-of-graph}, which are in -@iftex -@ref{Readying a Graph, , Readying a Graph}, -@end iftex -@ifinfo -@ref{Columns of a graph}, -@end ifinfo -and @code{graph-body-print}. - -@need 800 -@item -Copy the following expression: - -@smallexample -(graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3)) -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the graph to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the @code{graph-body-print} expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the @code{graph-body-print} expression. -@end enumerate - -@need 800 -Emacs will print a graph like this: - -@smallexample -@group - * - * ** - * **** - *** **** - ********* * - ************ - ************* -@end group -@end smallexample - -@node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph -@section The @code{recursive-graph-body-print} Function -@findex recursive-graph-body-print - -The @code{graph-body-print} function may also be written recursively. -The recursive solution is divided into two parts: an outside `wrapper' -that uses a @code{let} expression to determine the values of several -variables that need only be found once, such as the maximum height of -the graph, and an inside function that is called recursively to print -the graph. - -@need 1250 -The `wrapper' is uncomplicated: - -@smallexample -@group -(defun recursive-graph-body-print (numbers-list) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values." - (let ((height (apply 'max numbers-list)) - (symbol-width (length graph-blank)) - from-position) - (recursive-graph-body-print-internal - numbers-list - height - symbol-width))) -@end group -@end smallexample - -The recursive function is a little more difficult. It has four parts: -the `do-again-test', the printing code, the recursive call, and the -`next-step-expression'. The `do-again-test' is a @code{when} -expression that determines whether the @code{numbers-list} contains -any remaining elements; if it does, the function prints one column of -the graph using the printing code and calls itself again. The -function calls itself again according to the value produced by the -`next-step-expression' which causes the call to act on a shorter -version of the @code{numbers-list}. - -@smallexample -@group -(defun recursive-graph-body-print-internal - (numbers-list height symbol-width) - "Print a bar graph. -Used within recursive-graph-body-print function." -@end group - -@group - (when numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) -@end group -@group - (goto-char from-position) - (forward-char symbol-width) - (sit-for 0) ; @r{Draw graph column by column.} - (recursive-graph-body-print-internal - (cdr numbers-list) height symbol-width))) -@end group -@end smallexample - -@need 1250 -After installation, this expression can be tested; here is a sample: - -@smallexample -(recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1)) -@end smallexample - -@need 800 -Here is what @code{recursive-graph-body-print} produces: - -@smallexample -@group - * - ** * - **** * - **** *** - * ********* - ************ - ************* -@end group -@end smallexample - -Either of these two functions, @code{graph-body-print} or -@code{recursive-graph-body-print}, create the body of a graph. - -@node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph -@section Need for Printed Axes - -A graph needs printed axes, so you can orient yourself. For a do-once -project, it may be reasonable to draw the axes by hand using Emacs' -Picture mode; but a graph drawing function may be used more than once. - -For this reason, I have written enhancements to the basic -@code{print-graph-body} function that automatically print labels for -the horizontal and vertical axes. Since the label printing functions -do not contain much new material, I have placed their description in -an appendix. @xref{Full Graph, , A Graph with Labelled Axes}. - -@node Line Graph Exercise, , Printed Axes, Readying a Graph -@section Exercise - -Write a line graph version of the graph printing functions. - -@node Emacs Initialization, Debugging, Readying a Graph, Top -@chapter Your @file{.emacs} File -@cindex @file{.emacs} file -@cindex Customizing your @file{.emacs} file -@cindex Initialization file - -``You don't have to like Emacs to like it'' -- this seemingly -paradoxical statement is the secret of GNU Emacs. The plain, `out of -the box' Emacs is a generic tool. Most people who use it, customize -it to suit themselves. - -GNU Emacs is mostly written in Emacs Lisp; this means that by writing -expressions in Emacs Lisp you can change or extend Emacs. - -@menu -* Default Configuration:: -* Site-wide Init:: You can write site-wide init files. -* defcustom:: Emacs will write code for you. -* Beginning a .emacs File:: How to write a @code{.emacs file}. -* Text and Auto-fill:: Automatically wrap lines. -* Mail Aliases:: Use abbreviations for email addresses. -* Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. -* Keymaps:: More about key binding. -* Loading Files:: Load (i.e., evaluate) files automatically. -* Autoload:: Make functions available. -* Simple Extension:: Define a function; bind it to a key. -* X11 Colors:: Colors in X. -* Miscellaneous:: -* Mode Line:: How to customize your mode line. -@end menu - -@node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization -@ifnottex -@unnumberedsec Emacs' Default Configuration -@end ifnottex - -There are those who appreciate Emacs' default configuration. After -all, Emacs starts you in C mode when you edit a C file, starts you in -Fortran mode when you edit a Fortran file, and starts you in -Fundamental mode when you edit an unadorned file. This all makes -sense, if you do not know who is going to use Emacs. Who knows what a -person hopes to do with an unadorned file? Fundamental mode is the -right default for such a file, just as C mode is the right default for -editing C code. (Enough programming languages have syntaxes -that enable them to share or nearly share features, so C mode is -now provided by by CC mode, the `C Collection'.) - -But when you do know who is going to use Emacs---you, -yourself---then it makes sense to customize Emacs. - -For example, I seldom want Fundamental mode when I edit an -otherwise undistinguished file; I want Text mode. This is why I -customize Emacs: so it suits me. - -You can customize and extend Emacs by writing or adapting a -@file{~/.emacs} file. This is your personal initialization file; its -contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You -may also add @file{.el} to @file{~/.emacs} and call it a -@file{~/.emacs.el} file. In the past, you were forbidden to type the -extra keystrokes that the name @file{~/.emacs.el} requires, but now -you may. The new format is consistent with the Emacs Lisp file -naming conventions; the old format saves typing.} - -A @file{~/.emacs} file contains Emacs Lisp code. You can write this -code yourself; or you can use Emacs' @code{customize} feature to write -the code for you. You can combine your own expressions and -auto-written Customize expressions in your @file{.emacs} file. - -(I myself prefer to write my own expressions, except for those, -particularly fonts, that I find easier to manipulate using the -@code{customize} command. I combine the two methods.) - -Most of this chapter is about writing expressions yourself. It -describes a simple @file{.emacs} file; for more information, see -@ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and -@ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference -Manual}. - -@node Site-wide Init, defcustom, Default Configuration, Emacs Initialization -@section Site-wide Initialization Files - -@cindex @file{default.el} init file -@cindex @file{site-init.el} init file -@cindex @file{site-load.el} init file -In addition to your personal initialization file, Emacs automatically -loads various site-wide initialization files, if they exist. These -have the same form as your @file{.emacs} file, but are loaded by -everyone. - -Two site-wide initialization files, @file{site-load.el} and -@file{site-init.el}, are loaded into Emacs and then `dumped' if a -`dumped' version of Emacs is created, as is most common. (Dumped -copies of Emacs load more quickly. However, once a file is loaded and -dumped, a change to it does not lead to a change in Emacs unless you -load it yourself or re-dump Emacs. @xref{Building Emacs, , Building -Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the -@file{INSTALL} file.) - -Three other site-wide initialization files are loaded automatically -each time you start Emacs, if they exist. These are -@file{site-start.el}, which is loaded @emph{before} your @file{.emacs} -file, and @file{default.el}, and the terminal type file, which are both -loaded @emph{after} your @file{.emacs} file. - -Settings and definitions in your @file{.emacs} file will overwrite -conflicting settings and definitions in a @file{site-start.el} file, -if it exists; but the settings and definitions in a @file{default.el} -or terminal type file will overwrite those in your @file{.emacs} file. -(You can prevent interference from a terminal type file by setting -@code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A -Simple Extension}.) - -@c Rewritten to avoid overfull hbox. -The @file{INSTALL} file that comes in the distribution contains -descriptions of the @file{site-init.el} and @file{site-load.el} files. - -The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files -control loading. These files are in the @file{lisp} directory of the -Emacs distribution and are worth perusing. - -The @file{loaddefs.el} file contains a good many suggestions as to -what to put into your own @file{.emacs} file, or into a site-wide -initialization file. - -@node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization -@section Specifying Variables using @code{defcustom} -@findex defcustom - -You can specify variables using @code{defcustom} so that you and -others can then use Emacs' @code{customize} feature to set their -values. (You cannot use @code{customize} to write function -definitions; but you can write @code{defuns} in your @file{.emacs} -file. Indeed, you can write any Lisp expression in your @file{.emacs} -file.) - -The @code{customize} feature depends on the @code{defcustom} special -form. Although you can use @code{defvar} or @code{setq} for variables -that users set, the @code{defcustom} special form is designed for the -job. - -You can use your knowledge of @code{defvar} for writing the -first three arguments for @code{defcustom}. The first argument to -@code{defcustom} is the name of the variable. The second argument is -the variable's initial value, if any; and this value is set only if -the value has not already been set. The third argument is the -documentation. - -The fourth and subsequent arguments to @code{defcustom} specify types -and options; these are not featured in @code{defvar}. (These -arguments are optional.) - -Each of these arguments consists of a keyword followed by a value. -Each keyword starts with the colon character @samp{:}. - -@need 1250 -For example, the customizable user option variable -@code{text-mode-hook} looks like this: - -@smallexample -@group -(defcustom text-mode-hook nil - "Normal hook run when entering Text mode and many related modes." - :type 'hook - :options '(turn-on-auto-fill flyspell-mode) - :group 'data) -@end group -@end smallexample - -@noindent -The name of the variable is @code{text-mode-hook}; it has no default -value; and its documentation string tells you what it does. - -The @code{:type} keyword tells Emacs the kind of data to which -@code{text-mode-hook} should be set and how to display the value in a -Customization buffer. - -The @code{:options} keyword specifies a suggested list of values for -the variable. Usually, @code{:options} applies to a hook. -The list is only a suggestion; it is not exclusive; a person who sets -the variable may set it to other values; the list shown following the -@code{:options} keyword is intended to offer convenient choices to a -user. - -Finally, the @code{:group} keyword tells the Emacs Customization -command in which group the variable is located. This tells where to -find it. - -The @code{defcustom} function recognizes more than a dozen keywords. -For more information, see @ref{Customization, , Writing Customization -Definitions, elisp, The GNU Emacs Lisp Reference Manual}. - -Consider @code{text-mode-hook} as an example. - -There are two ways to customize this variable. You can use the -customization command or write the appropriate expressions yourself. - -@need 800 -Using the customization command, you can type: - -@smallexample -M-x customize -@end smallexample - -@noindent -and find that the group for editing files of data is called `data'. -Enter that group. Text Mode Hook is the first member. You can click -on its various options, such as @code{turn-on-auto-fill}, to set the -values. After you click on the button to - -@smallexample -Save for Future Sessions -@end smallexample - -@noindent -Emacs will write an expression into your @file{.emacs} file. -It will look like this: - -@smallexample -@group -(custom-set-variables - ;; custom-set-variables was added by Custom. - ;; If you edit it by hand, you could mess it up, so be careful. - ;; Your init file should contain only one such instance. - ;; If there is more than one, they won't work right. - '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify)))) -@end group -@end smallexample - -@noindent -(The @code{text-mode-hook-identify} function tells -@code{toggle-text-mode-auto-fill} which buffers are in Text mode. -It comes on automatically.) - -The @code{custom-set-variables} function works somewhat differently -than a @code{setq}. While I have never learned the differences, I -modify the @code{custom-set-variables} expressions in my @file{.emacs} -file by hand: I make the changes in what appears to me to be a -reasonable manner and have not had any problems. Others prefer to use -the Customization command and let Emacs do the work for them. - -Another @code{custom-set-@dots{}} function is @code{custom-set-faces}. -This function sets the various font faces. Over time, I have set a -considerable number of faces. Some of the time, I re-set them using -@code{customize}; other times, I simply edit the -@code{custom-set-faces} expression in my @file{.emacs} file itself. - -The second way to customize your @code{text-mode-hook} is to set it -yourself in your @file{.emacs} file using code that has nothing to do -with the @code{custom-set-@dots{}} functions. - -@need 800 -When you do this, and later use @code{customize}, you will see a -message that says - -@smallexample -CHANGED outside Customize; operating on it here may be unreliable. -@end smallexample - -@need 800 -This message is only a warning. If you click on the button to - -@smallexample -Save for Future Sessions -@end smallexample - -@noindent -Emacs will write a @code{custom-set-@dots{}} expression near the end -of your @file{.emacs} file that will be evaluated after your -hand-written expression. It will, therefore, overrule your -hand-written expression. No harm will be done. When you do this, -however, be careful to remember which expression is active; if you -forget, you may confuse yourself. - -So long as you remember where the values are set, you will have no -trouble. In any event, the values are always set in your -initialization file, which is usually called @file{.emacs}. - -I myself use @code{customize} for hardly anything. Mostly, I write -expressions myself. - -@findex defsubst -@findex defconst -Incidentally, to be more complete concerning defines: @code{defsubst} -defines an inline function. The syntax is just like that of -@code{defun}. @code{defconst} defines a symbol as a constant. The -intent is that neither programs nor users should ever change a value -set by @code{defconst}. (You can change it; the value set is a -variable; but please do not.) - -@node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization -@section Beginning a @file{.emacs} File -@cindex @file{.emacs} file, beginning of - -When you start Emacs, it loads your @file{.emacs} file unless you tell -it not to by specifying @samp{-q} on the command line. (The -@code{emacs -q} command gives you a plain, out-of-the-box Emacs.) - -A @file{.emacs} file contains Lisp expressions. Often, these are no -more than expressions to set values; sometimes they are function -definitions. - -@xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs -Manual}, for a short description of initialization files. - -This chapter goes over some of the same ground, but is a walk among -extracts from a complete, long-used @file{.emacs} file---my own. - -The first part of the file consists of comments: reminders to myself. -By now, of course, I remember these things, but when I started, I did -not. - -@need 1200 -@smallexample -@group -;;;; Bob's .emacs file -; Robert J. Chassell -; 26 September 1985 -@end group -@end smallexample - -@noindent -Look at that date! I started this file a long time ago. I have been -adding to it ever since. - -@smallexample -@group -; Each section in this file is introduced by a -; line beginning with four semicolons; and each -; entry is introduced by a line beginning with -; three semicolons. -@end group -@end smallexample - -@noindent -This describes the usual conventions for comments in Emacs Lisp. -Everything on a line that follows a semicolon is a comment. Two, -three, and four semicolons are used as subsection and section markers. -(@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for -more about comments.) - -@smallexample -@group -;;;; The Help Key -; Control-h is the help key; -; after typing control-h, type a letter to -; indicate the subject about which you want help. -; For an explanation of the help facility, -; type control-h two times in a row. -@end group -@end smallexample - -@noindent -Just remember: type @kbd{C-h} two times for help. - -@smallexample -@group -; To find out about any mode, type control-h m -; while in that mode. For example, to find out -; about mail mode, enter mail mode and then type -; control-h m. -@end group -@end smallexample - -@noindent -`Mode help', as I call this, is very helpful. Usually, it tells you -all you need to know. - -Of course, you don't need to include comments like these in your -@file{.emacs} file. I included them in mine because I kept forgetting -about Mode help or the conventions for comments---but I was able to -remember to look here to remind myself. - -@node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization -@section Text and Auto Fill Mode - -Now we come to the part that `turns on' Text mode and -Auto Fill mode. - -@smallexample -@group -;;; Text mode and Auto Fill mode -; The next two lines put Emacs into Text mode -; and Auto Fill mode, and are for writers who -; want to start writing prose rather than code. -(setq default-major-mode 'text-mode) -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end group -@end smallexample - -Here is the first part of this @file{.emacs} file that does something -besides remind a forgetful human! - -The first of the two lines in parentheses tells Emacs to turn on Text -mode when you find a file, @emph{unless} that file should go into some -other mode, such as C mode. - -@cindex Per-buffer, local variables list -@cindex Local variables list, per-buffer, -@cindex Automatic mode selection -@cindex Mode selection, automatic -When Emacs reads a file, it looks at the extension to the file name, -if any. (The extension is the part that comes after a @samp{.}.) If -the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns -on C mode. Also, Emacs looks at first nonblank line of the file; if -the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs -possesses a list of extensions and specifications that it uses -automatically. In addition, Emacs looks near the last page for a -per-buffer, ``local variables list'', if any. - -@ifinfo -@xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU -Emacs Manual}. - -@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs -Manual}. -@end ifinfo -@iftex -See sections ``How Major Modes are Chosen'' and ``Local Variables in -Files'' in @cite{The GNU Emacs Manual}. -@end iftex - -Now, back to the @file{.emacs} file. - -@need 800 -Here is the line again; how does it work? - -@cindex Text Mode turned on -@smallexample -(setq default-major-mode 'text-mode) -@end smallexample - -@noindent -This line is a short, but complete Emacs Lisp expression. - -We are already familiar with @code{setq}. It sets the following variable, -@code{default-major-mode}, to the subsequent value, which is -@code{text-mode}. The single quote mark before @code{text-mode} tells -Emacs to deal directly with the @code{text-mode} variable, not with -whatever it might stand for. @xref{set & setq, , Setting the Value of -a Variable}, for a reminder of how @code{setq} works. The main point -is that there is no difference between the procedure you use to set -a value in your @file{.emacs} file and the procedure you use anywhere -else in Emacs. - -@need 800 -Here is the next line: - -@cindex Auto Fill mode turned on -@findex add-hook -@smallexample -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end smallexample - -@noindent -In this line, the @code{add-hook} command adds -@code{turn-on-auto-fill} to the variable. - -@code{turn-on-auto-fill} is the name of a program, that, you guessed -it!, turns on Auto Fill mode. - -Every time Emacs turns on Text mode, Emacs runs the commands `hooked' -onto Text mode. So every time Emacs turns on Text mode, Emacs also -turns on Auto Fill mode. - -In brief, the first line causes Emacs to enter Text mode when you edit a -file, unless the file name extension, a first non-blank line, or local -variables to tell Emacs otherwise. - -Text mode among other actions, sets the syntax table to work -conveniently for writers. In Text mode, Emacs considers an apostrophe -as part of a word like a letter; but Emacs does not consider a period -or a space as part of a word. Thus, @kbd{M-f} moves you over -@samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after -the @samp{t} of @samp{it's}. - -The second line causes Emacs to turn on Auto Fill mode when it turns -on Text mode. In Auto Fill mode, Emacs automatically breaks a line -that is too wide and brings the excessively wide part of the line down -to the next line. Emacs breaks lines between words, not within them. - -When Auto Fill mode is turned off, lines continue to the right as you -type them. Depending on how you set the value of -@code{truncate-lines}, the words you type either disappear off the -right side of the screen, or else are shown, in a rather ugly and -unreadable manner, as a continuation line on the screen. - -@need 1250 -In addition, in this part of my @file{.emacs} file, I tell the Emacs -fill commands to insert two spaces after a colon: - -@smallexample -(setq colon-double-space t) -@end smallexample - -@node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization -@section Mail Aliases - -Here is a @code{setq} that `turns on' mail aliases, along with more -reminders. - -@smallexample -@group -;;; Mail mode -; To enter mail mode, type `C-x m' -; To enter RMAIL (for reading mail), -; type `M-x rmail' -(setq mail-aliases t) -@end group -@end smallexample - -@cindex Mail aliases -@noindent -This @code{setq} command sets the value of the variable -@code{mail-aliases} to @code{t}. Since @code{t} means true, the line -says, in effect, ``Yes, use mail aliases.'' - -Mail aliases are convenient short names for long email addresses or -for lists of email addresses. The file where you keep your `aliases' -is @file{~/.mailrc}. You write an alias like this: - -@smallexample -alias geo george@@foobar.wiz.edu -@end smallexample - -@noindent -When you write a message to George, address it to @samp{geo}; the -mailer will automatically expand @samp{geo} to the full address. - -@node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization -@section Indent Tabs Mode -@cindex Tabs, preventing -@findex indent-tabs-mode - -By default, Emacs inserts tabs in place of multiple spaces when it -formats a region. (For example, you might indent many lines of text -all at once with the @code{indent-region} command.) Tabs look fine on -a terminal or with ordinary printing, but they produce badly indented -output when you use @TeX{} or Texinfo since @TeX{} ignores tabs. - -@need 1250 -The following turns off Indent Tabs mode: - -@smallexample -@group -;;; Prevent Extraneous Tabs -(setq-default indent-tabs-mode nil) -@end group -@end smallexample - -Note that this line uses @code{setq-default} rather than the -@code{setq} command that we have seen before. The @code{setq-default} -command sets values only in buffers that do not have their own local -values for the variable. - -@ifinfo -@xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}. - -@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs -Manual}. -@end ifinfo -@iftex -See sections ``Tabs vs.@: Spaces'' and ``Local Variables in -Files'' in @cite{The GNU Emacs Manual}. -@end iftex - -@need 1700 -@node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization -@section Some Keybindings - -Now for some personal keybindings: - -@smallexample -@group -;;; Compare windows -(global-set-key "\C-cw" 'compare-windows) -@end group -@end smallexample - -@findex compare-windows -@code{compare-windows} is a nifty command that compares the text in -your current window with text in the next window. It makes the -comparison by starting at point in each window, moving over text in -each window as far as they match. I use this command all the time. - -This also shows how to set a key globally, for all modes. - -@cindex Setting a key globally -@cindex Global set key -@cindex Key setting globally -@findex global-set-key -The command is @code{global-set-key}. It is followed by the -keybinding. In a @file{.emacs} file, the keybinding is written as -shown: @code{\C-c} stands for `control-c', which means `press the -control key and the @key{c} key at the same time'. The @code{w} means -`press the @key{w} key'. The keybinding is surrounded by double -quotation marks. In documentation, you would write this as -@w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as -@kbd{M-c}, rather than a @key{CTRL} key, you would write -@w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, , -Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for -details.) - -The command invoked by the keys is @code{compare-windows}. Note that -@code{compare-windows} is preceded by a single quote; otherwise, Emacs -would first try to evaluate the symbol to determine its value. - -These three things, the double quotation marks, the backslash before -the @samp{C}, and the single quote mark are necessary parts of -keybinding that I tend to forget. Fortunately, I have come to -remember that I should look at my existing @file{.emacs} file, and -adapt what is there. - -As for the keybinding itself: @kbd{C-c w}. This combines the prefix -key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This -set of keys, @kbd{C-c} followed by a single character, is strictly -reserved for individuals' own use. (I call these `own' keys, since -these are for my own use.) You should always be able to create such a -keybinding for your own use without stomping on someone else's -keybinding. If you ever write an extension to Emacs, please avoid -taking any of these keys for public use. Create a key like @kbd{C-c -C-w} instead. Otherwise, we will run out of `own' keys. - -@need 1250 -Here is another keybinding, with a comment: - -@smallexample -@group -;;; Keybinding for `occur' -; I use occur a lot, so let's bind it to a key: -(global-set-key "\C-co" 'occur) -@end group -@end smallexample - -@findex occur -The @code{occur} command shows all the lines in the current buffer -that contain a match for a regular expression. Matching lines are -shown in a buffer called @file{*Occur*}. That buffer serves as a menu -to jump to occurrences. - -@findex global-unset-key -@cindex Unbinding key -@cindex Key unbinding -@need 1250 -Here is how to unbind a key, so it does not -work: - -@smallexample -@group -;;; Unbind `C-x f' -(global-unset-key "\C-xf") -@end group -@end smallexample - -There is a reason for this unbinding: I found I inadvertently typed -@w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a -file, as I intended, I accidentally set the width for filled text, -almost always to a width I did not want. Since I hardly ever reset my -default width, I simply unbound the key. - -@findex list-buffers, @r{rebound} -@findex buffer-menu, @r{bound to key} -@need 1250 -The following rebinds an existing key: - -@smallexample -@group -;;; Rebind `C-x C-b' for `buffer-menu' -(global-set-key "\C-x\C-b" 'buffer-menu) -@end group -@end smallexample - -By default, @kbd{C-x C-b} runs the -@code{list-buffers} command. This command lists -your buffers in @emph{another} window. Since I -almost always want to do something in that -window, I prefer the @code{buffer-menu} -command, which not only lists the buffers, -but moves point into that window. - -@node Keymaps, Loading Files, Keybindings, Emacs Initialization -@section Keymaps -@cindex Keymaps -@cindex Rebinding keys - -Emacs uses @dfn{keymaps} to record which keys call which commands. -When you use @code{global-set-key} to set the keybinding for a single -command in all parts of Emacs, you are specifying the keybinding in -@code{current-global-map}. - -Specific modes, such as C mode or Text mode, have their own keymaps; -the mode-specific keymaps override the global map that is shared by -all buffers. - -The @code{global-set-key} function binds, or rebinds, the global -keymap. For example, the following binds the key @kbd{C-x C-b} to the -function @code{buffer-menu}: - -@smallexample -(global-set-key "\C-x\C-b" 'buffer-menu) -@end smallexample - -Mode-specific keymaps are bound using the @code{define-key} function, -which takes a specific keymap as an argument, as well as the key and -the command. For example, my @file{.emacs} file contains the -following expression to bind the @code{texinfo-insert-@@group} command -to @kbd{C-c C-c g}: - -@smallexample -@group -(define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group) -@end group -@end smallexample - -@noindent -The @code{texinfo-insert-@@group} function itself is a little extension -to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I -use this command all the time and prefer to type the three strokes -@kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}. -(@samp{@@group} and its matching @samp{@@end group} are commands that -keep all enclosed text together on one page; many multi-line examples -in this book are surrounded by @samp{@@group @dots{} @@end group}.) - -@need 1250 -Here is the @code{texinfo-insert-@@group} function definition: - -@smallexample -@group -(defun texinfo-insert-@@group () - "Insert the string @@group in a Texinfo buffer." - (interactive) - (beginning-of-line) - (insert "@@group\n")) -@end group -@end smallexample - -(Of course, I could have used Abbrev mode to save typing, rather than -write a function to insert a word; but I prefer key strokes consistent -with other Texinfo mode key bindings.) - -You will see numerous @code{define-key} expressions in -@file{loaddefs.el} as well as in the various mode libraries, such as -@file{cc-mode.el} and @file{lisp-mode.el}. - -@xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs -Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp -Reference Manual}, for more information about keymaps. - -@node Loading Files, Autoload, Keymaps, Emacs Initialization -@section Loading Files -@cindex Loading files -@c findex load - -Many people in the GNU Emacs community have written extensions to -Emacs. As time goes by, these extensions are often included in new -releases. For example, the Calendar and Diary packages are now part -of the standard GNU Emacs, as is Calc. - -You can use a @code{load} command to evaluate a complete file and -thereby install all the functions and variables in the file into Emacs. -For example: - -@c (auto-compression-mode t) - -@smallexample -(load "~/emacs/slowsplit") -@end smallexample - -This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it -exists, the faster, byte compiled @file{slowsplit.elc} file from the -@file{emacs} sub-directory of your home directory. The file contains -the function @code{split-window-quietly}, which John Robinson wrote in -1989. - -The @code{split-window-quietly} function splits a window with the -minimum of redisplay. I installed it in 1989 because it worked well -with the slow 1200 baud terminals I was then using. Nowadays, I only -occasionally come across such a slow connection, but I continue to use -the function because I like the way it leaves the bottom half of a -buffer in the lower of the new windows and the top half in the upper -window. - -@need 1250 -To replace the key binding for the default -@code{split-window-vertically}, you must also unset that key and bind -the keys to @code{split-window-quietly}, like this: - -@smallexample -@group -(global-unset-key "\C-x2") -(global-set-key "\C-x2" 'split-window-quietly) -@end group -@end smallexample - -@vindex load-path -If you load many extensions, as I do, then instead of specifying the -exact location of the extension file, as shown above, you can specify -that directory as part of Emacs' @code{load-path}. Then, when Emacs -loads a file, it will search that directory as well as its default -list of directories. (The default list is specified in @file{paths.h} -when Emacs is built.) - -@need 1250 -The following command adds your @file{~/emacs} directory to the -existing load path: - -@smallexample -@group -;;; Emacs Load Path -(setq load-path (cons "~/emacs" load-path)) -@end group -@end smallexample - -Incidentally, @code{load-library} is an interactive interface to the -@code{load} function. The complete function looks like this: - -@findex load-library -@smallexample -@group -(defun load-library (library) - "Load the library named LIBRARY. -This is an interface to the function `load'." - (interactive - (list (completing-read "Load library: " - 'locate-file-completion - (cons load-path (get-load-suffixes))))) - (load library)) -@end group -@end smallexample - -The name of the function, @code{load-library}, comes from the use of -`library' as a conventional synonym for `file'. The source for the -@code{load-library} command is in the @file{files.el} library. - -Another interactive command that does a slightly different job is -@code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for -Emacs, emacs, The GNU Emacs Manual}, for information on the -distinction between @code{load-library} and this command. - -@node Autoload, Simple Extension, Loading Files, Emacs Initialization -@section Autoloading -@findex autoload - -Instead of installing a function by loading the file that contains it, -or by evaluating the function definition, you can make the function -available but not actually install it until it is first called. This -is called @dfn{autoloading}. - -When you execute an autoloaded function, Emacs automatically evaluates -the file that contains the definition, and then calls the function. - -Emacs starts quicker with autoloaded functions, since their libraries -are not loaded right away; but you need to wait a moment when you -first use such a function, while its containing file is evaluated. - -Rarely used functions are frequently autoloaded. The -@file{loaddefs.el} library contains hundreds of autoloaded functions, -from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may -come to use a `rare' function frequently. When you do, you should -load that function's file with a @code{load} expression in your -@file{.emacs} file. - -In my @file{.emacs} file, I load 14 libraries that contain functions -that would otherwise be autoloaded. (Actually, it would have been -better to include these files in my `dumped' Emacs, but I forgot. -@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp -Reference Manual}, and the @file{INSTALL} file for more about -dumping.) - -You may also want to include autoloaded expressions in your @file{.emacs} -file. @code{autoload} is a built-in function that takes up to five -arguments, the final three of which are optional. The first argument -is the name of the function to be autoloaded; the second is the name -of the file to be loaded. The third argument is documentation for the -function, and the fourth tells whether the function can be called -interactively. The fifth argument tells what type of -object---@code{autoload} can handle a keymap or macro as well as a -function (the default is a function). - -@need 800 -Here is a typical example: - -@smallexample -@group -(autoload 'html-helper-mode - "html-helper-mode" "Edit HTML documents" t) -@end group -@end smallexample - -@noindent -(@code{html-helper-mode} is an older alternative to @code{html-mode}, -which is a standard part of the distribution.) - -@noindent -This expression autoloads the @code{html-helper-mode} function. It -takes it from the @file{html-helper-mode.el} file (or from the byte -compiled file @file{html-helper-mode.elc}, if it exists.) The file -must be located in a directory specified by @code{load-path}. The -documentation says that this is a mode to help you edit documents -written in the HyperText Markup Language. You can call this mode -interactively by typing @kbd{M-x html-helper-mode}. (You need to -duplicate the function's regular documentation in the autoload -expression because the regular function is not yet loaded, so its -documentation is not available.) - -@xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference -Manual}, for more information. - -@node Simple Extension, X11 Colors, Autoload, Emacs Initialization -@section A Simple Extension: @code{line-to-top-of-window} -@findex line-to-top-of-window -@cindex Simple extension in @file{.emacs} file - -Here is a simple extension to Emacs that moves the line point is on to -the top of the window. I use this all the time, to make text easier -to read. - -You can put the following code into a separate file and then load it -from your @file{.emacs} file, or you can include it within your -@file{.emacs} file. - -@need 1250 -Here is the definition: - -@smallexample -@group -;;; Line to top of window; -;;; replace three keystroke sequence C-u 0 C-l -(defun line-to-top-of-window () - "Move the line point is on to top of window." - (interactive) - (recenter 0)) -@end group -@end smallexample - -@need 1250 -Now for the keybinding. - -Nowadays, function keys as well as mouse button events and -non-@sc{ascii} characters are written within square brackets, without -quotation marks. (In Emacs version 18 and before, you had to write -different function key bindings for each different make of terminal.) - -I bind @code{line-to-top-of-window} to my @key{F6} function key like -this: - -@smallexample -(global-set-key [f6] 'line-to-top-of-window) -@end smallexample - -For more information, see @ref{Init Rebinding, , Rebinding Keys in -Your Init File, emacs, The GNU Emacs Manual}. - -@cindex Conditional 'twixt two versions of Emacs -@cindex Version of Emacs, choosing -@cindex Emacs version, choosing -If you run two versions of GNU Emacs, such as versions 21 and 22, and -use one @file{.emacs} file, you can select which code to evaluate with -the following conditional: - -@smallexample -@group -(cond - (= 21 emacs-major-version) - ;; evaluate version 21 code - ( @dots{} )) - (= 22 emacs-major-version) - ;; evaluate version 22 code - ( @dots{} ))) -@end group -@end smallexample - -For example, in contrast to version 20, more recent versions blink -their cursors by default. I hate such blinking, as well as other -features, so I placed the following in my @file{.emacs} -file@footnote{When I start instances of Emacs that do not load my -@file{.emacs} file or any site file, I also turn off blinking: - -@smallexample -emacs -q --no-site-file -eval '(blink-cursor-mode nil)' - -@exdent Or nowadays, using an even more sophisticated set of options, - -emacs -Q - D -@end smallexample -}: - -@smallexample -@group -(when (or (= 21 emacs-major-version) - (= 22 emacs-major-version)) - (blink-cursor-mode 0) - ;; Insert newline when you press `C-n' (next-line) - ;; at the end of the buffer - (setq next-line-add-newlines t) -@end group -@group - ;; Turn on image viewing - (auto-image-file-mode t) -@end group -@group - ;; Turn on menu bar (this bar has text) - ;; (Use numeric argument to turn on) - (menu-bar-mode 1) -@end group -@group - ;; Turn off tool bar (this bar has icons) - ;; (Use numeric argument to turn on) - (tool-bar-mode nil) -@end group -@group - ;; Turn off tooltip mode for tool bar - ;; (This mode causes icon explanations to pop up) - ;; (Use numeric argument to turn on) - (tooltip-mode nil) - ;; If tooltips turned on, make tips appear promptly - (setq tooltip-delay 0.1) ; default is 0.7 second - ) -@end group -@end smallexample - -@need 1250 -Alternatively, since @code{blink-cursor-mode} has existed since Emacs -version 21 and is likely to continue, you could write - -@smallexample -@group -(when (>= emacs-major-version 21) - (blink-cursor-mode 0) -@end group -@end smallexample - -@noindent -and add other expressions, too. - - -@node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization -@section X11 Colors - -You can specify colors when you use Emacs with the MIT X Windowing -system. - -I dislike the default colors and specify my own. - -@need 1250 -Here are the expressions in my @file{.emacs} -file that set values: - -@smallexample -@group -;; Set cursor color -(set-cursor-color "white") - -;; Set mouse color -(set-mouse-color "white") - -;; Set foreground and background -(set-foreground-color "white") -(set-background-color "darkblue") -@end group - -@group -;;; Set highlighting colors for isearch and drag -(set-face-foreground 'highlight "white") -(set-face-background 'highlight "blue") -@end group - -@group -(set-face-foreground 'region "cyan") -(set-face-background 'region "blue") -@end group - -@group -(set-face-foreground 'secondary-selection "skyblue") -(set-face-background 'secondary-selection "darkblue") -@end group - -@group -;; Set calendar highlighting colors -(setq calendar-load-hook - '(lambda () - (set-face-foreground 'diary-face "skyblue") - (set-face-background 'holiday-face "slate blue") - (set-face-foreground 'holiday-face "white"))) -@end group -@end smallexample - -The various shades of blue soothe my eye and prevent me from seeing -the screen flicker. - -Alternatively, I could have set my specifications in various X -initialization files. For example, I could set the foreground, -background, cursor, and pointer (i.e., mouse) colors in my -@file{~/.Xresources} file like this: - -@smallexample -@group -Emacs*foreground: white -Emacs*background: darkblue -Emacs*cursorColor: white -Emacs*pointerColor: white -@end group -@end smallexample - -In any event, since it is not part of Emacs, I set the root color of -my X window in my @file{~/.xinitrc} file, like this@footnote{I also -run more modern window managers, such as Enlightenment, Gnome, or KDE; -in those cases, I often specify an image rather than a plain color.}: - -@smallexample -xsetroot -solid Navy -fg white & -@end smallexample - -@need 1700 -@node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization -@section Miscellaneous Settings for a @file{.emacs} File - -@need 1250 -Here are a few miscellaneous settings: -@sp 1 - -@itemize @minus -@item -Set the shape and color of the mouse cursor: - -@smallexample -@group -; Cursor shapes are defined in -; `/usr/include/X11/cursorfont.h'; -; for example, the `target' cursor is number 128; -; the `top_left_arrow' cursor is number 132. -@end group - -@group -(let ((mpointer (x-get-resource "*mpointer" - "*emacs*mpointer"))) - ;; If you have not set your mouse pointer - ;; then set it, otherwise leave as is: - (if (eq mpointer nil) - (setq mpointer "132")) ; top_left_arrow -@end group -@group - (setq x-pointer-shape (string-to-int mpointer)) - (set-mouse-color "white")) -@end group -@end smallexample - -@item -Or you can set the values of a variety of features in an alist, like -this: - -@smallexample -@group -(setq-default - default-frame-alist - '((cursor-color . "white") - (mouse-color . "white") - (foreground-color . "white") - (background-color . "DodgerBlue4") - ;; (cursor-type . bar) - (cursor-type . box) -@end group -@group - (tool-bar-lines . 0) - (menu-bar-lines . 1) - (width . 80) - (height . 58) - (font . - "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1") - )) -@end group -@end smallexample - -@item -Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL} -into @kbd{@key{CTRL}-h}.@* -(Some older keyboards needed this, although I have not seen the -problem recently.) - -@smallexample -@group -;; Translate `C-h' to <DEL>. -; (keyboard-translate ?\C-h ?\C-?) - -;; Translate <DEL> to `C-h'. -(keyboard-translate ?\C-? ?\C-h) -@end group -@end smallexample - -@item Turn off a blinking cursor! - -@smallexample -@group -(if (fboundp 'blink-cursor-mode) - (blink-cursor-mode -1)) -@end group -@end smallexample - -@noindent -or start GNU Emacs with the command @code{emacs -nbc}. - -@need 1250 -@item When using `grep'@* -@samp{-i}@w{ } Ignore case distinctions@* -@samp{-n}@w{ } Prefix each line of output with line number@* -@samp{-H}@w{ } Print the filename for each match.@* -@samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-} - -@smallexample -(setq grep-command "grep -i -nH -e ") -@end smallexample - -@ignore -@c Evidently, no longer needed in GNU Emacs 22 - -item Automatically uncompress compressed files when visiting them - -smallexample -(load "uncompress") -end smallexample - -@end ignore - -@item Find an existing buffer, even if it has a different name@* -This avoids problems with symbolic links. - -@smallexample -(setq find-file-existing-other-name t) -@end smallexample - -@item Set your language environment and default input method - -@smallexample -@group -(set-language-environment "latin-1") -;; Remember you can enable or disable multilingual text input -;; with the @code{toggle-input-method'} (@kbd{C-\}) command -(setq default-input-method "latin-1-prefix") -@end group -@end smallexample - -If you want to write with Chinese `GB' characters, set this instead: - -@smallexample -@group -(set-language-environment "Chinese-GB") -(setq default-input-method "chinese-tonepy") -@end group -@end smallexample -@end itemize - -@subsubheading Fixing Unpleasant Key Bindings -@cindex Key bindings, fixing -@cindex Bindings, key, fixing unpleasant - -Some systems bind keys unpleasantly. Sometimes, for example, the -@key{CTRL} key appears in an awkward spot rather than at the far left -of the home row. - -Usually, when people fix these sorts of keybindings, they do not -change their @file{~/.emacs} file. Instead, they bind the proper keys -on their consoles with the @code{loadkeys} or @code{install-keymap} -commands in their boot script and then include @code{xmodmap} commands -in their @file{.xinitrc} or @file{.Xsession} file for X Windows. - -@need 1250 -@noindent -For a boot script: - -@smallexample -@group -loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz -@exdent or -install-keymap emacs2 -@end group -@end smallexample - -@need 1250 -@noindent -For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps -Lock} key is at the far left of the home row: - -@smallexample -@group -# Bind the key labeled `Caps Lock' to `Control' -# (Such a broken user interface suggests that keyboard manufacturers -# think that computers are typewriters from 1885.) - -xmodmap -e "clear Lock" -xmodmap -e "add Control = Caps_Lock" -@end group -@end smallexample - -@need 1250 -@noindent -In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT} -key to a @key{META} key: - -@smallexample -@group -# Some ill designed keyboards have a key labeled ALT and no Meta -xmodmap -e "keysym Alt_L = Meta_L Alt_L" -@end group -@end smallexample - -@need 1700 -@node Mode Line, , Miscellaneous, Emacs Initialization -@section A Modified Mode Line -@vindex default-mode-line-format -@cindex Mode line format - -Finally, a feature I really like: a modified mode line. - -When I work over a network, I forget which machine I am using. Also, -I tend to I lose track of where I am, and which line point is on. - -So I reset my mode line to look like this: - -@smallexample --:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top -@end smallexample - -I am visiting a file called @file{foo.texi}, on my machine -@file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in -Texinfo mode, and am at the top of the buffer. - -@need 1200 -My @file{.emacs} file has a section that looks like this: - -@smallexample -@group -;; Set a Mode Line that tells me which machine, which directory, -;; and which line I am on, plus the other customary information. -(setq default-mode-line-format - (quote - (#("-" 0 1 - (help-echo - "mouse-1: select window, mouse-2: delete others ...")) - mode-line-mule-info - mode-line-modified - mode-line-frame-identification - " " -@end group -@group - mode-line-buffer-identification - " " - (:eval (substring - (system-name) 0 (string-match "\\..+" (system-name)))) - ":" - default-directory - #(" " 0 1 - (help-echo - "mouse-1: select window, mouse-2: delete others ...")) - (line-number-mode " Line %l ") - global-mode-string -@end group -@group - #(" %[(" 0 6 - (help-echo - "mouse-1: select window, mouse-2: delete others ...")) - (:eval (mode-line-mode-name)) - mode-line-process - minor-mode-alist - #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...))) - ")%] " - (-3 . "%P") - ;; "-%-" - ))) -@end group -@end smallexample - -@noindent -Here, I redefine the default mode line. Most of the parts are from -the original; but I make a few changes. I set the @emph{default} mode -line format so as to permit various modes, such as Info, to override -it. - -Many elements in the list are self-explanatory: -@code{mode-line-modified} is a variable that tells whether the buffer -has been modified, @code{mode-name} tells the name of the mode, and so -on. However, the format looks complicated because of two features we -have not discussed. - -@cindex Properties, in mode line example -The first string in the mode line is a dash or hyphen, @samp{-}. In -the old days, it would have been specified simply as @code{"-"}. But -nowadays, Emacs can add properties to a string, such as highlighting -or, as in this case, a help feature. If you place your mouse cursor -over the hyphen, some help information appears (By default, you must -wait seven-tenths of a second before the information appears. You can -change that timing by changing the value of @code{tooltip-delay}.) - -@need 1000 -The new string format has a special syntax: - -@smallexample -#("-" 0 1 (help-echo "mouse-1: select window, ...")) -@end smallexample - -@noindent -The @code{#(} begins a list. The first element of the list is the -string itself, just one @samp{-}. The second and third -elements specify the range over which the fourth element applies. A -range starts @emph{after} a character, so a zero means the range -starts just before the first character; a 1 means that the range ends -just after the first character. The third element is the property for -the range. It consists of a property list, a -property name, in this case, @samp{help-echo}, followed by a value, in this -case, a string. The second, third, and fourth elements of this new -string format can be repeated. - -@xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp -Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format, -elisp, The GNU Emacs Lisp Reference Manual}, for more information. - -@code{mode-line-buffer-identification} -displays the current buffer name. It is a list -beginning @code{(#("%12b" 0 4 @dots{}}. -The @code{#(} begins the list. - -The @samp{"%12b"} displays the current buffer name, using the -@code{buffer-name} function with which we are familiar; the `12' -specifies the maximum number of characters that will be displayed. -When a name has fewer characters, whitespace is added to fill out to -this number. (Buffer names can and often should be longer than 12 -characters; this length works well in a typical 80 column wide -window.) - -@code{:eval} says to evaluate the following form and use the result as -a string to display. In this case, the expression displays the first -component of the full system name. The end of the first component is -a @samp{.} (`period'), so I use the @code{string-match} function to -tell me the length of the first component. The substring from the -zeroth character to that length is the name of the machine. - -@need 1250 -This is the expression: - -@smallexample -@group -(:eval (substring - (system-name) 0 (string-match "\\..+" (system-name)))) -@end group -@end smallexample - -@samp{%[} and @samp{%]} cause a pair of square brackets -to appear for each recursive editing level. @samp{%n} says `Narrow' -when narrowing is in effect. @samp{%P} tells you the percentage of -the buffer that is above the bottom of the window, or `Top', `Bottom', -or `All'. (A lower case @samp{p} tell you the percentage above the -@emph{top} of the window.) @samp{%-} inserts enough dashes to fill -out the line. - -Remember, ``You don't have to like Emacs to like it'' --- your own -Emacs can have different colors, different commands, and different -keys than a default Emacs. - -On the other hand, if you want to bring up a plain `out of the box' -Emacs, with no customization, type: - -@smallexample -emacs -q -@end smallexample - -@noindent -This will start an Emacs that does @emph{not} load your -@file{~/.emacs} initialization file. A plain, default Emacs. Nothing -more. - -@node Debugging, Conclusion, Emacs Initialization, Top -@chapter Debugging -@cindex debugging - -GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The -first is built into the internals of Emacs and is always with you; -the second requires that you instrument a function before you can use it. - -Both debuggers are described extensively in @ref{Debugging, , -Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}. -In this chapter, I will walk through a short example of each. - -@menu -* debug:: How to use the built-in debugger. -* debug-on-entry:: Start debugging when you call a function. -* debug-on-quit:: Start debugging when you quit with @kbd{C-g}. -* edebug:: How to use Edebug, a source level debugger. -* Debugging Exercises:: -@end menu - -@node debug, debug-on-entry, Debugging, Debugging -@section @code{debug} -@findex debug - -Suppose you have written a function definition that is intended to -return the sum of the numbers 1 through a given number. (This is the -@code{triangle} function discussed earlier. @xref{Decrementing -Example, , Example with Decrementing Counter}, for a discussion.) -@c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.) - -However, your function definition has a bug. You have mistyped -@samp{1=} for @samp{1-}. Here is the broken definition: - -@findex triangle-bugged -@smallexample -@group -(defun triangle-bugged (number) - "Return sum of numbers 1 through NUMBER inclusive." - (let ((total 0)) - (while (> number 0) - (setq total (+ total number)) - (setq number (1= number))) ; @r{Error here.} - total)) -@end group -@end smallexample - -If you are reading this in Info, you can evaluate this definition in -the normal fashion. You will see @code{triangle-bugged} appear in the -echo area. - -@need 1250 -Now evaluate the @code{triangle-bugged} function with an -argument of 4: - -@smallexample -(triangle-bugged 4) -@end smallexample - -@noindent -In a recent GNU Emacs, you will create and enter a @file{*Backtrace*} -buffer that says: - -@noindent -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function 1=) - (1= number) - (setq number (1= number)) - (while (> number 0) (setq total (+ total number)) - (setq number (1= number))) - (let ((total 0)) (while (> number 0) (setq total ...) - (setq number ...)) total) - triangle-bugged(4) -@end group -@group - eval((triangle-bugged 4)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -(I have reformatted this example slightly; the debugger does not fold -long lines. As usual, you can quit the debugger by typing @kbd{q} in -the @file{*Backtrace*} buffer.) - -In practice, for a bug as simple as this, the `Lisp error' line will -tell you what you need to know to correct the definition. The -function @code{1=} is `void'. - -@ignore -@need 800 -In GNU Emacs 20 and before, you will see: - -@smallexample -Symbol's function definition is void:@: 1= -@end smallexample - -@noindent -which has the same meaning as the @file{*Backtrace*} buffer line in -version 21. -@end ignore - -However, suppose you are not quite certain what is going on? -You can read the complete backtrace. - -In this case, you need to run a recent GNU Emacs, which automatically -starts the debugger that puts you in the @file{*Backtrace*} buffer; or -else, you need to start the debugger manually as described below. - -Read the @file{*Backtrace*} buffer from the bottom up; it tells you -what Emacs did that led to the error. Emacs made an interactive call -to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation -of the @code{triangle-bugged} expression. Each line above tells you -what the Lisp interpreter evaluated next. - -@need 1250 -The third line from the top of the buffer is - -@smallexample -(setq number (1= number)) -@end smallexample - -@noindent -Emacs tried to evaluate this expression; in order to do so, it tried -to evaluate the inner expression shown on the second line from the -top: - -@smallexample -(1= number) -@end smallexample - -@need 1250 -@noindent -This is where the error occurred; as the top line says: - -@smallexample -Debugger entered--Lisp error: (void-function 1=) -@end smallexample - -@noindent -You can correct the mistake, re-evaluate the function definition, and -then run your test again. - -@node debug-on-entry, debug-on-quit, debug, Debugging -@section @code{debug-on-entry} -@findex debug-on-entry - -A recent GNU Emacs starts the debugger automatically when your -function has an error. - -@ignore -GNU Emacs version 20 and before did not; it simply -presented you with an error message. You had to start the debugger -manually. -@end ignore - -Incidentally, you can start the debugger manually for all versions of -Emacs; the advantage is that the debugger runs even if you do not have -a bug in your code. Sometimes your code will be free of bugs! - -You can enter the debugger when you call the function by calling -@code{debug-on-entry}. - -@need 1250 -@noindent -Type: - -@smallexample -M-x debug-on-entry RET triangle-bugged RET -@end smallexample - -@need 1250 -@noindent -Now, evaluate the following: - -@smallexample -(triangle-bugged 5) -@end smallexample - -@noindent -All versions of Emacs will create a @file{*Backtrace*} buffer and tell -you that it is beginning to evaluate the @code{triangle-bugged} -function: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--entering a function: -* triangle-bugged(5) - eval((triangle-bugged 5)) -@end group -@group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate -the first expression in @code{triangle-bugged}; the buffer will look -like this: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--beginning evaluation of function call form: -* (let ((total 0)) (while (> number 0) (setq total ...) - (setq number ...)) total) -* triangle-bugged(5) - eval((triangle-bugged 5)) -@end group -@group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -Now, type @kbd{d} again, eight times, slowly. Each time you type -@kbd{d}, Emacs will evaluate another expression in the function -definition. - -@need 1750 -Eventually, the buffer will look like this: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--beginning evaluation of function call form: -* (setq number (1= number)) -* (while (> number 0) (setq total (+ total number)) - (setq number (1= number))) -@group -@end group -* (let ((total 0)) (while (> number 0) (setq total ...) - (setq number ...)) total) -* triangle-bugged(5) - eval((triangle-bugged 5)) -@group -@end group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@need 1500 -@noindent -Finally, after you type @kbd{d} two more times, Emacs will reach the -error, and the top two lines of the @file{*Backtrace*} buffer will look -like this: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function 1=) -* (1= number) -@dots{} ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -By typing @kbd{d}, you were able to step through the function. - -You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this -quits the trace, but does not cancel @code{debug-on-entry}. - -@findex cancel-debug-on-entry -To cancel the effect of @code{debug-on-entry}, call -@code{cancel-debug-on-entry} and the name of the function, like this: - -@smallexample -M-x cancel-debug-on-entry RET triangle-bugged RET -@end smallexample - -@noindent -(If you are reading this in Info, cancel @code{debug-on-entry} now.) - -@node debug-on-quit, edebug, debug-on-entry, Debugging -@section @code{debug-on-quit} and @code{(debug)} - -In addition to setting @code{debug-on-error} or calling @code{debug-on-entry}, -there are two other ways to start @code{debug}. - -@findex debug-on-quit -You can start @code{debug} whenever you type @kbd{C-g} -(@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to -@code{t}. This is useful for debugging infinite loops. - -@need 1500 -@cindex @code{(debug)} in code -Or, you can insert a line that says @code{(debug)} into your code -where you want the debugger to start, like this: - -@smallexample -@group -(defun triangle-bugged (number) - "Return sum of numbers 1 through NUMBER inclusive." - (let ((total 0)) - (while (> number 0) - (setq total (+ total number)) - (debug) ; @r{Start debugger.} - (setq number (1= number))) ; @r{Error here.} - total)) -@end group -@end smallexample - -The @code{debug} function is described in detail in @ref{Debugger, , -The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}. - -@node edebug, Debugging Exercises, debug-on-quit, Debugging -@section The @code{edebug} Source Level Debugger -@cindex Source level debugger -@findex edebug - -Edebug is a source level debugger. Edebug normally displays the -source of the code you are debugging, with an arrow at the left that -shows which line you are currently executing. - -You can walk through the execution of a function, line by line, or run -quickly until reaching a @dfn{breakpoint} where execution stops. - -Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs -Lisp Reference Manual}. - -@need 1250 -Here is a bugged function definition for @code{triangle-recursively}. -@xref{Recursive triangle function, , Recursion in place of a counter}, -for a review of it. - -@smallexample -@group -(defun triangle-recursively-bugged (number) - "Return sum of numbers 1 through NUMBER inclusive. -Uses recursion." - (if (= number 1) - 1 - (+ number - (triangle-recursively-bugged - (1= number))))) ; @r{Error here.} -@end group -@end smallexample - -@noindent -Normally, you would install this definition by positioning your cursor -after the function's closing parenthesis and typing @kbd{C-x C-e} -(@code{eval-last-sexp}) or else by positioning your cursor within the -definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default, -the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp -Interactive mode.) - -@need 1500 -However, to prepare this function definition for Edebug, you must -first @dfn{instrument} the code using a different command. You can do -this by positioning your cursor within or just after the definition -and typing - -@smallexample -M-x edebug-defun RET -@end smallexample - -@noindent -This will cause Emacs to load Edebug automatically if it is not -already loaded, and properly instrument the function. - -After instrumenting the function, place your cursor after the -following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}): - -@smallexample -(triangle-recursively-bugged 3) -@end smallexample - -@noindent -You will be jumped back to the source for -@code{triangle-recursively-bugged} and the cursor positioned at the -beginning of the @code{if} line of the function. Also, you will see -an arrowhead at the left hand side of that line. The arrowhead marks -the line where the function is executing. (In the following examples, -we show the arrowhead with @samp{=>}; in a windowing system, you may -see the arrowhead as a solid triangle in the window `fringe'.) - -@smallexample -=>@point{}(if (= number 1) -@end smallexample - -@noindent -@iftex -In the example, the location of point is displayed with a star, -@samp{@point{}} (in Info, it is displayed as @samp{-!-}). -@end iftex -@ifnottex -In the example, the location of point is displayed as @samp{@point{}} -(in a printed book, it is displayed with a five pointed star). -@end ifnottex - -If you now press @key{SPC}, point will move to the next expression to -be executed; the line will look like this: - -@smallexample -=>(if @point{}(= number 1) -@end smallexample - -@noindent -As you continue to press @key{SPC}, point will move from expression to -expression. At the same time, whenever an expression returns a value, -that value will be displayed in the echo area. For example, after you -move point past @code{number}, you will see the following: - -@smallexample -Result: 3 (#o3, #x3, ?\C-c) -@end smallexample - -@noindent -This means the value of @code{number} is 3, which is octal three, -hexadecimal three, and @sc{ascii} `control-c' (the third letter of the -alphabet, in case you need to know this information). - -You can continue moving through the code until you reach the line with -the error. Before evaluation, that line looks like this: - -@smallexample -=> @point{}(1= number))))) ; @r{Error here.} -@end smallexample - -@need 1250 -@noindent -When you press @key{SPC} once again, you will produce an error message -that says: - -@smallexample -Symbol's function definition is void:@: 1= -@end smallexample - -@noindent -This is the bug. - -Press @kbd{q} to quit Edebug. - -To remove instrumentation from a function definition, simply -re-evaluate it with a command that does not instrument it. -For example, you could place your cursor after the definition's -closing parenthesis and type @kbd{C-x C-e}. - -Edebug does a great deal more than walk with you through a function. -You can set it so it races through on its own, stopping only at an -error or at specified stopping points; you can cause it to display the -changing values of various expressions; you can find out how many -times a function is called, and more. - -Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs -Lisp Reference Manual}. - -@need 1500 -@node Debugging Exercises, , edebug, Debugging -@section Debugging Exercises - -@itemize @bullet -@item -Install the @code{count-words-region} function and then cause it to -enter the built-in debugger when you call it. Run the command on a -region containing two words. You will need to press @kbd{d} a -remarkable number of times. On your system, is a `hook' called after -the command finishes? (For information on hooks, see @ref{Command -Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference -Manual}.) - -@item -Copy @code{count-words-region} into the @file{*scratch*} buffer, -instrument the function for Edebug, and walk through its execution. -The function does not need to have a bug, although you can introduce -one if you wish. If the function lacks a bug, the walk-through -completes without problems. - -@item -While running Edebug, type @kbd{?} to see a list of all the Edebug commands. -(The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@: -@kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix -for commands made outside of the Edebug debugging buffer.) - -@item -In the Edebug debugging buffer, use the @kbd{p} -(@code{edebug-bounce-point}) command to see where in the region the -@code{count-words-region} is working. - -@item -Move point to some spot further down the function and then type the -@kbd{h} (@code{edebug-goto-here}) command to jump to that location. - -@item -Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to -walk through the function on its own; use an upper case @kbd{T} for -@code{edebug-Trace-fast-mode}. - -@item -Set a breakpoint, then run Edebug in Trace mode until it reaches the -stopping point. -@end itemize - -@node Conclusion, the-the, Debugging, Top -@chapter Conclusion - -We have now reached the end of this Introduction. You have now -learned enough about programming in Emacs Lisp to set values, to write -simple @file{.emacs} files for yourself and your friends, and write -simple customizations and extensions to Emacs. - -This is a place to stop. Or, if you wish, you can now go onward, and -teach yourself. - -You have learned some of the basic nuts and bolts of programming. But -only some. There are a great many more brackets and hinges that are -easy to use that we have not touched. - -A path you can follow right now lies among the sources to GNU Emacs -and in -@ifnotinfo -@cite{The GNU Emacs Lisp Reference Manual}. -@end ifnotinfo -@ifinfo -@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU -Emacs Lisp Reference Manual}. -@end ifinfo - -The Emacs Lisp sources are an adventure. When you read the sources and -come across a function or expression that is unfamiliar, you need to -figure out or find out what it does. - -Go to the Reference Manual. It is a thorough, complete, and fairly -easy-to-read description of Emacs Lisp. It is written not only for -experts, but for people who know what you know. (The @cite{Reference -Manual} comes with the standard GNU Emacs distribution. Like this -introduction, it comes as a Texinfo source file, so you can read it -on-line and as a typeset, printed book.) - -Go to the other on-line help that is part of GNU Emacs: the on-line -documentation for all functions and variables, and @code{find-tags}, -the program that takes you to sources. - -Here is an example of how I explore the sources. Because of its name, -@file{simple.el} is the file I looked at first, a long time ago. As -it happens some of the functions in @file{simple.el} are complicated, -or at least look complicated at first sight. The @code{open-line} -function, for example, looks complicated. - -You may want to walk through this function slowly, as we did with the -@code{forward-sentence} function. (@xref{forward-sentence, The -@code{forward-sentence} function}.) Or you may want to skip that -function and look at another, such as @code{split-line}. You don't -need to read all the functions. According to -@code{count-words-in-defun}, the @code{split-line} function contains -102 words and symbols. - -Even though it is short, @code{split-line} contains expressions -we have not studied: @code{skip-chars-forward}, @code{indent-to}, -@code{current-column} and @code{insert-and-inherit}. - -Consider the @code{skip-chars-forward} function. (It is part of the -function definition for @code{back-to-indentation}, which is shown in -@ref{Review, , Review}.) - -In GNU Emacs, you can find out more about @code{skip-chars-forward} by -typing @kbd{C-h f} (@code{describe-function}) and the name of the -function. This gives you the function documentation. - -You may be able to guess what is done by a well named function such as -@code{indent-to}; or you can look it up, too. Incidentally, the -@code{describe-function} function itself is in @file{help.el}; it is -one of those long, but decipherable functions. You can look up -@code{describe-function} using the @kbd{C-h f} command! - -In this instance, since the code is Lisp, the @file{*Help*} buffer -contains the name of the library containing the function's source. -You can put point over the name of the library and press the RET key, -which in this situation is bound to @code{help-follow}, and be taken -directly to the source, in the same way as @kbd{M-.} -(@code{find-tag}). - -The definition for @code{describe-function} illustrates how to -customize the @code{interactive} expression without using the standard -character codes; and it shows how to create a temporary buffer. - -(The @code{indent-to} function is written in C rather than Emacs Lisp; -it is a `built-in' function. @code{help-follow} takes you to its -source as does @code{find-tag}, when properly set up.) - -You can look at a function's source using @code{find-tag}, which is -bound to @kbd{M-.} Finally, you can find out what the Reference -Manual has to say by visiting the manual in Info, and typing @kbd{i} -(@code{Info-index}) and the name of the function, or by looking up the -function in the index to a printed copy of the manual. - -Similarly, you can find out what is meant by -@code{insert-and-inherit}. - -Other interesting source files include @file{paragraphs.el}, -@file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el} -file includes short, easily understood functions as well as longer -ones. The @file{loaddefs.el} file contains the many standard -autoloads and many keymaps. I have never looked at it all; only at -parts. @file{loadup.el} is the file that loads the standard parts of -Emacs; it tells you a great deal about how Emacs is built. -(@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp -Reference Manual}, for more about building.) - -As I said, you have learned some nuts and bolts; however, and very -importantly, we have hardly touched major aspects of programming; I -have said nothing about how to sort information, except to use the -predefined @code{sort} function; I have said nothing about how to store -information, except to use variables and lists; I have said nothing -about how to write programs that write programs. These are topics for -another, and different kind of book, a different kind of learning. - -What you have done is learn enough for much practical work with GNU -Emacs. What you have done is get started. This is the end of a -beginning. - -@c ================ Appendix ================ - -@node the-the, Kill Ring, Conclusion, Top -@appendix The @code{the-the} Function -@findex the-the -@cindex Duplicated words function -@cindex Words, duplicated - -Sometimes when you you write text, you duplicate words---as with ``you -you'' near the beginning of this sentence. I find that most -frequently, I duplicate ``the''; hence, I call the function for -detecting duplicated words, @code{the-the}. - -@need 1250 -As a first step, you could use the following regular expression to -search for duplicates: - -@smallexample -\\(\\w+[ \t\n]+\\)\\1 -@end smallexample - -@noindent -This regexp matches one or more word-constituent characters followed -by one or more spaces, tabs, or newlines. However, it does not detect -duplicated words on different lines, since the ending of the first -word, the end of the line, is different from the ending of the second -word, a space. (For more information about regular expressions, see -@ref{Regexp Search, , Regular Expression Searches}, as well as -@ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs -Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp, -The GNU Emacs Lisp Reference Manual}.) - -You might try searching just for duplicated word-constituent -characters but that does not work since the pattern detects doubles -such as the two occurrences of `th' in `with the'. - -Another possible regexp searches for word-constituent characters -followed by non-word-constituent characters, reduplicated. Here, -@w{@samp{\\w+}} matches one or more word-constituent characters and -@w{@samp{\\W*}} matches zero or more non-word-constituent characters. - -@smallexample -\\(\\(\\w+\\)\\W*\\)\\1 -@end smallexample - -@noindent -Again, not useful. - -Here is the pattern that I use. It is not perfect, but good enough. -@w{@samp{\\b}} matches the empty string, provided it is at the beginning -or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of -any characters that are @emph{not} an @@-sign, space, newline, or tab. - -@smallexample -\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b -@end smallexample - -One can write more complicated expressions, but I found that this -expression is good enough, so I use it. - -Here is the @code{the-the} function, as I include it in my -@file{.emacs} file, along with a handy global key binding: - -@smallexample -@group -(defun the-the () - "Search forward for for a duplicated word." - (interactive) - (message "Searching for for duplicated words ...") - (push-mark) -@end group -@group - ;; This regexp is not perfect - ;; but is fairly good over all: - (if (re-search-forward - "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move) - (message "Found duplicated word.") - (message "End of buffer"))) -@end group - -@group -;; Bind `the-the' to C-c \ -(global-set-key "\C-c\\" 'the-the) -@end group -@end smallexample - -@sp 1 -Here is test text: - -@smallexample -@group -one two two three four five -five six seven -@end group -@end smallexample - -You can substitute the other regular expressions shown above in the -function definition and try each of them on this list. - -@node Kill Ring, Full Graph, the-the, Top -@appendix Handling the Kill Ring -@cindex Kill ring handling -@cindex Handling the kill ring -@cindex Ring, making a list like a - -The kill ring is a list that is transformed into a ring by the -workings of the @code{current-kill} function. The @code{yank} and -@code{yank-pop} commands use the @code{current-kill} function. - -This appendix describes the @code{current-kill} function as well as -both the @code{yank} and the @code{yank-pop} commands, but first, -consider the workings of the kill ring. - -@menu -* What the Kill Ring Does:: -* current-kill:: -* yank:: Paste a copy of a clipped element. -* yank-pop:: Insert element pointed to. -* ring file:: -@end menu - -@node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring -@ifnottex -@unnumberedsec What the Kill Ring Does -@end ifnottex - -@need 1250 -The kill ring has a default maximum length of sixty items; this number -is too large for an explanation. Instead, set it to four. Please -evaluate the following: - -@smallexample -@group -(setq old-kill-ring-max kill-ring-max) -(setq kill-ring-max 4) -@end group -@end smallexample - -@noindent -Then, please copy each line of the following indented example into the -kill ring. You may kill each line with @kbd{C-k} or mark it and copy -it with @kbd{M-w}. - -@noindent -(In a read-only buffer, such as the @file{*info*} buffer, the kill -command, @kbd{C-k} (@code{kill-line}), will not remove the text, -merely copy it to the kill ring. However, your machine may beep at -you. Alternatively, for silence, you may copy the region of each line -with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark -each line for this command to succeed, but it does not matter at which -end you put point or mark.) - -@need 1250 -@noindent -Please invoke the calls in order, so that five elements attempt to -fill the kill ring: - -@smallexample -@group -first some text -second piece of text -third line -fourth line of text -fifth bit of text -@end group -@end smallexample - -@need 1250 -@noindent -Then find the value of @code{kill-ring} by evaluating - -@smallexample -kill-ring -@end smallexample - -@need 800 -@noindent -It is: - -@smallexample -@group -("fifth bit of text" "fourth line of text" -"third line" "second piece of text") -@end group -@end smallexample - -@noindent -The first element, @samp{first some text}, was dropped. - -@need 1250 -To return to the old value for the length of the kill ring, evaluate: - -@smallexample -(setq kill-ring-max old-kill-ring-max) -@end smallexample - -@node current-kill, yank, What the Kill Ring Does, Kill Ring -@comment node-name, next, previous, up -@appendixsec The @code{current-kill} Function -@findex current-kill - -The @code{current-kill} function changes the element in the kill ring -to which @code{kill-ring-yank-pointer} points. (Also, the -@code{kill-new} function sets @code{kill-ring-yank-pointer} to point -to the latest element of the the kill ring. The @code{kill-new} -function is used directly or indirectly by @code{kill-append}, -@code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line}, -and @code{kill-region}.) - -@menu -* Code for current-kill:: -* Understanding current-kill:: -@end menu - -@node Code for current-kill, Understanding current-kill, current-kill, current-kill -@ifnottex -@unnumberedsubsec The code for @code{current-kill} -@end ifnottex - - -@need 1500 -The @code{current-kill} function is used by @code{yank} and by -@code{yank-pop}. Here is the code for @code{current-kill}: - -@smallexample -@group -(defun current-kill (n &optional do-not-move) - "Rotate the yanking point by N places, and then return that kill. -If N is zero, `interprogram-paste-function' is set, and calling it -returns a string, then that string is added to the front of the -kill ring and returned as the latest kill. -@end group -@group -If optional arg DO-NOT-MOVE is non-nil, then don't actually move the -yanking point; just return the Nth kill forward." - (let ((interprogram-paste (and (= n 0) - interprogram-paste-function - (funcall interprogram-paste-function)))) -@end group -@group - (if interprogram-paste - (progn - ;; Disable the interprogram cut function when we add the new - ;; text to the kill ring, so Emacs doesn't try to own the - ;; selection, with identical text. - (let ((interprogram-cut-function nil)) - (kill-new interprogram-paste)) - interprogram-paste) -@end group -@group - (or kill-ring (error "Kill ring is empty")) - (let ((ARGth-kill-element - (nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) - (car ARGth-kill-element))))) -@end group -@end smallexample - -Remember also that the @code{kill-new} function sets -@code{kill-ring-yank-pointer} to the latest element of the the kill -ring, which means that all the functions that call it set the value -indirectly: @code{kill-append}, @code{copy-region-as-kill}, -@code{kill-ring-save}, @code{kill-line}, and @code{kill-region}. - -@need 1500 -Here is the line in @code{kill-new}, which is explained in -@ref{kill-new function, , The @code{kill-new} function}. - -@smallexample -(setq kill-ring-yank-pointer kill-ring) -@end smallexample - -@node Understanding current-kill, , Code for current-kill, current-kill -@ifnottex -@unnumberedsubsec @code{current-kill} in Outline -@end ifnottex - -The @code{current-kill} function looks complex, but as usual, it can -be understood by taking it apart piece by piece. First look at it in -skeletal form: - -@smallexample -@group -(defun current-kill (n &optional do-not-move) - "Rotate the yanking point by N places, and then return that kill." - (let @var{varlist} - @var{body}@dots{}) -@end group -@end smallexample - -This function takes two arguments, one of which is optional. It has a -documentation string. It is @emph{not} interactive. - -@menu -* Body of current-kill:: -* Digression concerning error:: How to mislead humans, but not computers. -* Determining the Element:: -@end menu - -@node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill -@ifnottex -@unnumberedsubsubsec The Body of @code{current-kill} -@end ifnottex - -The body of the function definition is a @code{let} expression, which -itself has a body as well as a @var{varlist}. - -The @code{let} expression declares a variable that will be only usable -within the bounds of this function. This variable is called -@code{interprogram-paste} and is for copying to another program. It -is not for copying within this instance of GNU Emacs. Most window -systems provide a facility for interprogram pasting. Sadly, that -facility usually provides only for the last element. Most windowing -systems have not adopted a ring of many possibilities, even though -Emacs has provided it for decades. - -The @code{if} expression has two parts, one if there exists -@code{interprogram-paste} and one if not. - -@need 2000 -Let us consider the `if not' or else-part of the @code{current-kill} -function. (The then-part uses the the @code{kill-new} function, which -we have already described. @xref{kill-new function, , The -@code{kill-new} function}.) - -@smallexample -@group -(or kill-ring (error "Kill ring is empty")) -(let ((ARGth-kill-element - (nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) - (car ARGth-kill-element)) -@end group -@end smallexample - -@noindent -The code first checks whether the kill ring has content; otherwise it -signals an error. - -@need 1000 -Note that the @code{or} expression is very similar to testing length -with an @code{if}: - -@findex zerop -@findex error -@smallexample -@group -(if (zerop (length kill-ring)) ; @r{if-part} - (error "Kill ring is empty")) ; @r{then-part} - ;; No else-part -@end group -@end smallexample - -@noindent -If there is not anything in the kill ring, its length must be zero and -an error message sent to the user: @samp{Kill ring is empty}. The -@code{current-kill} function uses an @code{or} expression which is -simpler. But an @code{if} expression reminds us what goes on. - -This @code{if} expression uses the function @code{zerop} which returns -true if the value it is testing is zero. When @code{zerop} tests -true, the then-part of the @code{if} is evaluated. The then-part is a -list starting with the function @code{error}, which is a function that -is similar to the @code{message} function -(@pxref{message, , The @code{message} Function}) in that -it prints a one-line message in the echo area. However, in addition -to printing a message, @code{error} also stops evaluation of the -function within which it is embedded. This means that the rest of the -function will not be evaluated if the length of the kill ring is zero. - -Then the @code{current-kill} function selects the element to return. -The selection depends on the number of places that @code{current-kill} -rotates and on where @code{kill-ring-yank-pointer} points. - -Next, either the optional @code{do-not-move} argument is true or the -current value of @code{kill-ring-yank-pointer} is set to point to the -list. Finally, another expression returns the first element of the -list even if the @code{do-not-move} argument is true. - -@node Digression concerning error, Determining the Element, Body of current-kill, Understanding current-kill -@ifnottex -@unnumberedsubsubsec Digression about the word `error' -@end ifnottex - -In my opinion, it is slightly misleading, at least to humans, to use -the term `error' as the name of the @code{error} function. A better -term would be `cancel'. Strictly speaking, of course, you cannot -point to, much less rotate a pointer to a list that has no length, so -from the point of view of the computer, the word `error' is correct. -But a human expects to attempt this sort of thing, if only to find out -whether the kill ring is full or empty. This is an act of -exploration. - -From the human point of view, the act of exploration and discovery is -not necessarily an error, and therefore should not be labelled as one, -even in the bowels of a computer. As it is, the code in Emacs implies -that a human who is acting virtuously, by exploring his or her -environment, is making an error. This is bad. Even though the computer -takes the same steps as it does when there is an `error', a term such as -`cancel' would have a clearer connotation. - -@node Determining the Element, , Digression concerning error, Understanding current-kill -@ifnottex -@unnumberedsubsubsec Determining the Element -@end ifnottex - -Among other actions, the else-part of the @code{if} expression sets -the value of @code{kill-ring-yank-pointer} to -@code{ARGth-kill-element} when the kill ring has something in it and -the value of @code{do-not-move} is @code{nil}. - -@need 800 -The code looks like this: - -@smallexample -@group -(nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) -@end group -@end smallexample - -This needs some examination. Unless it is not supposed to move the -pointer, the @code{current-kill} function changes where -@code{kill-ring-yank-pointer} points. -That is what the -@w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}} -expression does. Also, clearly, @code{ARGth-kill-element} is being -set to be equal to some @sc{cdr} of the kill ring, using the -@code{nthcdr} function that is described in an earlier section. -(@xref{copy-region-as-kill}.) How does it do this? - -As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function -works by repeatedly taking the @sc{cdr} of a list---it takes the -@sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{} - -@need 800 -The two following expressions produce the same result: - -@smallexample -@group -(setq kill-ring-yank-pointer (cdr kill-ring)) - -(setq kill-ring-yank-pointer (nthcdr 1 kill-ring)) -@end group -@end smallexample - -However, the @code{nthcdr} expression is more complicated. It uses -the @code{mod} function to determine which @sc{cdr} to select. - -(You will remember to look at inner functions first; indeed, we will -have to go inside the @code{mod}.) - -The @code{mod} function returns the value of its first argument modulo -the second; that is to say, it returns the remainder after dividing -the first argument by the second. The value returned has the same -sign as the second argument. - -@need 800 -Thus, - -@smallexample -@group -(mod 12 4) - @result{} 0 ;; @r{because there is no remainder} -(mod 13 4) - @result{} 1 -@end group -@end smallexample - -@need 1250 -In this case, the first argument is often smaller than the second. -That is fine. - -@smallexample -@group -(mod 0 4) - @result{} 0 -(mod 1 4) - @result{} 1 -@end group -@end smallexample - -We can guess what the @code{-} function does. It is like @code{+} but -subtracts instead of adds; the @code{-} function subtracts its second -argument from its first. Also, we already know what the @code{length} -function does (@pxref{length}). It returns the length of a list. - -And @code{n} is the name of the required argument to the -@code{current-kill} function. - -@need 1250 -So when the first argument to @code{nthcdr} is zero, the @code{nthcdr} -expression returns the whole list, as you can see by evaluating the -following: - -@smallexample -@group -;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four} -;; @r{and} (mod (- 0 4) 4) @result{} 0 -(nthcdr (mod (- 0 4) 4) - '("fourth line of text" - "third line" - "second piece of text" - "first some text")) -@end group -@end smallexample - -@need 1250 -When the first argument to the @code{current-kill} function is one, -the @code{nthcdr} expression returns the list without its first -element. - -@smallexample -@group -(nthcdr (mod (- 1 4) 4) - '("fourth line of text" - "third line" - "second piece of text" - "first some text")) -@end group -@end smallexample - -@cindex @samp{global variable} defined -@cindex @samp{variable, global}, defined -Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer} -are @dfn{global variables}. That means that any expression in Emacs -Lisp can access them. They are not like the local variables set by -@code{let} or like the symbols in an argument list. -Local variables can only be accessed -within the @code{let} that defines them or the function that specifies -them in an argument list (and within expressions called by them). - -@ignore -@c texi2dvi fails when the name of the section is within ifnottex ... -(@xref{Prevent confusion, , @code{let} Prevents Confusion}, and -@ref{defun, , The @code{defun} Special Form}.) -@end ignore - -@node yank, yank-pop, current-kill, Kill Ring -@comment node-name, next, previous, up -@appendixsec @code{yank} -@findex yank - -After learning about @code{current-kill}, the code for the -@code{yank} function is almost easy. - -The @code{yank} function does not use the -@code{kill-ring-yank-pointer} variable directly. It calls -@code{insert-for-yank} which calls @code{current-kill} which sets the -@code{kill-ring-yank-pointer} variable. - -@need 1250 -The code looks like this: - -@c in GNU Emacs 22 -@smallexample -@group -(defun yank (&optional arg) - "Reinsert (\"paste\") the last stretch of killed text. -More precisely, reinsert the stretch of killed text most recently -killed OR yanked. Put point at end, and set mark at beginning. -With just \\[universal-argument] as argument, same but put point at -beginning (and mark at end). With argument N, reinsert the Nth most -recently killed stretch of killed text. - -When this command inserts killed text into the buffer, it honors -`yank-excluded-properties' and `yank-handler' as described in the -doc string for `insert-for-yank-1', which see. - -See also the command \\[yank-pop]." -@end group -@group - (interactive "*P") - (setq yank-window-start (window-start)) - ;; If we don't get all the way thru, make last-command indicate that - ;; for the following command. - (setq this-command t) - (push-mark (point)) -@end group -@group - (insert-for-yank (current-kill (cond - ((listp arg) 0) - ((eq arg '-) -2) - (t (1- arg))))) - (if (consp arg) - ;; This is like exchange-point-and-mark, - ;; but doesn't activate the mark. - ;; It is cleaner to avoid activation, even though the command - ;; loop would deactivate the mark because we inserted text. - (goto-char (prog1 (mark t) - (set-marker (mark-marker) (point) (current-buffer))))) -@end group -@group - ;; If we do get all the way thru, make this-command indicate that. - (if (eq this-command t) - (setq this-command 'yank)) - nil) -@end group -@end smallexample - -The key expression is @code{insert-for-yank}, which inserts the string -returned by @code{current-kill}, but removes some text properties from -it. - -However, before getting to that expression, the function sets the value -of @code{yank-window-start} to the position returned by the -@code{(window-start)} expression, the position at which the display -currently starts. The @code{yank} function also sets -@code{this-command} and pushes the mark. - -After it yanks the appropriate element, if the optional argument is a -@sc{cons} rather than a number or nothing, it puts point at beginning -of the yanked text and mark at its end. - -(The @code{prog1} function is like @code{progn} but returns the value -of its first argument rather than the value of its last argument. Its -first argument is forced to return the buffer's mark as an integer. -You can see the documentation for these functions by placing point -over them in this buffer and then typing @kbd{C-h f} -(@code{describe-function}) followed by a @kbd{RET}; the default is the -function.) - -The last part of the function tells what to do when it succeeds. - -@node yank-pop, ring file, yank, Kill Ring -@comment node-name, next, previous, up -@appendixsec @code{yank-pop} -@findex yank-pop - -After understanding @code{yank} and @code{current-kill}, you know how -to approach the @code{yank-pop} function. Leaving out the -documentation to save space, it looks like this: - -@c GNU Emacs 22 -@smallexample -@group -(defun yank-pop (&optional arg) - "@dots{}" - (interactive "*p") - (if (not (eq last-command 'yank)) - (error "Previous command was not a yank")) -@end group -@group - (setq this-command 'yank) - (unless arg (setq arg 1)) - (let ((inhibit-read-only t) - (before (< (point) (mark t)))) -@end group -@group - (if before - (funcall (or yank-undo-function 'delete-region) (point) (mark t)) - (funcall (or yank-undo-function 'delete-region) (mark t) (point))) - (setq yank-undo-function nil) -@end group -@group - (set-marker (mark-marker) (point) (current-buffer)) - (insert-for-yank (current-kill arg)) - ;; Set the window start back where it was in the yank command, - ;; if possible. - (set-window-start (selected-window) yank-window-start t) -@end group -@group - (if before - ;; This is like exchange-point-and-mark, - ;; but doesn't activate the mark. - ;; It is cleaner to avoid activation, even though the command - ;; loop would deactivate the mark because we inserted text. - (goto-char (prog1 (mark t) - (set-marker (mark-marker) - (point) - (current-buffer)))))) - nil) -@end group -@end smallexample - -The function is interactive with a small @samp{p} so the prefix -argument is processed and passed to the function. The command can -only be used after a previous yank; otherwise an error message is -sent. This check uses the variable @code{last-command} which is set -by @code{yank} and is discussed elsewhere. -(@xref{copy-region-as-kill}.) - -The @code{let} clause sets the variable @code{before} to true or false -depending whether point is before or after mark and then the region -between point and mark is deleted. This is the region that was just -inserted by the previous yank and it is this text that will be -replaced. - -@code{funcall} calls its first argument as a function, passing -remaining arguments to it. The first argument is whatever the -@code{or} expression returns. The two remaining arguments are the -positions of point and mark set by the preceding @code{yank} command. - -There is more, but that is the hardest part. - -@node ring file, , yank-pop, Kill Ring -@comment node-name, next, previous, up -@appendixsec The @file{ring.el} File -@cindex @file{ring.el} file - -Interestingly, GNU Emacs posses a file called @file{ring.el} that -provides many of the features we just discussed. But functions such -as @code{kill-ring-yank-pointer} do not use this library, possibly -because they were written earlier. - -@node Full Graph, Free Software and Free Manuals, Kill Ring, Top -@appendix A Graph with Labelled Axes - -Printed axes help you understand a graph. They convey scale. In an -earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we -wrote the code to print the body of a graph. Here we write the code -for printing and labelling vertical and horizontal axes, along with the -body itself. - -@menu -* Labelled Example:: -* print-graph Varlist:: @code{let} expression in @code{print-graph}. -* print-Y-axis:: Print a label for the vertical axis. -* print-X-axis:: Print a horizontal label. -* Print Whole Graph:: The function to print a complete graph. -@end menu - -@node Labelled Example, print-graph Varlist, Full Graph, Full Graph -@ifnottex -@unnumberedsec Labelled Example Graph -@end ifnottex - -Since insertions fill a buffer to the right and below point, the new -graph printing function should first print the Y or vertical axis, -then the body of the graph, and finally the X or horizontal axis. -This sequence lays out for us the contents of the function: - -@enumerate -@item -Set up code. - -@item -Print Y axis. - -@item -Print body of graph. - -@item -Print X axis. -@end enumerate - -@need 800 -Here is an example of how a finished graph should look: - -@smallexample -@group - 10 - - * - * * - * ** - * *** - 5 - * ******* - * *** ******* - ************* - *************** - 1 - **************** - | | | | - 1 5 10 15 -@end group -@end smallexample - -@noindent -In this graph, both the vertical and the horizontal axes are labelled -with numbers. However, in some graphs, the horizontal axis is time -and would be better labelled with months, like this: - -@smallexample -@group - 5 - * - * ** * - ******* - ********** ** - 1 - ************** - | ^ | - Jan June Jan -@end group -@end smallexample - -Indeed, with a little thought, we can easily come up with a variety of -vertical and horizontal labelling schemes. Our task could become -complicated. But complications breed confusion. Rather than permit -this, it is better choose a simple labelling scheme for our first -effort, and to modify or replace it later. - -@need 1200 -These considerations suggest the following outline for the -@code{print-graph} function: - -@smallexample -@group -(defun print-graph (numbers-list) - "@var{documentation}@dots{}" - (let ((height @dots{} - @dots{})) -@end group -@group - (print-Y-axis height @dots{} ) - (graph-body-print numbers-list) - (print-X-axis @dots{} ))) -@end group -@end smallexample - -We can work on each part of the @code{print-graph} function definition -in turn. - -@node print-graph Varlist, print-Y-axis, Labelled Example, Full Graph -@comment node-name, next, previous, up -@appendixsec The @code{print-graph} Varlist -@cindex @code{print-graph} varlist - -In writing the @code{print-graph} function, the first task is to write -the varlist in the @code{let} expression. (We will leave aside for the -moment any thoughts about making the function interactive or about the -contents of its documentation string.) - -The varlist should set several values. Clearly, the top of the label -for the vertical axis must be at least the height of the graph, which -means that we must obtain this information here. Note that the -@code{print-graph-body} function also requires this information. There -is no reason to calculate the height of the graph in two different -places, so we should change @code{print-graph-body} from the way we -defined it earlier to take advantage of the calculation. - -Similarly, both the function for printing the X axis labels and the -@code{print-graph-body} function need to learn the value of the width of -each symbol. We can perform the calculation here and change the -definition for @code{print-graph-body} from the way we defined it in the -previous chapter. - -The length of the label for the horizontal axis must be at least as long -as the graph. However, this information is used only in the function -that prints the horizontal axis, so it does not need to be calculated here. - -These thoughts lead us directly to the following form for the varlist -in the @code{let} for @code{print-graph}: - -@smallexample -@group -(let ((height (apply 'max numbers-list)) ; @r{First version.} - (symbol-width (length graph-blank))) -@end group -@end smallexample - -@noindent -As we shall see, this expression is not quite right. - -@need 2000 -@node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph -@comment node-name, next, previous, up -@appendixsec The @code{print-Y-axis} Function -@cindex Axis, print vertical -@cindex Y axis printing -@cindex Vertical axis printing -@cindex Print vertical axis - -The job of the @code{print-Y-axis} function is to print a label for -the vertical axis that looks like this: - -@smallexample -@group - 10 - - - - - - 5 - - - - - 1 - -@end group -@end smallexample - -@noindent -The function should be passed the height of the graph, and then should -construct and insert the appropriate numbers and marks. - -@menu -* print-Y-axis in Detail:: -* Height of label:: What height for the Y axis? -* Compute a Remainder:: How to compute the remainder of a division. -* Y Axis Element:: Construct a line for the Y axis. -* Y-axis-column:: Generate a list of Y axis labels. -* print-Y-axis Penultimate:: A not quite final version. -@end menu - -@node print-Y-axis in Detail, Height of label, print-Y-axis, print-Y-axis -@ifnottex -@unnumberedsubsec The @code{print-Y-axis} Function in Detail -@end ifnottex - -It is easy enough to see in the figure what the Y axis label should -look like; but to say in words, and then to write a function -definition to do the job is another matter. It is not quite true to -say that we want a number and a tic every five lines: there are only -three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4), -but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8, -and 9). It is better to say that we want a number and a tic mark on -the base line (number 1) and then that we want a number and a tic on -the fifth line from the bottom and on every line that is a multiple of -five. - -@node Height of label, Compute a Remainder, print-Y-axis in Detail, print-Y-axis -@ifnottex -@unnumberedsubsec What height should the label be? -@end ifnottex - -The next issue is what height the label should be? Suppose the maximum -height of tallest column of the graph is seven. Should the highest -label on the Y axis be @samp{5 -}, and should the graph stick up above -the label? Or should the highest label be @samp{7 -}, and mark the peak -of the graph? Or should the highest label be @code{10 -}, which is a -multiple of five, and be higher than the topmost value of the graph? - -The latter form is preferred. Most graphs are drawn within rectangles -whose sides are an integral number of steps long---5, 10, 15, and so -on for a step distance of five. But as soon as we decide to use a -step height for the vertical axis, we discover that the simple -expression in the varlist for computing the height is wrong. The -expression is @code{(apply 'max numbers-list)}. This returns the -precise height, not the maximum height plus whatever is necessary to -round up to the nearest multiple of five. A more complex expression -is required. - -As usual in cases like this, a complex problem becomes simpler if it is -divided into several smaller problems. - -First, consider the case when the highest value of the graph is an -integral multiple of five---when it is 5, 10, 15, or some higher -multiple of five. We can use this value as the Y axis height. - -A fairly simply way to determine whether a number is a multiple of -five is to divide it by five and see if the division results in a -remainder. If there is no remainder, the number is a multiple of -five. Thus, seven divided by five has a remainder of two, and seven -is not an integral multiple of five. Put in slightly different -language, more reminiscent of the classroom, five goes into seven -once, with a remainder of two. However, five goes into ten twice, -with no remainder: ten is an integral multiple of five. - -@node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis -@appendixsubsec Side Trip: Compute a Remainder - -@findex % @r{(remainder function)} -@cindex Remainder function, @code{%} -In Lisp, the function for computing a remainder is @code{%}. The -function returns the remainder of its first argument divided by its -second argument. As it happens, @code{%} is a function in Emacs Lisp -that you cannot discover using @code{apropos}: you find nothing if you -type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to -learn of the existence of @code{%} is to read about it in a book such -as this or in the Emacs Lisp sources. - -You can try the @code{%} function by evaluating the following two -expressions: - -@smallexample -@group -(% 7 5) - -(% 10 5) -@end group -@end smallexample - -@noindent -The first expression returns 2 and the second expression returns 0. - -To test whether the returned value is zero or some other number, we -can use the @code{zerop} function. This function returns @code{t} if -its argument, which must be a number, is zero. - -@smallexample -@group -(zerop (% 7 5)) - @result{} nil - -(zerop (% 10 5)) - @result{} t -@end group -@end smallexample - -Thus, the following expression will return @code{t} if the height -of the graph is evenly divisible by five: - -@smallexample -(zerop (% height 5)) -@end smallexample - -@noindent -(The value of @code{height}, of course, can be found from @code{(apply -'max numbers-list)}.) - -On the other hand, if the value of @code{height} is not a multiple of -five, we want to reset the value to the next higher multiple of five. -This is straightforward arithmetic using functions with which we are -already familiar. First, we divide the value of @code{height} by five -to determine how many times five goes into the number. Thus, five -goes into twelve twice. If we add one to this quotient and multiply by -five, we will obtain the value of the next multiple of five that is -larger than the height. Five goes into twelve twice. Add one to two, -and multiply by five; the result is fifteen, which is the next multiple -of five that is higher than twelve. The Lisp expression for this is: - -@smallexample -(* (1+ (/ height 5)) 5) -@end smallexample - -@noindent -For example, if you evaluate the following, the result is 15: - -@smallexample -(* (1+ (/ 12 5)) 5) -@end smallexample - -All through this discussion, we have been using `five' as the value -for spacing labels on the Y axis; but we may want to use some other -value. For generality, we should replace `five' with a variable to -which we can assign a value. The best name I can think of for this -variable is @code{Y-axis-label-spacing}. - -@need 1250 -Using this term, and an @code{if} expression, we produce the -following: - -@smallexample -@group -(if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing)) -@end group -@end smallexample - -@noindent -This expression returns the value of @code{height} itself if the height -is an even multiple of the value of the @code{Y-axis-label-spacing} or -else it computes and returns a value of @code{height} that is equal to -the next higher multiple of the value of the @code{Y-axis-label-spacing}. - -We can now include this expression in the @code{let} expression of the -@code{print-graph} function (after first setting the value of -@code{Y-axis-label-spacing}): -@vindex Y-axis-label-spacing - -@smallexample -@group -(defvar Y-axis-label-spacing 5 - "Number of lines from one Y axis label to next.") -@end group - -@group -@dots{} -(let* ((height (apply 'max numbers-list)) - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height -@end group -@group - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) - (symbol-width (length graph-blank)))) -@dots{} -@end group -@end smallexample - -@noindent -(Note use of the @code{let*} function: the initial value of height is -computed once by the @code{(apply 'max numbers-list)} expression and -then the resulting value of @code{height} is used to compute its -final value. @xref{fwd-para let, , The @code{let*} expression}, for -more about @code{let*}.) - -@node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis -@appendixsubsec Construct a Y Axis Element - -When we print the vertical axis, we want to insert strings such as -@w{@samp{5 -}} and @w{@samp{10 - }} every five lines. -Moreover, we want the numbers and dashes to line up, so shorter -numbers must be padded with leading spaces. If some of the strings -use two digit numbers, the strings with single digit numbers must -include a leading blank space before the number. - -@findex number-to-string -To figure out the length of the number, the @code{length} function is -used. But the @code{length} function works only with a string, not with -a number. So the number has to be converted from being a number to -being a string. This is done with the @code{number-to-string} function. -For example, - -@smallexample -@group -(length (number-to-string 35)) - @result{} 2 - -(length (number-to-string 100)) - @result{} 3 -@end group -@end smallexample - -@noindent -(@code{number-to-string} is also called @code{int-to-string}; you will -see this alternative name in various sources.) - -In addition, in each label, each number is followed by a string such -as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker. -This variable is defined with @code{defvar}: - -@vindex Y-axis-tic -@smallexample -@group -(defvar Y-axis-tic " - " - "String that follows number in a Y axis label.") -@end group -@end smallexample - -The length of the Y label is the sum of the length of the Y axis tic -mark and the length of the number of the top of the graph. - -@smallexample -(length (concat (number-to-string height) Y-axis-tic))) -@end smallexample - -This value will be calculated by the @code{print-graph} function in -its varlist as @code{full-Y-label-width} and passed on. (Note that we -did not think to include this in the varlist when we first proposed it.) - -To make a complete vertical axis label, a tic mark is concatenated -with a number; and the two together may be preceded by one or more -spaces depending on how long the number is. The label consists of -three parts: the (optional) leading spaces, the number, and the tic -mark. The function is passed the value of the number for the specific -row, and the value of the width of the top line, which is calculated -(just once) by @code{print-graph}. - -@smallexample -@group -(defun Y-axis-element (number full-Y-label-width) - "Construct a NUMBERed label element. -A numbered element looks like this ` 5 - ', -and is padded as needed so all line up with -the element for the largest number." -@end group -@group - (let* ((leading-spaces - (- full-Y-label-width - (length - (concat (number-to-string number) - Y-axis-tic))))) -@end group -@group - (concat - (make-string leading-spaces ? ) - (number-to-string number) - Y-axis-tic))) -@end group -@end smallexample - -The @code{Y-axis-element} function concatenates together the leading -spaces, if any; the number, as a string; and the tic mark. - -To figure out how many leading spaces the label will need, the -function subtracts the actual length of the label---the length of the -number plus the length of the tic mark---from the desired label width. - -@findex make-string -Blank spaces are inserted using the @code{make-string} function. This -function takes two arguments: the first tells it how long the string -will be and the second is a symbol for the character to insert, in a -special format. The format is a question mark followed by a blank -space, like this, @samp{? }. @xref{Character Type, , Character Type, -elisp, The GNU Emacs Lisp Reference Manual}, for a description of the -syntax for characters. (Of course, you might want to replace the -blank space by some other character @dots{} You know what to do.) - -The @code{number-to-string} function is used in the concatenation -expression, to convert the number to a string that is concatenated -with the leading spaces and the tic mark. - -@node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis -@appendixsubsec Create a Y Axis Column - -The preceding functions provide all the tools needed to construct a -function that generates a list of numbered and blank strings to insert -as the label for the vertical axis: - -@findex Y-axis-column -@smallexample -@group -(defun Y-axis-column (height width-of-label) - "Construct list of Y axis labels and blank strings. -For HEIGHT of line above base and WIDTH-OF-LABEL." - (let (Y-axis) -@group -@end group - (while (> height 1) - (if (zerop (% height Y-axis-label-spacing)) - ;; @r{Insert label.} - (setq Y-axis - (cons - (Y-axis-element height width-of-label) - Y-axis)) -@group -@end group - ;; @r{Else, insert blanks.} - (setq Y-axis - (cons - (make-string width-of-label ? ) - Y-axis))) - (setq height (1- height))) - ;; @r{Insert base line.} - (setq Y-axis - (cons (Y-axis-element 1 width-of-label) Y-axis)) - (nreverse Y-axis))) -@end group -@end smallexample - -In this function, we start with the value of @code{height} and -repetitively subtract one from its value. After each subtraction, we -test to see whether the value is an integral multiple of the -@code{Y-axis-label-spacing}. If it is, we construct a numbered label -using the @code{Y-axis-element} function; if not, we construct a -blank label using the @code{make-string} function. The base line -consists of the number one followed by a tic mark. - -@need 2000 -@node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis -@appendixsubsec The Not Quite Final Version of @code{print-Y-axis} - -The list constructed by the @code{Y-axis-column} function is passed to -the @code{print-Y-axis} function, which inserts the list as a column. - -@findex print-Y-axis -@smallexample -@group -(defun print-Y-axis (height full-Y-label-width) - "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH. -Height must be the maximum height of the graph. -Full width is the width of the highest label element." -;; Value of height and full-Y-label-width -;; are passed by `print-graph'. -@end group -@group - (let ((start (point))) - (insert-rectangle - (Y-axis-column height full-Y-label-width)) - ;; @r{Place point ready for inserting graph.} - (goto-char start) - ;; @r{Move point forward by value of} full-Y-label-width - (forward-char full-Y-label-width))) -@end group -@end smallexample - -The @code{print-Y-axis} uses the @code{insert-rectangle} function to -insert the Y axis labels created by the @code{Y-axis-column} function. -In addition, it places point at the correct position for printing the body of -the graph. - -You can test @code{print-Y-axis}: - -@enumerate -@item -Install - -@smallexample -@group -Y-axis-label-spacing -Y-axis-tic -Y-axis-element -Y-axis-column -print-Y-axis -@end group -@end smallexample - -@item -Copy the following expression: - -@smallexample -(print-Y-axis 12 5) -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the axis labels to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the @code{graph-body-print} expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the expression. -@end enumerate - -Emacs will print labels vertically, the top one being @w{@samp{10 -@w{ -}}}. (The @code{print-graph} function will pass the value of -@code{height-of-top-line}, which in this case will end up as 15, -thereby getting rid of what might appear as a bug.) - -@need 2000 -@node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph -@appendixsec The @code{print-X-axis} Function -@cindex Axis, print horizontal -@cindex X axis printing -@cindex Print horizontal axis -@cindex Horizontal axis printing - -X axis labels are much like Y axis labels, except that the ticks are on a -line above the numbers. Labels should look like this: - -@smallexample -@group - | | | | - 1 5 10 15 -@end group -@end smallexample - -The first tic is under the first column of the graph and is preceded by -several blank spaces. These spaces provide room in rows above for the Y -axis labels. The second, third, fourth, and subsequent ticks are all -spaced equally, according to the value of @code{X-axis-label-spacing}. - -The second row of the X axis consists of numbers, preceded by several -blank spaces and also separated according to the value of the variable -@code{X-axis-label-spacing}. - -The value of the variable @code{X-axis-label-spacing} should itself be -measured in units of @code{symbol-width}, since you may want to change -the width of the symbols that you are using to print the body of the -graph without changing the ways the graph is labelled. - -@menu -* Similarities differences:: Much like @code{print-Y-axis}, but not exactly. -* X Axis Tic Marks:: Create tic marks for the horizontal axis. -@end menu - -@node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis -@ifnottex -@unnumberedsubsec Similarities and differences -@end ifnottex - -The @code{print-X-axis} function is constructed in more or less the -same fashion as the @code{print-Y-axis} function except that it has -two lines: the line of tic marks and the numbers. We will write a -separate function to print each line and then combine them within the -@code{print-X-axis} function. - -This is a three step process: - -@enumerate -@item -Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}. - -@item -Write a function to print the X numbers, @code{print-X-axis-numbered-line}. - -@item -Write a function to print both lines, the @code{print-X-axis} function, -using @code{print-X-axis-tic-line} and -@code{print-X-axis-numbered-line}. -@end enumerate - -@node X Axis Tic Marks, , Similarities differences, print-X-axis -@appendixsubsec X Axis Tic Marks - -The first function should print the X axis tic marks. We must specify -the tic marks themselves and their spacing: - -@smallexample -@group -(defvar X-axis-label-spacing - (if (boundp 'graph-blank) - (* 5 (length graph-blank)) 5) - "Number of units from one X axis label to next.") -@end group -@end smallexample - -@noindent -(Note that the value of @code{graph-blank} is set by another -@code{defvar}. The @code{boundp} predicate checks whether it has -already been set; @code{boundp} returns @code{nil} if it has not. If -@code{graph-blank} were unbound and we did not use this conditional -construction, in a recent GNU Emacs, we would enter the debugger and -see an error message saying @samp{@w{Debugger entered--Lisp error:} -@w{(void-variable graph-blank)}}.) - -@need 1200 -Here is the @code{defvar} for @code{X-axis-tic-symbol}: - -@smallexample -@group -(defvar X-axis-tic-symbol "|" - "String to insert to point to a column in X axis.") -@end group -@end smallexample - -@need 1250 -The goal is to make a line that looks like this: - -@smallexample - | | | | -@end smallexample - -The first tic is indented so that it is under the first column, which is -indented to provide space for the Y axis labels. - -A tic element consists of the blank spaces that stretch from one tic to -the next plus a tic symbol. The number of blanks is determined by the -width of the tic symbol and the @code{X-axis-label-spacing}. - -@need 1250 -The code looks like this: - -@smallexample -@group -;;; X-axis-tic-element -@dots{} -(concat - (make-string - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol) -@dots{} -@end group -@end smallexample - -Next, we determine how many blanks are needed to indent the first tic -mark to the first column of the graph. This uses the value of -@code{full-Y-label-width} passed it by the @code{print-graph} function. - -@need 1250 -The code to make @code{X-axis-leading-spaces} -looks like this: - -@smallexample -@group -;; X-axis-leading-spaces -@dots{} -(make-string full-Y-label-width ? ) -@dots{} -@end group -@end smallexample - -We also need to determine the length of the horizontal axis, which is -the length of the numbers list, and the number of ticks in the horizontal -axis: - -@smallexample -@group -;; X-length -@dots{} -(length numbers-list) -@end group - -@group -;; tic-width -@dots{} -(* symbol-width X-axis-label-spacing) -@end group - -@group -;; number-of-X-ticks -(if (zerop (% (X-length tic-width))) - (/ (X-length tic-width)) - (1+ (/ (X-length tic-width)))) -@end group -@end smallexample - -@need 1250 -All this leads us directly to the function for printing the X axis tic line: - -@findex print-X-axis-tic-line -@smallexample -@group -(defun print-X-axis-tic-line - (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) - "Print ticks for X axis." - (insert X-axis-leading-spaces) - (insert X-axis-tic-symbol) ; @r{Under first column.} -@end group -@group - ;; @r{Insert second tic in the right spot.} - (insert (concat - (make-string - (- (* symbol-width X-axis-label-spacing) - ;; @r{Insert white space up to second tic symbol.} - (* 2 (length X-axis-tic-symbol))) - ? ) - X-axis-tic-symbol)) -@end group -@group - ;; @r{Insert remaining ticks.} - (while (> number-of-X-tics 1) - (insert X-axis-tic-element) - (setq number-of-X-tics (1- number-of-X-tics)))) -@end group -@end smallexample - -The line of numbers is equally straightforward: - -@need 1250 -First, we create a numbered element with blank spaces before each number: - -@findex X-axis-element -@smallexample -@group -(defun X-axis-element (number) - "Construct a numbered X axis element." - (let ((leading-spaces - (- (* symbol-width X-axis-label-spacing) - (length (number-to-string number))))) - (concat (make-string leading-spaces ? ) - (number-to-string number)))) -@end group -@end smallexample - -Next, we create the function to print the numbered line, starting with -the number ``1'' under the first column: - -@findex print-X-axis-numbered-line -@smallexample -@group -(defun print-X-axis-numbered-line - (number-of-X-tics X-axis-leading-spaces) - "Print line of X-axis numbers" - (let ((number X-axis-label-spacing)) - (insert X-axis-leading-spaces) - (insert "1") -@end group -@group - (insert (concat - (make-string - ;; @r{Insert white space up to next number.} - (- (* symbol-width X-axis-label-spacing) 2) - ? ) - (number-to-string number))) -@end group -@group - ;; @r{Insert remaining numbers.} - (setq number (+ number X-axis-label-spacing)) - (while (> number-of-X-tics 1) - (insert (X-axis-element number)) - (setq number (+ number X-axis-label-spacing)) - (setq number-of-X-tics (1- number-of-X-tics))))) -@end group -@end smallexample - -Finally, we need to write the @code{print-X-axis} that uses -@code{print-X-axis-tic-line} and -@code{print-X-axis-numbered-line}. - -The function must determine the local values of the variables used by both -@code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and -then it must call them. Also, it must print the carriage return that -separates the two lines. - -The function consists of a varlist that specifies five local variables, -and calls to each of the two line printing functions: - -@findex print-X-axis -@smallexample -@group -(defun print-X-axis (numbers-list) - "Print X axis labels to length of NUMBERS-LIST." - (let* ((leading-spaces - (make-string full-Y-label-width ? )) -@end group -@group - ;; symbol-width @r{is provided by} graph-body-print - (tic-width (* symbol-width X-axis-label-spacing)) - (X-length (length numbers-list)) -@end group -@group - (X-tic - (concat - (make-string -@end group -@group - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) -@end group -@group - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol)) -@end group -@group - (tic-number - (if (zerop (% X-length tic-width)) - (/ X-length tic-width) - (1+ (/ X-length tic-width))))) -@end group -@group - (print-X-axis-tic-line tic-number leading-spaces X-tic) - (insert "\n") - (print-X-axis-numbered-line tic-number leading-spaces))) -@end group -@end smallexample - -@need 1250 -You can test @code{print-X-axis}: - -@enumerate -@item -Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing}, -@code{print-X-axis-tic-line}, as well as @code{X-axis-element}, -@code{print-X-axis-numbered-line}, and @code{print-X-axis}. - -@item -Copy the following expression: - -@smallexample -@group -(progn - (let ((full-Y-label-width 5) - (symbol-width 1)) - (print-X-axis - '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16)))) -@end group -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the axis labels to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the test expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the expression. -@end enumerate - -@need 1250 -Emacs will print the horizontal axis like this: -@sp 1 - -@smallexample -@group - | | | | | - 1 5 10 15 20 -@end group -@end smallexample - -@node Print Whole Graph, , print-X-axis, Full Graph -@appendixsec Printing the Whole Graph -@cindex Printing the whole graph -@cindex Whole graph printing -@cindex Graph, printing all - -Now we are nearly ready to print the whole graph. - -The function to print the graph with the proper labels follows the -outline we created earlier (@pxref{Full Graph, , A Graph with Labelled -Axes}), but with additions. - -@need 1250 -Here is the outline: - -@smallexample -@group -(defun print-graph (numbers-list) - "@var{documentation}@dots{}" - (let ((height @dots{} - @dots{})) -@end group -@group - (print-Y-axis height @dots{} ) - (graph-body-print numbers-list) - (print-X-axis @dots{} ))) -@end group -@end smallexample - -@menu -* The final version:: A few changes. -* Test print-graph:: Run a short test. -* Graphing words in defuns:: Executing the final code. -* lambda:: How to write an anonymous function. -* mapcar:: Apply a function to elements of a list. -* Another Bug:: Yet another bug @dots{} most insidious. -* Final printed graph:: The graph itself! -@end menu - -@node The final version, Test print-graph, Print Whole Graph, Print Whole Graph -@ifnottex -@unnumberedsubsec Changes for the Final Version -@end ifnottex - -The final version is different from what we planned in two ways: -first, it contains additional values calculated once in the varlist; -second, it carries an option to specify the labels' increment per row. -This latter feature turns out to be essential; otherwise, a graph may -have more rows than fit on a display or on a sheet of paper. - -@need 1500 -This new feature requires a change to the @code{Y-axis-column} -function, to add @code{vertical-step} to it. The function looks like -this: - -@findex Y-axis-column @r{Final version.} -@smallexample -@group -;;; @r{Final version.} -(defun Y-axis-column - (height width-of-label &optional vertical-step) - "Construct list of labels for Y axis. -HEIGHT is maximum height of graph. -WIDTH-OF-LABEL is maximum width of label. -VERTICAL-STEP, an option, is a positive integer -that specifies how much a Y axis label increments -for each line. For example, a step of 5 means -that each line is five units of the graph." -@end group -@group - (let (Y-axis - (number-per-line (or vertical-step 1))) - (while (> height 1) - (if (zerop (% height Y-axis-label-spacing)) -@end group -@group - ;; @r{Insert label.} - (setq Y-axis - (cons - (Y-axis-element - (* height number-per-line) - width-of-label) - Y-axis)) -@end group -@group - ;; @r{Else, insert blanks.} - (setq Y-axis - (cons - (make-string width-of-label ? ) - Y-axis))) - (setq height (1- height))) -@end group -@group - ;; @r{Insert base line.} - (setq Y-axis (cons (Y-axis-element - (or vertical-step 1) - width-of-label) - Y-axis)) - (nreverse Y-axis))) -@end group -@end smallexample - -The values for the maximum height of graph and the width of a symbol -are computed by @code{print-graph} in its @code{let} expression; so -@code{graph-body-print} must be changed to accept them. - -@findex graph-body-print @r{Final version.} -@smallexample -@group -;;; @r{Final version.} -(defun graph-body-print (numbers-list height symbol-width) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -HEIGHT is maximum height of graph. -SYMBOL-WIDTH is number of each column." -@end group -@group - (let (from-position) - (while numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) - (goto-char from-position) - (forward-char symbol-width) -@end group -@group - ;; @r{Draw graph column by column.} - (sit-for 0) - (setq numbers-list (cdr numbers-list))) - ;; @r{Place point for X axis labels.} - (forward-line height) - (insert "\n"))) -@end group -@end smallexample - -@need 1250 -Finally, the code for the @code{print-graph} function: - -@findex print-graph @r{Final version.} -@smallexample -@group -;;; @r{Final version.} -(defun print-graph - (numbers-list &optional vertical-step) - "Print labelled bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -@end group - -@group -Optionally, VERTICAL-STEP, a positive integer, -specifies how much a Y axis label increments for -each line. For example, a step of 5 means that -each row is five units." -@end group -@group - (let* ((symbol-width (length graph-blank)) - ;; @code{height} @r{is both the largest number} - ;; @r{and the number with the most digits.} - (height (apply 'max numbers-list)) -@end group -@group - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) -@end group -@group - (vertical-step (or vertical-step 1)) - (full-Y-label-width - (length -@end group -@group - (concat - (number-to-string - (* height-of-top-line vertical-step)) - Y-axis-tic)))) -@end group - -@group - (print-Y-axis - height-of-top-line full-Y-label-width vertical-step) -@end group -@group - (graph-body-print - numbers-list height-of-top-line symbol-width) - (print-X-axis numbers-list))) -@end group -@end smallexample - -@node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph -@appendixsubsec Testing @code{print-graph} - -@need 1250 -We can test the @code{print-graph} function with a short list of numbers: - -@enumerate -@item -Install the final versions of @code{Y-axis-column}, -@code{graph-body-print}, and @code{print-graph} (in addition to the -rest of the code.) - -@item -Copy the following expression: - -@smallexample -(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1)) -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the axis labels to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the test expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the expression. -@end enumerate - -@need 1250 -Emacs will print a graph that looks like this: - -@smallexample -@group -10 - - - - * - ** * - 5 - **** * - **** *** - * ********* - ************ - 1 - ************* - - | | | | - 1 5 10 15 -@end group -@end smallexample - -@need 1200 -On the other hand, if you pass @code{print-graph} a -@code{vertical-step} value of 2, by evaluating this expression: - -@smallexample -(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2) -@end smallexample - -@need 1250 -@noindent -The graph looks like this: - -@smallexample -@group -20 - - - - * - ** * -10 - **** * - **** *** - * ********* - ************ - 2 - ************* - - | | | | - 1 5 10 15 -@end group -@end smallexample - -@noindent -(A question: is the `2' on the bottom of the vertical axis a bug or a -feature? If you think it is a bug, and should be a `1' instead, (or -even a `0'), you can modify the sources.) - -@node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph -@appendixsubsec Graphing Numbers of Words and Symbols - -Now for the graph for which all this code was written: a graph that -shows how many function definitions contain fewer than 10 words and -symbols, how many contain between 10 and 19 words and symbols, how -many contain between 20 and 29 words and symbols, and so on. - -This is a multi-step process. First make sure you have loaded all the -requisite code. - -@need 1500 -It is a good idea to reset the value of @code{top-of-ranges} in case -you have set it to some different value. You can evaluate the -following: - -@smallexample -@group -(setq top-of-ranges - '(10 20 30 40 50 - 60 70 80 90 100 - 110 120 130 140 150 - 160 170 180 190 200 - 210 220 230 240 250 - 260 270 280 290 300) -@end group -@end smallexample - -@noindent -Next create a list of the number of words and symbols in each range. - -@need 1500 -@noindent -Evaluate the following: - -@smallexample -@group -(setq list-for-graph - (defuns-per-range - (sort - (recursive-lengths-list-many-files - (directory-files "/usr/local/emacs/lisp" - t ".+el$")) - '<) - top-of-ranges)) -@end group -@end smallexample - -@noindent -On my old machine, this took about an hour. It looked though 303 Lisp -files in my copy of Emacs version 19.23. After all that computing, -the @code{list-for-graph} had this value: - -@smallexample -@group -(537 1027 955 785 594 483 349 292 224 199 166 120 116 99 -90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220) -@end group -@end smallexample - -@noindent -This means that my copy of Emacs had 537 function definitions with -fewer than 10 words or symbols in them, 1,027 function definitions -with 10 to 19 words or symbols in them, 955 function definitions with -20 to 29 words or symbols in them, and so on. - -Clearly, just by looking at this list we can see that most function -definitions contain ten to thirty words and symbols. - -Now for printing. We do @emph{not} want to print a graph that is -1,030 lines high @dots{} Instead, we should print a graph that is -fewer than twenty-five lines high. A graph that height can be -displayed on almost any monitor, and easily printed on a sheet of paper. - -This means that each value in @code{list-for-graph} must be reduced to -one-fiftieth its present value. - -Here is a short function to do just that, using two functions we have -not yet seen, @code{mapcar} and @code{lambda}. - -@smallexample -@group -(defun one-fiftieth (full-range) - "Return list, each number one-fiftieth of previous." - (mapcar '(lambda (arg) (/ arg 50)) full-range)) -@end group -@end smallexample - -@node lambda, mapcar, Graphing words in defuns, Print Whole Graph -@appendixsubsec A @code{lambda} Expression: Useful Anonymity -@cindex Anonymous function -@findex lambda - -@code{lambda} is the symbol for an anonymous function, a function -without a name. Every time you use an anonymous function, you need to -include its whole body. - -@need 1250 -@noindent -Thus, - -@smallexample -(lambda (arg) (/ arg 50)) -@end smallexample - -@noindent -is a function definition that says `return the value resulting from -dividing whatever is passed to me as @code{arg} by 50'. - -@need 1200 -Earlier, for example, we had a function @code{multiply-by-seven}; it -multiplied its argument by 7. This function is similar, except it -divides its argument by 50; and, it has no name. The anonymous -equivalent of @code{multiply-by-seven} is: - -@smallexample -(lambda (number) (* 7 number)) -@end smallexample - -@noindent -(@xref{defun, , The @code{defun} Special Form}.) - -@need 1250 -@noindent -If we want to multiply 3 by 7, we can write: - -@c !!! Clear print-postscript-figures if the computer formatting this -@c document is too small and cannot handle all the diagrams and figures. -@c clear print-postscript-figures -@c set print-postscript-figures -@c lambda example diagram #1 -@ifnottex -@smallexample -@group -(multiply-by-seven 3) - \_______________/ ^ - | | - function argument -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{lambda-1} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -(multiply-by-seven 3) - \_______________/ ^ - | | - function argument -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -This expression returns 21. - -@need 1250 -@noindent -Similarly, we can write: - -@c lambda example diagram #2 -@ifnottex -@smallexample -@group -((lambda (number) (* 7 number)) 3) - \____________________________/ ^ - | | - anonymous function argument -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{lambda-2} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -((lambda (number) (* 7 number)) 3) - \____________________________/ ^ - | | - anonymous function argument -@end group -@end smallexample -@end iftex -@end ifclear - -@need 1250 -@noindent -If we want to divide 100 by 50, we can write: - -@c lambda example diagram #3 -@ifnottex -@smallexample -@group -((lambda (arg) (/ arg 50)) 100) - \______________________/ \_/ - | | - anonymous function argument -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{lambda-3} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -((lambda (arg) (/ arg 50)) 100) - \______________________/ \_/ - | | - anonymous function argument -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -This expression returns 2. The 100 is passed to the function, which -divides that number by 50. - -@xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs -Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda -expressions derive from the Lambda Calculus. - -@node mapcar, Another Bug, lambda, Print Whole Graph -@appendixsubsec The @code{mapcar} Function -@findex mapcar - -@code{mapcar} is a function that calls its first argument with each -element of its second argument, in turn. The second argument must be -a sequence. - -The @samp{map} part of the name comes from the mathematical phrase, -`mapping over a domain', meaning to apply a function to each of the -elements in a domain. The mathematical phrase is based on the -metaphor of a surveyor walking, one step at a time, over an area he is -mapping. And @samp{car}, of course, comes from the Lisp notion of the -first of a list. - -@need 1250 -@noindent -For example, - -@smallexample -@group -(mapcar '1+ '(2 4 6)) - @result{} (3 5 7) -@end group -@end smallexample - -@noindent -The function @code{1+} which adds one to its argument, is executed on -@emph{each} element of the list, and a new list is returned. - -Contrast this with @code{apply}, which applies its first argument to -all the remaining. -(@xref{Readying a Graph, , Readying a Graph}, for a explanation of -@code{apply}.) - -@need 1250 -In the definition of @code{one-fiftieth}, the first argument is the -anonymous function: - -@smallexample -(lambda (arg) (/ arg 50)) -@end smallexample - -@noindent -and the second argument is @code{full-range}, which will be bound to -@code{list-for-graph}. - -@need 1250 -The whole expression looks like this: - -@smallexample -(mapcar '(lambda (arg) (/ arg 50)) full-range)) -@end smallexample - -@xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs -Lisp Reference Manual}, for more about @code{mapcar}. - -Using the @code{one-fiftieth} function, we can generate a list in -which each element is one-fiftieth the size of the corresponding -element in @code{list-for-graph}. - -@smallexample -@group -(setq fiftieth-list-for-graph - (one-fiftieth list-for-graph)) -@end group -@end smallexample - -@need 1250 -The resulting list looks like this: - -@smallexample -@group -(10 20 19 15 11 9 6 5 4 3 3 2 2 -1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4) -@end group -@end smallexample - -@noindent -This, we are almost ready to print! (We also notice the loss of -information: many of the higher ranges are 0, meaning that fewer than -50 defuns had that many words or symbols---but not necessarily meaning -that none had that many words or symbols.) - -@node Another Bug, Final printed graph, mapcar, Print Whole Graph -@appendixsubsec Another Bug @dots{} Most Insidious -@cindex Bug, most insidious type -@cindex Insidious type of bug - -I said `almost ready to print'! Of course, there is a bug in the -@code{print-graph} function @dots{} It has a @code{vertical-step} -option, but not a @code{horizontal-step} option. The -@code{top-of-range} scale goes from 10 to 300 by tens. But the -@code{print-graph} function will print only by ones. - -This is a classic example of what some consider the most insidious -type of bug, the bug of omission. This is not the kind of bug you can -find by studying the code, for it is not in the code; it is an omitted -feature. Your best actions are to try your program early and often; -and try to arrange, as much as you can, to write code that is easy to -understand and easy to change. Try to be aware, whenever you can, -that whatever you have written, @emph{will} be rewritten, if not soon, -eventually. A hard maxim to follow. - -It is the @code{print-X-axis-numbered-line} function that needs the -work; and then the @code{print-X-axis} and the @code{print-graph} -functions need to be adapted. Not much needs to be done; there is one -nicety: the numbers ought to line up under the tic marks. This takes -a little thought. - -@need 1250 -Here is the corrected @code{print-X-axis-numbered-line}: - -@smallexample -@group -(defun print-X-axis-numbered-line - (number-of-X-tics X-axis-leading-spaces - &optional horizontal-step) - "Print line of X-axis numbers" - (let ((number X-axis-label-spacing) - (horizontal-step (or horizontal-step 1))) -@end group -@group - (insert X-axis-leading-spaces) - ;; @r{Delete extra leading spaces.} - (delete-char - (- (1- - (length (number-to-string horizontal-step))))) - (insert (concat - (make-string -@end group -@group - ;; @r{Insert white space.} - (- (* symbol-width - X-axis-label-spacing) - (1- - (length - (number-to-string horizontal-step))) - 2) - ? ) - (number-to-string - (* number horizontal-step)))) -@end group -@group - ;; @r{Insert remaining numbers.} - (setq number (+ number X-axis-label-spacing)) - (while (> number-of-X-tics 1) - (insert (X-axis-element - (* number horizontal-step))) - (setq number (+ number X-axis-label-spacing)) - (setq number-of-X-tics (1- number-of-X-tics))))) -@end group -@end smallexample - -@need 1500 -If you are reading this in Info, you can see the new versions of -@code{print-X-axis} @code{print-graph} and evaluate them. If you are -reading this in a printed book, you can see the changed lines here -(the full text is too much to print). - -@iftex -@smallexample -@group -(defun print-X-axis (numbers-list horizontal-step) - @dots{} - (print-X-axis-numbered-line - tic-number leading-spaces horizontal-step)) -@end group -@end smallexample - -@smallexample -@group -(defun print-graph - (numbers-list - &optional vertical-step horizontal-step) - @dots{} - (print-X-axis numbers-list horizontal-step)) -@end group -@end smallexample -@end iftex - -@ifnottex -@smallexample -@group -(defun print-X-axis (numbers-list horizontal-step) - "Print X axis labels to length of NUMBERS-LIST. -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." -@end group -@group -;; Value of symbol-width and full-Y-label-width -;; are passed by `print-graph'. - (let* ((leading-spaces - (make-string full-Y-label-width ? )) - ;; symbol-width @r{is provided by} graph-body-print - (tic-width (* symbol-width X-axis-label-spacing)) - (X-length (length numbers-list)) -@end group -@group - (X-tic - (concat - (make-string - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) -@end group -@group - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol)) - (tic-number - (if (zerop (% X-length tic-width)) - (/ X-length tic-width) - (1+ (/ X-length tic-width))))) -@end group - -@group - (print-X-axis-tic-line - tic-number leading-spaces X-tic) - (insert "\n") - (print-X-axis-numbered-line - tic-number leading-spaces horizontal-step))) -@end group -@end smallexample - -@smallexample -@group -(defun print-graph - (numbers-list &optional vertical-step horizontal-step) - "Print labelled bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -@end group - -@group -Optionally, VERTICAL-STEP, a positive integer, -specifies how much a Y axis label increments for -each line. For example, a step of 5 means that -each row is five units. -@end group - -@group -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." - (let* ((symbol-width (length graph-blank)) - ;; @code{height} @r{is both the largest number} - ;; @r{and the number with the most digits.} - (height (apply 'max numbers-list)) -@end group -@group - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) -@end group -@group - (vertical-step (or vertical-step 1)) - (full-Y-label-width - (length - (concat - (number-to-string - (* height-of-top-line vertical-step)) - Y-axis-tic)))) -@end group -@group - (print-Y-axis - height-of-top-line full-Y-label-width vertical-step) - (graph-body-print - numbers-list height-of-top-line symbol-width) - (print-X-axis numbers-list horizontal-step))) -@end group -@end smallexample -@end ifnottex - -@c qqq -@ignore -Graphing Definitions Re-listed - -@need 1250 -Here are all the graphing definitions in their final form: - -@smallexample -@group -(defvar top-of-ranges - '(10 20 30 40 50 - 60 70 80 90 100 - 110 120 130 140 150 - 160 170 180 190 200 - 210 220 230 240 250) - "List specifying ranges for `defuns-per-range'.") -@end group - -@group -(defvar graph-symbol "*" - "String used as symbol in graph, usually an asterisk.") -@end group - -@group -(defvar graph-blank " " - "String used as blank in graph, usually a blank space. -graph-blank must be the same number of columns wide -as graph-symbol.") -@end group - -@group -(defvar Y-axis-tic " - " - "String that follows number in a Y axis label.") -@end group - -@group -(defvar Y-axis-label-spacing 5 - "Number of lines from one Y axis label to next.") -@end group - -@group -(defvar X-axis-tic-symbol "|" - "String to insert to point to a column in X axis.") -@end group - -@group -(defvar X-axis-label-spacing - (if (boundp 'graph-blank) - (* 5 (length graph-blank)) 5) - "Number of units from one X axis label to next.") -@end group -@end smallexample - -@smallexample -@group -(defun count-words-in-defun () - "Return the number of words and symbols in a defun." - (beginning-of-defun) - (let ((count 0) - (end (save-excursion (end-of-defun) (point)))) -@end group - -@group - (while - (and (< (point) end) - (re-search-forward - "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" - end t)) - (setq count (1+ count))) - count)) -@end group -@end smallexample - -@smallexample -@group -(defun lengths-list-file (filename) - "Return list of definitions' lengths within FILE. -The returned list is a list of numbers. -Each number is the number of words or -symbols in one function definition." -@end group - -@group - (message "Working on `%s' ... " filename) - (save-excursion - (let ((buffer (find-file-noselect filename)) - (lengths-list)) - (set-buffer buffer) - (setq buffer-read-only t) - (widen) - (goto-char (point-min)) -@end group - -@group - (while (re-search-forward "^(defun" nil t) - (setq lengths-list - (cons (count-words-in-defun) lengths-list))) - (kill-buffer buffer) - lengths-list))) -@end group -@end smallexample - -@smallexample -@group -(defun lengths-list-many-files (list-of-files) - "Return list of lengths of defuns in LIST-OF-FILES." - (let (lengths-list) -;;; @r{true-or-false-test} - (while list-of-files - (setq lengths-list - (append - lengths-list -@end group -@group -;;; @r{Generate a lengths' list.} - (lengths-list-file - (expand-file-name (car list-of-files))))) -;;; @r{Make files' list shorter.} - (setq list-of-files (cdr list-of-files))) -;;; @r{Return final value of lengths' list.} - lengths-list)) -@end group -@end smallexample - -@smallexample -@group -(defun defuns-per-range (sorted-lengths top-of-ranges) - "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." - (let ((top-of-range (car top-of-ranges)) - (number-within-range 0) - defuns-per-range-list) -@end group - -@group - ;; @r{Outer loop.} - (while top-of-ranges - - ;; @r{Inner loop.} - (while (and - ;; @r{Need number for numeric test.} - (car sorted-lengths) - (< (car sorted-lengths) top-of-range)) - - ;; @r{Count number of definitions within current range.} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) -@end group - -@group - ;; @r{Exit inner loop but remain within outer loop.} - - (setq defuns-per-range-list - (cons number-within-range defuns-per-range-list)) - (setq number-within-range 0) ; @r{Reset count to zero.} - - ;; @r{Move to next range.} - (setq top-of-ranges (cdr top-of-ranges)) - ;; @r{Specify next top of range value.} - (setq top-of-range (car top-of-ranges))) -@end group - -@group - ;; @r{Exit outer loop and count the number of defuns larger than} - ;; @r{ the largest top-of-range value.} - (setq defuns-per-range-list - (cons - (length sorted-lengths) - defuns-per-range-list)) - - ;; @r{Return a list of the number of definitions within each range,} - ;; @r{ smallest to largest.} - (nreverse defuns-per-range-list))) -@end group -@end smallexample - -@smallexample -@group -(defun column-of-graph (max-graph-height actual-height) - "Return list of MAX-GRAPH-HEIGHT strings; -ACTUAL-HEIGHT are graph-symbols. -The graph-symbols are contiguous entries at the end -of the list. -The list will be inserted as one column of a graph. -The strings are either graph-blank or graph-symbol." -@end group - -@group - (let ((insert-list nil) - (number-of-top-blanks - (- max-graph-height actual-height))) - - ;; @r{Fill in @code{graph-symbols}.} - (while (> actual-height 0) - (setq insert-list (cons graph-symbol insert-list)) - (setq actual-height (1- actual-height))) -@end group - -@group - ;; @r{Fill in @code{graph-blanks}.} - (while (> number-of-top-blanks 0) - (setq insert-list (cons graph-blank insert-list)) - (setq number-of-top-blanks - (1- number-of-top-blanks))) - - ;; @r{Return whole list.} - insert-list)) -@end group -@end smallexample - -@smallexample -@group -(defun Y-axis-element (number full-Y-label-width) - "Construct a NUMBERed label element. -A numbered element looks like this ` 5 - ', -and is padded as needed so all line up with -the element for the largest number." -@end group -@group - (let* ((leading-spaces - (- full-Y-label-width - (length - (concat (number-to-string number) - Y-axis-tic))))) -@end group -@group - (concat - (make-string leading-spaces ? ) - (number-to-string number) - Y-axis-tic))) -@end group -@end smallexample - -@smallexample -@group -(defun print-Y-axis - (height full-Y-label-width &optional vertical-step) - "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH. -Height must be the maximum height of the graph. -Full width is the width of the highest label element. -Optionally, print according to VERTICAL-STEP." -@end group -@group -;; Value of height and full-Y-label-width -;; are passed by `print-graph'. - (let ((start (point))) - (insert-rectangle - (Y-axis-column height full-Y-label-width vertical-step)) -@end group -@group - ;; @r{Place point ready for inserting graph.} - (goto-char start) - ;; @r{Move point forward by value of} full-Y-label-width - (forward-char full-Y-label-width))) -@end group -@end smallexample - -@smallexample -@group -(defun print-X-axis-tic-line - (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) - "Print ticks for X axis." - (insert X-axis-leading-spaces) - (insert X-axis-tic-symbol) ; @r{Under first column.} -@end group -@group - ;; @r{Insert second tic in the right spot.} - (insert (concat - (make-string - (- (* symbol-width X-axis-label-spacing) - ;; @r{Insert white space up to second tic symbol.} - (* 2 (length X-axis-tic-symbol))) - ? ) - X-axis-tic-symbol)) -@end group -@group - ;; @r{Insert remaining ticks.} - (while (> number-of-X-tics 1) - (insert X-axis-tic-element) - (setq number-of-X-tics (1- number-of-X-tics)))) -@end group -@end smallexample - -@smallexample -@group -(defun X-axis-element (number) - "Construct a numbered X axis element." - (let ((leading-spaces - (- (* symbol-width X-axis-label-spacing) - (length (number-to-string number))))) - (concat (make-string leading-spaces ? ) - (number-to-string number)))) -@end group -@end smallexample - -@smallexample -@group -(defun graph-body-print (numbers-list height symbol-width) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -HEIGHT is maximum height of graph. -SYMBOL-WIDTH is number of each column." -@end group -@group - (let (from-position) - (while numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) - (goto-char from-position) - (forward-char symbol-width) -@end group -@group - ;; @r{Draw graph column by column.} - (sit-for 0) - (setq numbers-list (cdr numbers-list))) - ;; @r{Place point for X axis labels.} - (forward-line height) - (insert "\n"))) -@end group -@end smallexample - -@smallexample -@group -(defun Y-axis-column - (height width-of-label &optional vertical-step) - "Construct list of labels for Y axis. -HEIGHT is maximum height of graph. -WIDTH-OF-LABEL is maximum width of label. -@end group -@group -VERTICAL-STEP, an option, is a positive integer -that specifies how much a Y axis label increments -for each line. For example, a step of 5 means -that each line is five units of the graph." - (let (Y-axis - (number-per-line (or vertical-step 1))) -@end group -@group - (while (> height 1) - (if (zerop (% height Y-axis-label-spacing)) - ;; @r{Insert label.} - (setq Y-axis - (cons - (Y-axis-element - (* height number-per-line) - width-of-label) - Y-axis)) -@end group -@group - ;; @r{Else, insert blanks.} - (setq Y-axis - (cons - (make-string width-of-label ? ) - Y-axis))) - (setq height (1- height))) -@end group -@group - ;; @r{Insert base line.} - (setq Y-axis (cons (Y-axis-element - (or vertical-step 1) - width-of-label) - Y-axis)) - (nreverse Y-axis))) -@end group -@end smallexample - -@smallexample -@group -(defun print-X-axis-numbered-line - (number-of-X-tics X-axis-leading-spaces - &optional horizontal-step) - "Print line of X-axis numbers" - (let ((number X-axis-label-spacing) - (horizontal-step (or horizontal-step 1))) -@end group -@group - (insert X-axis-leading-spaces) - ;; line up number - (delete-char (- (1- (length (number-to-string horizontal-step))))) - (insert (concat - (make-string - ;; @r{Insert white space up to next number.} - (- (* symbol-width X-axis-label-spacing) - (1- (length (number-to-string horizontal-step))) - 2) - ? ) - (number-to-string (* number horizontal-step)))) -@end group -@group - ;; @r{Insert remaining numbers.} - (setq number (+ number X-axis-label-spacing)) - (while (> number-of-X-tics 1) - (insert (X-axis-element (* number horizontal-step))) - (setq number (+ number X-axis-label-spacing)) - (setq number-of-X-tics (1- number-of-X-tics))))) -@end group -@end smallexample - -@smallexample -@group -(defun print-X-axis (numbers-list horizontal-step) - "Print X axis labels to length of NUMBERS-LIST. -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." -@end group -@group -;; Value of symbol-width and full-Y-label-width -;; are passed by `print-graph'. - (let* ((leading-spaces - (make-string full-Y-label-width ? )) - ;; symbol-width @r{is provided by} graph-body-print - (tic-width (* symbol-width X-axis-label-spacing)) - (X-length (length numbers-list)) -@end group -@group - (X-tic - (concat - (make-string - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) -@end group -@group - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol)) - (tic-number - (if (zerop (% X-length tic-width)) - (/ X-length tic-width) - (1+ (/ X-length tic-width))))) -@end group - -@group - (print-X-axis-tic-line - tic-number leading-spaces X-tic) - (insert "\n") - (print-X-axis-numbered-line - tic-number leading-spaces horizontal-step))) -@end group -@end smallexample - -@smallexample -@group -(defun one-fiftieth (full-range) - "Return list, each number of which is 1/50th previous." - (mapcar '(lambda (arg) (/ arg 50)) full-range)) -@end group -@end smallexample - -@smallexample -@group -(defun print-graph - (numbers-list &optional vertical-step horizontal-step) - "Print labelled bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -@end group - -@group -Optionally, VERTICAL-STEP, a positive integer, -specifies how much a Y axis label increments for -each line. For example, a step of 5 means that -each row is five units. -@end group - -@group -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." - (let* ((symbol-width (length graph-blank)) - ;; @code{height} @r{is both the largest number} - ;; @r{and the number with the most digits.} - (height (apply 'max numbers-list)) -@end group -@group - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) -@end group -@group - (vertical-step (or vertical-step 1)) - (full-Y-label-width - (length - (concat - (number-to-string - (* height-of-top-line vertical-step)) - Y-axis-tic)))) -@end group -@group - - (print-Y-axis - height-of-top-line full-Y-label-width vertical-step) - (graph-body-print - numbers-list height-of-top-line symbol-width) - (print-X-axis numbers-list horizontal-step))) -@end group -@end smallexample -@c qqq -@end ignore - -@page -@node Final printed graph, , Another Bug, Print Whole Graph -@appendixsubsec The Printed Graph - -When made and installed, you can call the @code{print-graph} command -like this: -@sp 1 - -@smallexample -@group -(print-graph fiftieth-list-for-graph 50 10) -@end group -@end smallexample -@sp 1 - -@noindent -Here is the graph: -@sp 2 - -@smallexample -@group -1000 - * - ** - ** - ** - ** - 750 - *** - *** - *** - *** - **** - 500 - ***** - ****** - ****** - ****** - ******* - 250 - ******** - ********* * - *********** * - ************* * - 50 - ***************** * * - | | | | | | | | - 10 50 100 150 200 250 300 350 -@end group -@end smallexample - -@sp 2 - -@noindent -The largest group of functions contain 10 -- 19 words and symbols each. - -@node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top -@appendix Free Software and Free Manuals - -@strong{by Richard M. Stallman} -@sp 1 - -The biggest deficiency in free operating systems is not in the -software---it is the lack of good free manuals that we can include in -these systems. Many of our most important programs do not come with -full manuals. Documentation is an essential part of any software -package; when an important free software package does not come with a -free manual, that is a major gap. We have many such gaps today. - -Once upon a time, many years ago, I thought I would learn Perl. I got -a copy of a free manual, but I found it hard to read. When I asked -Perl users about alternatives, they told me that there were better -introductory manuals---but those were not free. - -Why was this? The authors of the good manuals had written them for -O'Reilly Associates, which published them with restrictive terms---no -copying, no modification, source files not available---which exclude -them from the free software community. - -That wasn't the first time this sort of thing has happened, and (to -our community's great loss) it was far from the last. Proprietary -manual publishers have enticed a great many authors to restrict their -manuals since then. Many times I have heard a GNU user eagerly tell me -about a manual that he is writing, with which he expects to help the -GNU project---and then had my hopes dashed, as he proceeded to explain -that he had signed a contract with a publisher that would restrict it -so that we cannot use it. - -Given that writing good English is a rare skill among programmers, we -can ill afford to lose manuals this way. - -@c (texinfo)uref -(The Free Software Foundation -@uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, , -sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html, -GNU manuals}, too.) - -Free documentation, like free software, is a matter of freedom, not -price. The problem with these manuals was not that O'Reilly Associates -charged a price for printed copies---that in itself is fine. (The Free -Software Foundation sells printed copies of free GNU manuals, too.) -But GNU manuals are available in source code form, while these manuals -are available only on paper. GNU manuals come with permission to copy -and modify; the Perl manuals do not. These restrictions are the -problems. - -The criterion for a free manual is pretty much the same as for free -software: it is a matter of giving all users certain -freedoms. Redistribution (including commercial redistribution) must be -permitted, so that the manual can accompany every copy of the program, -on-line or on paper. Permission for modification is crucial too. - -As a general rule, I don't believe that it is essential for people to -have permission to modify all sorts of articles and books. The issues -for writings are not necessarily the same as those for software. For -example, I don't think you or I are obliged to give permission to -modify articles like this one, which describe our actions and our -views. - -But there is a particular reason why the freedom to modify is crucial -for documentation for free software. When people exercise their right -to modify the software, and add or change its features, if they are -conscientious they will change the manual too---so they can provide -accurate and usable documentation with the modified program. A manual -which forbids programmers to be conscientious and finish the job, or -more precisely requires them to write a new manual from scratch if -they change the program, does not fill our community's needs. - -While a blanket prohibition on modification is unacceptable, some -kinds of limits on the method of modification pose no problem. For -example, requirements to preserve the original author's copyright -notice, the distribution terms, or the list of authors, are ok. It is -also no problem to require modified versions to include notice that -they were modified, even to have entire sections that may not be -deleted or changed, as long as these sections deal with nontechnical -topics. (Some GNU manuals have them.) - -These kinds of restrictions are not a problem because, as a practical -matter, they don't stop the conscientious programmer from adapting the -manual to fit the modified program. In other words, they don't block -the free software community from making full use of the manual. - -However, it must be possible to modify all the technical content of -the manual, and then distribute the result in all the usual media, -through all the usual channels; otherwise, the restrictions do block -the community, the manual is not free, and so we need another manual. - -Unfortunately, it is often hard to find someone to write another -manual when a proprietary manual exists. The obstacle is that many -users think that a proprietary manual is good enough---so they don't -see the need to write a free manual. They do not see that the free -operating system has a gap that needs filling. - -Why do users think that proprietary manuals are good enough? Some have -not considered the issue. I hope this article will do something to -change that. - -Other users consider proprietary manuals acceptable for the same -reason so many people consider proprietary software acceptable: they -judge in purely practical terms, not using freedom as a -criterion. These people are entitled to their opinions, but since -those opinions spring from values which do not include freedom, they -are no guide for those of us who do value freedom. - -Please spread the word about this issue. We continue to lose manuals -to proprietary publishing. If we spread the word that proprietary -manuals are not sufficient, perhaps the next person who wants to help -GNU by writing documentation will realize, before it is too late, that -he must above all make it free. - -We can also encourage commercial publishers to sell free, copylefted -manuals instead of proprietary ones. One way you can help this is to -check the distribution terms of a manual before you buy it, and prefer -copylefted manuals to non-copylefted ones. - -@sp 2 -@noindent -Note: The Free Software Foundation maintains a page on its Web site -that lists free books available from other publishers:@* -@uref{http://www.gnu.org/doc/other-free-books.html} - -@node GNU Free Documentation License, Index, Free Software and Free Manuals, Top -@appendix GNU Free Documentation License - -@cindex FDL, GNU Free Documentation License -@center Version 1.2, November 2002 - -@display -Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. -51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input -format, @acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML}, -PostScript or @acronym{PDF} designed for human modification. Examples -of transparent image formats include @acronym{PNG}, @acronym{XCF} and -@acronym{JPG}. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, @acronym{SGML} or -@acronym{XML} for which the @acronym{DTD} and/or processing tools are -not generally available, and the machine-generated @acronym{HTML}, -PostScript or @acronym{PDF} produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to -copy, modify, sublicense or distribute the Document is void, and will -automatically terminate your rights under this License. However, -parties who have received copies, or rights, from you under this -License will not have their licenses terminated so long as such -parties remain in full compliance. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. -@end enumerate - -@page -@appendixsubsec ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group -Copyright (C) @var{year} @var{your name}. -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 -or any later version published by the Free Software Foundation; -with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -A copy of the license is included in the section entitled ``GNU -Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with...Texts.'' line with this: - -@smallexample -@group -with the Invariant Sections being @var{list their titles}, with -the Front-Cover Texts being @var{list}, and with the Back-Cover Texts -being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@node Index, About the Author, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Index - -@ignore -MENU ENTRY: NODE NAME. -@end ignore - -@printindex cp - -@iftex -@c Place biographical information on right-hand (verso) page - -@tex -\ifodd\pageno - \par\vfill\supereject - \global\evenheadline={\hfil} \global\evenfootline={\hfil} - \global\oddheadline={\hfil} \global\oddfootline={\hfil} - \page\hbox{}\page -\else - \par\vfill\supereject - \par\vfill\supereject - \global\evenheadline={\hfil} \global\evenfootline={\hfil} - \global\oddheadline={\hfil} \global\oddfootline={\hfil} - \page\hbox{}\page - \page\hbox{}\page -\fi -@end tex - -@page -@w{ } - -@c ================ Biographical information ================ - -@w{ } -@sp 8 -@center About the Author -@sp 1 -@end iftex - -@ifnottex -@node About the Author, , Index, Top -@unnumbered About the Author -@end ifnottex - -@quotation -Robert J. Chassell has worked with GNU Emacs since 1985. He writes -and edits, teaches Emacs and Emacs Lisp, and speaks throughout the -world on software freedom. Chassell was a founding Director and -Treasurer of the Free Software Foundation, Inc. He is co-author of -the @cite{Texinfo} manual, and has edited more than a dozen other -books. He graduated from Cambridge University, in England. He has an -abiding interest in social and economic history and flies his own -airplane. -@end quotation - -@page -@w{ } - -@c Prevent page number on blank verso, so eject it first. -@tex -\par\vfill\supereject -@end tex - -@iftex -@headings off -@evenheading @thispage @| @| @thistitle -@oddheading @| @| @thispage -@end iftex - -@bye - -@ignore - arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf -@end ignore