mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-04 08:47:11 +00:00
22297 lines
779 KiB
Plaintext
22297 lines
779 KiB
Plaintext
\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
|
|
@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 >>>>
|
|
@set smallbook
|
|
@ifset smallbook
|
|
@smallbook
|
|
@clear largebook
|
|
@end ifset
|
|
@set print-postscript-figures
|
|
@c set largebook
|
|
@c clear print-postscript-figures
|
|
@c ---------
|
|
|
|
@comment %**end of header
|
|
|
|
@c per rms and peterb, use 10pt fonts for the main text, mostly to
|
|
@c save on paper cost.
|
|
@c Do this inside @tex for now, so current makeinfo does not complain.
|
|
@tex
|
|
@ifset smallbook
|
|
@fonttextsize 10
|
|
\global\let\urlcolor=\Black % don't print links in grayscale
|
|
\global\let\linkcolor=\Black
|
|
@end ifset
|
|
\global\hbadness=6666 % don't worry about not-too-underfull boxes
|
|
@end tex
|
|
|
|
@set edition-number 3.08
|
|
@set update-date 4 October 2008
|
|
@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, 2008, 2009 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.3 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 the freedom to
|
|
copy and modify this GNU manual. Buying copies from the FSF
|
|
supports it in developing GNU and promoting software freedom.''
|
|
@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.
|
|
|
|
@c iftex
|
|
@c global@pageno = -11
|
|
@c 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
|
|
@email{bob@@gnu.org}
|
|
@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
|
|
Text between double quotation marks---even sentences or
|
|
paragraphs---is also 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 document, 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
|
|
assembles 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 the expression @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 already 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 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: "
|
|
(apply-partially 'locate-file-completion-table
|
|
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 version @file{html-helper-mode.elc}, if that 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
|
|
Interaction 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 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 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 @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
|
|
@include doclicense.texi
|
|
|
|
@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
|
|
\par\vfill\supereject
|
|
\ifodd\pageno
|
|
\global\evenheadline={\hfil} \global\evenfootline={\hfil}
|
|
\global\oddheadline={\hfil} \global\oddfootline={\hfil}
|
|
%\page\hbox{}\page
|
|
\else
|
|
% \par\vfill\supereject
|
|
\global\evenheadline={\hfil} \global\evenfootline={\hfil}
|
|
\global\oddheadline={\hfil} \global\oddfootline={\hfil}
|
|
%\page\hbox{}%\page
|
|
%\page\hbox{}%\page
|
|
\fi
|
|
@end tex
|
|
|
|
@c 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
|
|
|
|
@c @page
|
|
@c @w{ }
|
|
@c
|
|
@c @c Prevent page number on blank verso, so eject it first.
|
|
@c @tex
|
|
@c \par\vfill\supereject
|
|
@c @end tex
|
|
|
|
@c @iftex
|
|
@c @headings off
|
|
@c @evenheading @thispage @| @| @thistitle
|
|
@c @oddheading @| @| @thispage
|
|
@c @end iftex
|
|
|
|
@bye
|
|
|
|
@ignore
|
|
arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf
|
|
@end ignore
|