Commit | Line | Data |
---|---|---|
8cda6f8f GM |
1 | \input texinfo @c -*-texinfo-*- |
2 | @comment %**start of header | |
fb3dc846 | 3 | @setfilename ../../info/eintr |
8cda6f8f GM |
4 | @c setfilename emacs-lisp-intro.info |
5 | @c sethtmlfilename emacs-lisp-intro.html | |
6 | @settitle Programming in Emacs Lisp | |
7 | @syncodeindex vr cp | |
8 | @syncodeindex fn cp | |
8cda6f8f GM |
9 | @finalout |
10 | ||
11 | @c --------- | |
12 | @c <<<< For hard copy printing, this file is now | |
13 | @c set for smallbook, which works for all sizes | |
7877f373 | 14 | @c of paper, and with PostScript figures >>>> |
a9097c6d KB |
15 | @set smallbook |
16 | @ifset smallbook | |
8cda6f8f GM |
17 | @smallbook |
18 | @clear largebook | |
a9097c6d | 19 | @end ifset |
8cda6f8f GM |
20 | @set print-postscript-figures |
21 | @c set largebook | |
22 | @c clear print-postscript-figures | |
23 | @c --------- | |
24 | ||
25 | @comment %**end of header | |
26 | ||
a9097c6d | 27 | @c per rms and peterb, use 10pt fonts for the main text, mostly to |
867d4bb3 | 28 | @c save on paper cost. |
a9097c6d KB |
29 | @c Do this inside @tex for now, so current makeinfo does not complain. |
30 | @tex | |
31 | @ifset smallbook | |
32 | @fonttextsize 10 | |
6e3da0ae | 33 | |
a9097c6d KB |
34 | @end ifset |
35 | \global\hbadness=6666 % don't worry about not-too-underfull boxes | |
36 | @end tex | |
37 | ||
6e3da0ae RC |
38 | @set edition-number 3.10 |
39 | @set update-date 28 October 2009 | |
767b8eae | 40 | @c FIXME can this be updated? -- xfq |
45cf6cbd | 41 | |
8cda6f8f GM |
42 | @ignore |
43 | ## Summary of shell commands to create various output formats: | |
44 | ||
45 | pushd /usr/local/src/emacs/lispintro/ | |
46 | ## pushd /u/intro/ | |
47 | ||
48 | ## Info output | |
49 | makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi | |
50 | ||
51 | ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/usr/local/src/emacs/info/eintr")) | |
52 | ||
53 | ## DVI output | |
54 | texi2dvi emacs-lisp-intro.texi | |
55 | ||
56 | ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi & | |
57 | ||
58 | ## HTML output | |
59 | makeinfo --html --no-split --verbose emacs-lisp-intro.texi | |
60 | ||
61 | ## galeon emacs-lisp-intro.html | |
62 | ||
63 | ## Plain text output | |
64 | makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ | |
65 | --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi | |
66 | ||
67 | popd | |
68 | ||
69 | # as user `root' | |
70 | # insert thumbdrive | |
71 | mtusb # mount -v -t ext3 /dev/sda /mnt | |
72 | cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi | |
73 | umtusb # umount -v /mnt | |
74 | # remove thumbdrive | |
75 | ||
76 | ## Other shell commands | |
77 | ||
78 | pushd /usr/local/src/emacs/lispintro/ | |
79 | ## pushd /u/intro/ | |
80 | ||
81 | ||
82 | texi2dvi --pdf emacs-lisp-intro.texi | |
83 | # xpdf emacs-lisp-intro.pdf & | |
84 | ||
85 | ## DocBook -- note file extension | |
86 | makeinfo --docbook --no-split --paragraph-indent=0 \ | |
87 | --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi | |
88 | ||
89 | ## XML with a Texinfo DTD -- note file extension | |
90 | makeinfo --xml --no-split --paragraph-indent=0 \ | |
91 | --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi | |
92 | ||
93 | ## PostScript (needs DVI) | |
94 | # gv emacs-lisp-intro.ps & | |
95 | # Create DVI if we lack it | |
96 | # texi2dvi emacs-lisp-intro.texi | |
97 | dvips emacs-lisp-intro.dvi -o emacs-lisp-intro.ps | |
98 | ||
99 | ## RTF (needs HTML) | |
100 | # Use OpenOffice to view RTF | |
101 | # Create HTML if we lack it | |
102 | # makeinfo --no-split --html emacs-lisp-intro.texi | |
103 | /usr/local/src/html2rtf.pl emacs-lisp-intro.html | |
104 | ||
105 | ## LaTeX (needs RTF) | |
106 | /usr/bin/rtf2latex emacs-lisp-intro.rtf | |
107 | ||
108 | popd | |
109 | ||
110 | @end ignore | |
111 | ||
112 | @c ================ Included Figures ================ | |
113 | ||
114 | @c Set print-postscript-figures if you print PostScript figures. | |
115 | @c If you clear this, the ten figures will be printed as ASCII diagrams. | |
116 | @c (This is not relevant to Info, since Info only handles ASCII.) | |
117 | @c Your site may require editing changes to print PostScript; in this | |
118 | @c case, search for `print-postscript-figures' and make appropriate changes. | |
119 | ||
120 | @c ================ How to Create an Info file ================ | |
121 | ||
122 | @c If you have `makeinfo' installed, run the following command | |
123 | ||
124 | @c makeinfo emacs-lisp-intro.texi | |
125 | ||
126 | @c or, if you want a single, large Info file, and no paragraph indents: | |
127 | @c makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi | |
128 | ||
129 | @c After creating the Info file, edit your Info `dir' file, if the | |
130 | @c `dircategory' section below does not enable your system to | |
131 | @c install the manual automatically. | |
132 | @c (The `dir' file is often in the `/usr/local/share/info/' directory.) | |
133 | ||
134 | @c ================ How to Create an HTML file ================ | |
135 | ||
136 | @c To convert to HTML format | |
137 | @c makeinfo --html --no-split --verbose emacs-lisp-intro.texi | |
138 | ||
139 | @c ================ How to Print a Book in Various Sizes ================ | |
140 | ||
141 | @c This book can be printed in any of three different sizes. | |
142 | @c In the above header, set @-commands appropriately. | |
143 | ||
144 | @c 7 by 9.25 inches: | |
145 | @c @smallbook | |
146 | @c @clear largebook | |
147 | ||
148 | @c 8.5 by 11 inches: | |
149 | @c @c smallbook | |
150 | @c @set largebook | |
151 | ||
152 | @c European A4 size paper: | |
153 | @c @c smallbook | |
154 | @c @afourpaper | |
155 | @c @set largebook | |
156 | ||
157 | @c ================ How to Typeset and Print ================ | |
158 | ||
159 | @c If you do not include PostScript figures, run either of the | |
160 | @c following command sequences, or similar commands suited to your | |
161 | @c system: | |
162 | ||
163 | @c texi2dvi emacs-lisp-intro.texi | |
164 | @c lpr -d emacs-lisp-intro.dvi | |
165 | ||
166 | @c or else: | |
167 | ||
168 | @c tex emacs-lisp-intro.texi | |
169 | @c texindex emacs-lisp-intro.?? | |
170 | @c tex emacs-lisp-intro.texi | |
171 | @c lpr -d emacs-lisp-intro.dvi | |
172 | ||
173 | @c If you include the PostScript figures, and you have old software, | |
174 | @c you may need to convert the .dvi file to a .ps file before | |
175 | @c printing. Run either of the following command sequences, or one | |
176 | @c similar: | |
177 | @c | |
178 | @c dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps | |
179 | @c | |
180 | @c or else: | |
181 | @c | |
182 | @c postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps | |
183 | @c | |
184 | ||
185 | @c (Note: if you edit the book so as to change the length of the | |
186 | @c table of contents, you may have to change the value of `pageno' below.) | |
187 | ||
188 | @c ================ End of Formatting Sections ================ | |
189 | ||
190 | @c For next or subsequent edition: | |
191 | @c create function using with-output-to-temp-buffer | |
192 | @c create a major mode, with keymaps | |
193 | @c run an asynchronous process, like grep or diff | |
194 | ||
195 | @c For 8.5 by 11 inch format: do not use such a small amount of | |
196 | @c whitespace between paragraphs as smallbook format | |
197 | @ifset largebook | |
198 | @tex | |
199 | \global\parskip 6pt plus 1pt | |
200 | @end tex | |
201 | @end ifset | |
202 | ||
203 | @c For all sized formats: print within-book cross | |
204 | @c reference with ``...'' rather than [...] | |
205 | ||
206 | @c This works with the texinfo.tex file, version 2003-05-04.08, | |
207 | @c in the Texinfo version 4.6 of the 2003 Jun 13 distribution. | |
208 | ||
209 | @tex | |
210 | \if \xrefprintnodename | |
211 | \global\def\xrefprintnodename#1{\unskip, ``#1''} | |
212 | \else | |
213 | \global\def\xrefprintnodename#1{ ``#1''} | |
214 | \fi | |
215 | % \global\def\xrefprintnodename#1{, ``#1''} | |
216 | @end tex | |
217 | ||
218 | @c ---------------------------------------------------- | |
219 | ||
e979a521 | 220 | @dircategory GNU Emacs Lisp |
8cda6f8f GM |
221 | @direntry |
222 | * Emacs Lisp Intro: (eintr). | |
223 | A simple introduction to Emacs Lisp programming. | |
224 | @end direntry | |
225 | ||
226 | @copying | |
227 | This is an @cite{Introduction to Programming in Emacs Lisp}, for | |
228 | people who are not programmers. | |
229 | @sp 1 | |
230 | Edition @value{edition-number}, @value{update-date} | |
c0765905 GM |
231 | @ifset WWW_GNU_ORG |
232 | @html | |
233 | <p>The homepage for GNU Emacs is at | |
234 | <a href="http://www.gnu.org/software/emacs/">http://www.gnu.org/software/emacs/</a>. | |
235 | <br>To view this manual in other formats, click | |
236 | <a href="/software/emacs/emacs-lisp-intro/emacs-lisp-intro.html">here</a>. | |
237 | @end html | |
238 | @end ifset | |
8cda6f8f | 239 | @sp 1 |
ab422c4d | 240 | Copyright @copyright{} 1990--1995, 1997, 2001--2013 Free Software |
f99f1641 | 241 | Foundation, Inc. |
8cda6f8f GM |
242 | @sp 1 |
243 | ||
244 | @iftex | |
245 | Published by the:@* | |
246 | ||
aa89a0ef GM |
247 | GNU Press, @hfill @uref{http://www.fsf.org/campaigns/gnu-press/}@* |
248 | a division of the @hfill email: @email{sales@@fsf.org}@* | |
249 | Free Software Foundation, Inc. @hfill Tel: +1 (617) 542-5942@* | |
250 | 51 Franklin Street, Fifth Floor @hfill Fax: +1 (617) 542-2652@* | |
72ec96fb | 251 | Boston, MA 02110-1301 USA |
8cda6f8f GM |
252 | @end iftex |
253 | ||
254 | @ifnottex | |
255 | Published by the: | |
256 | ||
257 | @example | |
aa89a0ef GM |
258 | GNU Press, http://www.fsf.org/campaigns/gnu-press/ |
259 | a division of the email: sales@@fsf.org | |
260 | Free Software Foundation, Inc. Tel: +1 (617) 542-5942 | |
261 | 51 Franklin Street, Fifth Floor Fax: +1 (617) 542-2652 | |
72ec96fb | 262 | Boston, MA 02110-1301 USA |
8cda6f8f GM |
263 | @end example |
264 | @end ifnottex | |
265 | ||
266 | @sp 1 | |
aa89a0ef | 267 | @c Printed copies are available from @uref{http://shop.fsf.org/} for $35 each.@* |
8cda6f8f GM |
268 | ISBN 1-882114-43-4 |
269 | ||
270 | Permission is granted to copy, distribute and/or modify this document | |
e41dfb1e | 271 | under the terms of the GNU Free Documentation License, Version 1.3 or |
8cda6f8f GM |
272 | any later version published by the Free Software Foundation; there |
273 | being no Invariant Section, with the Front-Cover Texts being ``A GNU | |
274 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of | |
275 | the license is included in the section entitled ``GNU Free | |
276 | Documentation License''. | |
277 | ||
868a6b71 RC |
278 | (a) The FSF's Back-Cover Text is: ``You have the freedom to |
279 | copy and modify this GNU manual. Buying copies from the FSF | |
280 | supports it in developing GNU and promoting software freedom.'' | |
8cda6f8f GM |
281 | @end copying |
282 | ||
283 | @c half title; two lines here, so do not use `shorttitlepage' | |
284 | @tex | |
285 | {\begingroup% | |
286 | \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}% | |
287 | \endgroup}% | |
288 | {\begingroup\hbox{}\vskip 0.25in \chaprm% | |
289 | \centerline{Programming in Emacs Lisp}% | |
290 | \endgroup\page\hbox{}\page} | |
291 | @end tex | |
292 | ||
293 | @titlepage | |
294 | @sp 6 | |
295 | @center @titlefont{An Introduction to} | |
296 | @sp 2 | |
297 | @center @titlefont{Programming in Emacs Lisp} | |
298 | @sp 2 | |
299 | @center Revised Third Edition | |
300 | @sp 4 | |
301 | @center by Robert J. Chassell | |
302 | ||
303 | @page | |
304 | @vskip 0pt plus 1filll | |
305 | @insertcopying | |
306 | @end titlepage | |
307 | ||
308 | @iftex | |
309 | @headings off | |
310 | @evenheading @thispage @| @| @thischapter | |
311 | @oddheading @thissection @| @| @thispage | |
312 | @end iftex | |
313 | ||
314 | @ifnothtml | |
315 | @c Keep T.O.C. short by tightening up for largebook | |
316 | @ifset largebook | |
317 | @tex | |
318 | \global\parskip 2pt plus 1pt | |
319 | \global\advance\baselineskip by -1pt | |
320 | @end tex | |
321 | @end ifset | |
322 | @end ifnothtml | |
323 | ||
324 | @shortcontents | |
325 | @contents | |
326 | ||
327 | @ifnottex | |
d6adf7e7 | 328 | @node Top |
8cda6f8f GM |
329 | @top An Introduction to Programming in Emacs Lisp |
330 | ||
331 | @insertcopying | |
332 | ||
333 | This master menu first lists each chapter and index; then it lists | |
334 | every node in every chapter. | |
335 | @end ifnottex | |
336 | ||
337 | @c >>>> Set pageno appropriately <<<< | |
338 | ||
339 | @c The first page of the Preface is a roman numeral; it is the first | |
340 | @c right handed page after the Table of Contents; hence the following | |
341 | @c setting must be for an odd negative number. | |
342 | ||
a9097c6d KB |
343 | @c iftex |
344 | @c global@pageno = -11 | |
345 | @c end iftex | |
8cda6f8f | 346 | |
cb97cd2a AS |
347 | @set COUNT-WORDS count-words-example |
348 | @c Length of variable name chosen so that things still line up when expanded. | |
349 | ||
8cda6f8f GM |
350 | @menu |
351 | * Preface:: What to look for. | |
352 | * List Processing:: What is Lisp? | |
353 | * Practicing Evaluation:: Running several programs. | |
354 | * Writing Defuns:: How to write function definitions. | |
355 | * Buffer Walk Through:: Exploring a few buffer-related functions. | |
356 | * More Complex:: A few, even more complex functions. | |
357 | * Narrowing & Widening:: Restricting your and Emacs attention to | |
358 | a region. | |
359 | * car cdr & cons:: Fundamental functions in Lisp. | |
360 | * Cutting & Storing Text:: Removing text and saving it. | |
361 | * List Implementation:: How lists are implemented in the computer. | |
362 | * Yanking:: Pasting stored text. | |
363 | * Loops & Recursion:: How to repeat a process. | |
364 | * Regexp Search:: Regular expression searches. | |
365 | * Counting Words:: A review of repetition and regexps. | |
366 | * Words in a defun:: Counting words in a @code{defun}. | |
367 | * Readying a Graph:: A prototype graph printing function. | |
368 | * Emacs Initialization:: How to write a @file{.emacs} file. | |
369 | * Debugging:: How to run the Emacs Lisp debuggers. | |
370 | * Conclusion:: Now you have the basics. | |
371 | * the-the:: An appendix: how to find reduplicated words. | |
372 | * Kill Ring:: An appendix: how the kill ring works. | |
09e80d9f | 373 | * Full Graph:: How to create a graph with labeled axes. |
8cda6f8f GM |
374 | * Free Software and Free Manuals:: |
375 | * GNU Free Documentation License:: | |
376 | * Index:: | |
377 | * About the Author:: | |
378 | ||
379 | @detailmenu | |
380 | --- The Detailed Node Listing --- | |
381 | ||
382 | Preface | |
383 | ||
384 | * Why:: Why learn Emacs Lisp? | |
385 | * On Reading this Text:: Read, gain familiarity, pick up habits.... | |
386 | * Who You Are:: For whom this is written. | |
387 | * Lisp History:: | |
388 | * Note for Novices:: You can read this as a novice. | |
389 | * Thank You:: | |
390 | ||
391 | List Processing | |
392 | ||
393 | * Lisp Lists:: What are lists? | |
394 | * Run a Program:: Any list in Lisp is a program ready to run. | |
395 | * Making Errors:: Generating an error message. | |
396 | * Names & Definitions:: Names of symbols and function definitions. | |
397 | * Lisp Interpreter:: What the Lisp interpreter does. | |
398 | * Evaluation:: Running a program. | |
399 | * Variables:: Returning a value from a variable. | |
400 | * Arguments:: Passing information to a function. | |
401 | * set & setq:: Setting the value of a variable. | |
402 | * Summary:: The major points. | |
403 | * Error Message Exercises:: | |
404 | ||
405 | Lisp Lists | |
406 | ||
407 | * Numbers Lists:: List have numbers, other lists, in them. | |
408 | * Lisp Atoms:: Elemental entities. | |
409 | * Whitespace in Lists:: Formatting lists to be readable. | |
410 | * Typing Lists:: How GNU Emacs helps you type lists. | |
411 | ||
412 | The Lisp Interpreter | |
413 | ||
414 | * Complications:: Variables, Special forms, Lists within. | |
415 | * Byte Compiling:: Specially processing code for speed. | |
416 | ||
417 | Evaluation | |
418 | ||
419 | * How the Interpreter Acts:: Returns and Side Effects... | |
420 | * Evaluating Inner Lists:: Lists within lists... | |
421 | ||
422 | Variables | |
423 | ||
424 | * fill-column Example:: | |
425 | * Void Function:: The error message for a symbol | |
426 | without a function. | |
427 | * Void Variable:: The error message for a symbol without a value. | |
428 | ||
429 | Arguments | |
430 | ||
431 | * Data types:: Types of data passed to a function. | |
432 | * Args as Variable or List:: An argument can be the value | |
433 | of a variable or list. | |
434 | * Variable Number of Arguments:: Some functions may take a | |
435 | variable number of arguments. | |
436 | * Wrong Type of Argument:: Passing an argument of the wrong type | |
437 | to a function. | |
438 | * message:: A useful function for sending messages. | |
439 | ||
440 | Setting the Value of a Variable | |
441 | ||
442 | * Using set:: Setting values. | |
443 | * Using setq:: Setting a quoted value. | |
444 | * Counting:: Using @code{setq} to count. | |
445 | ||
446 | Practicing Evaluation | |
447 | ||
448 | * How to Evaluate:: Typing editing commands or @kbd{C-x C-e} | |
449 | causes evaluation. | |
450 | * Buffer Names:: Buffers and files are different. | |
451 | * Getting Buffers:: Getting a buffer itself, not merely its name. | |
452 | * Switching Buffers:: How to change to another buffer. | |
453 | * Buffer Size & Locations:: Where point is located and the size of | |
454 | the buffer. | |
455 | * Evaluation Exercise:: | |
456 | ||
457 | How To Write Function Definitions | |
458 | ||
459 | * Primitive Functions:: | |
2325c82f | 460 | * defun:: The @code{defun} macro. |
8cda6f8f GM |
461 | * Install:: Install a function definition. |
462 | * Interactive:: Making a function interactive. | |
463 | * Interactive Options:: Different options for @code{interactive}. | |
464 | * Permanent Installation:: Installing code permanently. | |
465 | * let:: Creating and initializing local variables. | |
466 | * if:: What if? | |
467 | * else:: If--then--else expressions. | |
468 | * Truth & Falsehood:: What Lisp considers false and true. | |
469 | * save-excursion:: Keeping track of point, mark, and buffer. | |
470 | * Review:: | |
471 | * defun Exercises:: | |
472 | ||
473 | Install a Function Definition | |
474 | ||
475 | * Effect of installation:: | |
476 | * Change a defun:: How to change a function definition. | |
477 | ||
478 | Make a Function Interactive | |
479 | ||
480 | * Interactive multiply-by-seven:: An overview. | |
481 | * multiply-by-seven in detail:: The interactive version. | |
482 | ||
483 | @code{let} | |
484 | ||
485 | * Prevent confusion:: | |
486 | * Parts of let Expression:: | |
487 | * Sample let Expression:: | |
488 | * Uninitialized let Variables:: | |
489 | ||
490 | The @code{if} Special Form | |
491 | ||
492 | * if in more detail:: | |
493 | * type-of-animal in detail:: An example of an @code{if} expression. | |
494 | ||
495 | Truth and Falsehood in Emacs Lisp | |
496 | ||
497 | * nil explained:: @code{nil} has two meanings. | |
498 | ||
499 | @code{save-excursion} | |
500 | ||
501 | * Point and mark:: A review of various locations. | |
502 | * Template for save-excursion:: | |
503 | ||
504 | A Few Buffer--Related Functions | |
505 | ||
506 | * Finding More:: How to find more information. | |
507 | * simplified-beginning-of-buffer:: Shows @code{goto-char}, | |
508 | @code{point-min}, and @code{push-mark}. | |
509 | * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. | |
510 | * append-to-buffer:: Uses @code{save-excursion} and | |
511 | @code{insert-buffer-substring}. | |
512 | * Buffer Related Review:: Review. | |
513 | * Buffer Exercises:: | |
514 | ||
515 | The Definition of @code{mark-whole-buffer} | |
516 | ||
517 | * mark-whole-buffer overview:: | |
518 | * Body of mark-whole-buffer:: Only three lines of code. | |
519 | ||
520 | The Definition of @code{append-to-buffer} | |
521 | ||
522 | * append-to-buffer overview:: | |
523 | * append interactive:: A two part interactive expression. | |
524 | * append-to-buffer body:: Incorporates a @code{let} expression. | |
525 | * append save-excursion:: How the @code{save-excursion} works. | |
526 | ||
527 | A Few More Complex Functions | |
528 | ||
529 | * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. | |
530 | * insert-buffer:: Read-only, and with @code{or}. | |
531 | * beginning-of-buffer:: Shows @code{goto-char}, | |
532 | @code{point-min}, and @code{push-mark}. | |
533 | * Second Buffer Related Review:: | |
534 | * optional Exercise:: | |
535 | ||
536 | The Definition of @code{insert-buffer} | |
537 | ||
538 | * insert-buffer code:: | |
539 | * insert-buffer interactive:: When you can read, but not write. | |
540 | * insert-buffer body:: The body has an @code{or} and a @code{let}. | |
541 | * if & or:: Using an @code{if} instead of an @code{or}. | |
542 | * Insert or:: How the @code{or} expression works. | |
543 | * Insert let:: Two @code{save-excursion} expressions. | |
544 | * New insert-buffer:: | |
545 | ||
546 | The Interactive Expression in @code{insert-buffer} | |
547 | ||
548 | * Read-only buffer:: When a buffer cannot be modified. | |
549 | * b for interactive:: An existing buffer or else its name. | |
550 | ||
551 | Complete Definition of @code{beginning-of-buffer} | |
552 | ||
553 | * Optional Arguments:: | |
554 | * beginning-of-buffer opt arg:: Example with optional argument. | |
555 | * beginning-of-buffer complete:: | |
556 | ||
557 | @code{beginning-of-buffer} with an Argument | |
558 | ||
559 | * Disentangle beginning-of-buffer:: | |
560 | * Large buffer case:: | |
561 | * Small buffer case:: | |
562 | ||
563 | Narrowing and Widening | |
564 | ||
565 | * Narrowing advantages:: The advantages of narrowing | |
566 | * save-restriction:: The @code{save-restriction} special form. | |
567 | * what-line:: The number of the line that point is on. | |
568 | * narrow Exercise:: | |
569 | ||
570 | @code{car}, @code{cdr}, @code{cons}: Fundamental Functions | |
571 | ||
572 | * Strange Names:: An historical aside: why the strange names? | |
573 | * car & cdr:: Functions for extracting part of a list. | |
574 | * cons:: Constructing a list. | |
575 | * nthcdr:: Calling @code{cdr} repeatedly. | |
576 | * nth:: | |
577 | * setcar:: Changing the first element of a list. | |
578 | * setcdr:: Changing the rest of a list. | |
579 | * cons Exercise:: | |
580 | ||
581 | @code{cons} | |
582 | ||
583 | * Build a list:: | |
584 | * length:: How to find the length of a list. | |
585 | ||
586 | Cutting and Storing Text | |
587 | ||
588 | * Storing Text:: Text is stored in a list. | |
589 | * zap-to-char:: Cutting out text up to a character. | |
590 | * kill-region:: Cutting text out of a region. | |
591 | * copy-region-as-kill:: A definition for copying text. | |
592 | * Digression into C:: Minor note on C programming language macros. | |
593 | * defvar:: How to give a variable an initial value. | |
594 | * cons & search-fwd Review:: | |
595 | * search Exercises:: | |
596 | ||
597 | @code{zap-to-char} | |
598 | ||
599 | * Complete zap-to-char:: The complete implementation. | |
600 | * zap-to-char interactive:: A three part interactive expression. | |
601 | * zap-to-char body:: A short overview. | |
602 | * search-forward:: How to search for a string. | |
603 | * progn:: The @code{progn} special form. | |
604 | * Summing up zap-to-char:: Using @code{point} and @code{search-forward}. | |
605 | ||
606 | @code{kill-region} | |
607 | ||
608 | * Complete kill-region:: The function definition. | |
609 | * condition-case:: Dealing with a problem. | |
610 | * Lisp macro:: | |
611 | ||
612 | @code{copy-region-as-kill} | |
613 | ||
614 | * Complete copy-region-as-kill:: The complete function definition. | |
615 | * copy-region-as-kill body:: The body of @code{copy-region-as-kill}. | |
616 | ||
617 | The Body of @code{copy-region-as-kill} | |
618 | ||
619 | * last-command & this-command:: | |
620 | * kill-append function:: | |
621 | * kill-new function:: | |
622 | ||
623 | Initializing a Variable with @code{defvar} | |
624 | ||
625 | * See variable current value:: | |
626 | * defvar and asterisk:: | |
627 | ||
628 | How Lists are Implemented | |
629 | ||
630 | * Lists diagrammed:: | |
631 | * Symbols as Chest:: Exploring a powerful metaphor. | |
632 | * List Exercise:: | |
633 | ||
634 | Yanking Text Back | |
635 | ||
636 | * Kill Ring Overview:: | |
637 | * kill-ring-yank-pointer:: The kill ring is a list. | |
638 | * yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. | |
639 | ||
640 | Loops and Recursion | |
641 | ||
642 | * while:: Causing a stretch of code to repeat. | |
643 | * dolist dotimes:: | |
644 | * Recursion:: Causing a function to call itself. | |
645 | * Looping exercise:: | |
646 | ||
647 | @code{while} | |
648 | ||
649 | * Looping with while:: Repeat so long as test returns true. | |
650 | * Loop Example:: A @code{while} loop that uses a list. | |
651 | * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. | |
652 | * Incrementing Loop:: A loop with an incrementing counter. | |
653 | * Incrementing Loop Details:: | |
654 | * Decrementing Loop:: A loop with a decrementing counter. | |
655 | ||
656 | Details of an Incrementing Loop | |
657 | ||
658 | * Incrementing Example:: Counting pebbles in a triangle. | |
659 | * Inc Example parts:: The parts of the function definition. | |
660 | * Inc Example altogether:: Putting the function definition together. | |
661 | ||
662 | Loop with a Decrementing Counter | |
663 | ||
664 | * Decrementing Example:: More pebbles on the beach. | |
665 | * Dec Example parts:: The parts of the function definition. | |
666 | * Dec Example altogether:: Putting the function definition together. | |
667 | ||
668 | Save your time: @code{dolist} and @code{dotimes} | |
669 | ||
670 | * dolist:: | |
671 | * dotimes:: | |
672 | ||
673 | Recursion | |
674 | ||
675 | * Building Robots:: Same model, different serial number ... | |
676 | * Recursive Definition Parts:: Walk until you stop ... | |
677 | * Recursion with list:: Using a list as the test whether to recurse. | |
678 | * Recursive triangle function:: | |
679 | * Recursion with cond:: | |
680 | * Recursive Patterns:: Often used templates. | |
681 | * No Deferment:: Don't store up work ... | |
682 | * No deferment solution:: | |
683 | ||
684 | Recursion in Place of a Counter | |
685 | ||
686 | * Recursive Example arg of 1 or 2:: | |
687 | * Recursive Example arg of 3 or 4:: | |
688 | ||
689 | Recursive Patterns | |
690 | ||
691 | * Every:: | |
692 | * Accumulate:: | |
693 | * Keep:: | |
694 | ||
695 | Regular Expression Searches | |
696 | ||
697 | * sentence-end:: The regular expression for @code{sentence-end}. | |
698 | * re-search-forward:: Very similar to @code{search-forward}. | |
699 | * forward-sentence:: A straightforward example of regexp search. | |
700 | * forward-paragraph:: A somewhat complex example. | |
701 | * etags:: How to create your own @file{TAGS} table. | |
702 | * Regexp Review:: | |
703 | * re-search Exercises:: | |
704 | ||
705 | @code{forward-sentence} | |
706 | ||
707 | * Complete forward-sentence:: | |
708 | * fwd-sentence while loops:: Two @code{while} loops. | |
709 | * fwd-sentence re-search:: A regular expression search. | |
710 | ||
711 | @code{forward-paragraph}: a Goldmine of Functions | |
712 | ||
713 | * forward-paragraph in brief:: Key parts of the function definition. | |
714 | * fwd-para let:: The @code{let*} expression. | |
715 | * fwd-para while:: The forward motion @code{while} loop. | |
716 | ||
717 | Counting: Repetition and Regexps | |
718 | ||
719 | * Why Count Words:: | |
ea4f7750 | 720 | * @value{COUNT-WORDS}:: Use a regexp, but find a problem. |
8cda6f8f GM |
721 | * recursive-count-words:: Start with case of no words in region. |
722 | * Counting Exercise:: | |
723 | ||
ea4f7750 | 724 | The @code{@value{COUNT-WORDS}} Function |
8cda6f8f | 725 | |
ea4f7750 GM |
726 | * Design @value{COUNT-WORDS}:: The definition using a @code{while} loop. |
727 | * Whitespace Bug:: The Whitespace Bug in @code{@value{COUNT-WORDS}}. | |
8cda6f8f GM |
728 | |
729 | Counting Words in a @code{defun} | |
730 | ||
731 | * Divide and Conquer:: | |
732 | * Words and Symbols:: What to count? | |
733 | * Syntax:: What constitutes a word or symbol? | |
ea4f7750 | 734 | * count-words-in-defun:: Very like @code{@value{COUNT-WORDS}}. |
8cda6f8f GM |
735 | * Several defuns:: Counting several defuns in a file. |
736 | * Find a File:: Do you want to look at a file? | |
737 | * lengths-list-file:: A list of the lengths of many definitions. | |
738 | * Several files:: Counting in definitions in different files. | |
739 | * Several files recursively:: Recursively counting in different files. | |
740 | * Prepare the data:: Prepare the data for display in a graph. | |
741 | ||
742 | Count Words in @code{defuns} in Different Files | |
743 | ||
744 | * lengths-list-many-files:: Return a list of the lengths of defuns. | |
745 | * append:: Attach one list to another. | |
746 | ||
747 | Prepare the Data for Display in a Graph | |
748 | ||
749 | * Data for Display in Detail:: | |
750 | * Sorting:: Sorting lists. | |
751 | * Files List:: Making a list of files. | |
752 | * Counting function definitions:: | |
753 | ||
754 | Readying a Graph | |
755 | ||
756 | * Columns of a graph:: | |
757 | * graph-body-print:: How to print the body of a graph. | |
758 | * recursive-graph-body-print:: | |
759 | * Printed Axes:: | |
760 | * Line Graph Exercise:: | |
761 | ||
762 | Your @file{.emacs} File | |
763 | ||
764 | * Default Configuration:: | |
765 | * Site-wide Init:: You can write site-wide init files. | |
766 | * defcustom:: Emacs will write code for you. | |
767 | * Beginning a .emacs File:: How to write a @code{.emacs file}. | |
768 | * Text and Auto-fill:: Automatically wrap lines. | |
769 | * Mail Aliases:: Use abbreviations for email addresses. | |
770 | * Indent Tabs Mode:: Don't use tabs with @TeX{} | |
771 | * Keybindings:: Create some personal keybindings. | |
772 | * Keymaps:: More about key binding. | |
773 | * Loading Files:: Load (i.e., evaluate) files automatically. | |
774 | * Autoload:: Make functions available. | |
775 | * Simple Extension:: Define a function; bind it to a key. | |
776 | * X11 Colors:: Colors in X. | |
777 | * Miscellaneous:: | |
778 | * Mode Line:: How to customize your mode line. | |
779 | ||
780 | Debugging | |
781 | ||
782 | * debug:: How to use the built-in debugger. | |
783 | * debug-on-entry:: Start debugging when you call a function. | |
784 | * debug-on-quit:: Start debugging when you quit with @kbd{C-g}. | |
785 | * edebug:: How to use Edebug, a source level debugger. | |
786 | * Debugging Exercises:: | |
787 | ||
788 | Handling the Kill Ring | |
789 | ||
790 | * What the Kill Ring Does:: | |
791 | * current-kill:: | |
792 | * yank:: Paste a copy of a clipped element. | |
793 | * yank-pop:: Insert element pointed to. | |
794 | * ring file:: | |
795 | ||
796 | The @code{current-kill} Function | |
797 | ||
45d77375 | 798 | * Code for current-kill:: |
8cda6f8f GM |
799 | * Understanding current-kill:: |
800 | ||
801 | @code{current-kill} in Outline | |
802 | ||
803 | * Body of current-kill:: | |
804 | * Digression concerning error:: How to mislead humans, but not computers. | |
805 | * Determining the Element:: | |
806 | ||
09e80d9f | 807 | A Graph with Labeled Axes |
8cda6f8f | 808 | |
09e80d9f | 809 | * Labeled Example:: |
8cda6f8f GM |
810 | * print-graph Varlist:: @code{let} expression in @code{print-graph}. |
811 | * print-Y-axis:: Print a label for the vertical axis. | |
812 | * print-X-axis:: Print a horizontal label. | |
813 | * Print Whole Graph:: The function to print a complete graph. | |
814 | ||
815 | The @code{print-Y-axis} Function | |
816 | ||
817 | * print-Y-axis in Detail:: | |
818 | * Height of label:: What height for the Y axis? | |
819 | * Compute a Remainder:: How to compute the remainder of a division. | |
820 | * Y Axis Element:: Construct a line for the Y axis. | |
821 | * Y-axis-column:: Generate a list of Y axis labels. | |
822 | * print-Y-axis Penultimate:: A not quite final version. | |
823 | ||
824 | The @code{print-X-axis} Function | |
825 | ||
826 | * Similarities differences:: Much like @code{print-Y-axis}, but not exactly. | |
827 | * X Axis Tic Marks:: Create tic marks for the horizontal axis. | |
828 | ||
829 | Printing the Whole Graph | |
830 | ||
831 | * The final version:: A few changes. | |
832 | * Test print-graph:: Run a short test. | |
833 | * Graphing words in defuns:: Executing the final code. | |
834 | * lambda:: How to write an anonymous function. | |
835 | * mapcar:: Apply a function to elements of a list. | |
836 | * Another Bug:: Yet another bug @dots{} most insidious. | |
837 | * Final printed graph:: The graph itself! | |
838 | ||
839 | @end detailmenu | |
840 | @end menu | |
841 | ||
d6adf7e7 | 842 | @node Preface |
8cda6f8f GM |
843 | @unnumbered Preface |
844 | ||
845 | Most of the GNU Emacs integrated environment is written in the programming | |
846 | language called Emacs Lisp. The code written in this programming | |
847 | language is the software---the sets of instructions---that tell the | |
848 | computer what to do when you give it commands. Emacs is designed so | |
849 | that you can write new code in Emacs Lisp and easily install it as an | |
850 | extension to the editor. | |
851 | ||
852 | (GNU Emacs is sometimes called an ``extensible editor'', but it does | |
853 | much more than provide editing capabilities. It is better to refer to | |
854 | Emacs as an ``extensible computing environment''. However, that | |
855 | phrase is quite a mouthful. It is easier to refer to Emacs simply as | |
856 | an editor. Moreover, everything you do in Emacs---find the Mayan date | |
857 | and phases of the moon, simplify polynomials, debug code, manage | |
858 | files, read letters, write books---all these activities are kinds of | |
859 | editing in the most general sense of the word.) | |
860 | ||
861 | @menu | |
862 | * Why:: Why learn Emacs Lisp? | |
863 | * On Reading this Text:: Read, gain familiarity, pick up habits.... | |
864 | * Who You Are:: For whom this is written. | |
865 | * Lisp History:: | |
866 | * Note for Novices:: You can read this as a novice. | |
867 | * Thank You:: | |
868 | @end menu | |
869 | ||
8cda6f8f | 870 | @ifnottex |
d6adf7e7 | 871 | @node Why |
8cda6f8f GM |
872 | @unnumberedsec Why Study Emacs Lisp? |
873 | @end ifnottex | |
874 | ||
875 | Although Emacs Lisp is usually thought of in association only with Emacs, | |
876 | it is a full computer programming language. You can use Emacs Lisp as | |
877 | you would any other programming language. | |
878 | ||
879 | Perhaps you want to understand programming; perhaps you want to extend | |
880 | Emacs; or perhaps you want to become a programmer. This introduction to | |
881 | Emacs Lisp is designed to get you started: to guide you in learning the | |
882 | fundamentals of programming, and more importantly, to show you how you | |
883 | can teach yourself to go further. | |
884 | ||
d6adf7e7 | 885 | @node On Reading this Text |
8cda6f8f GM |
886 | @unnumberedsec On Reading this Text |
887 | ||
888 | All through this document, you will see little sample programs you can | |
889 | run inside of Emacs. If you read this document in Info inside of GNU | |
890 | Emacs, you can run the programs as they appear. (This is easy to do and | |
891 | is explained when the examples are presented.) Alternatively, you can | |
892 | read this introduction as a printed book while sitting beside a computer | |
893 | running Emacs. (This is what I like to do; I like printed books.) If | |
894 | you don't have a running Emacs beside you, you can still read this book, | |
895 | but in this case, it is best to treat it as a novel or as a travel guide | |
896 | to a country not yet visited: interesting, but not the same as being | |
897 | there. | |
898 | ||
40ba43b4 | 899 | Much of this introduction is dedicated to walkthroughs or guided tours |
8cda6f8f GM |
900 | of code used in GNU Emacs. These tours are designed for two purposes: |
901 | first, to give you familiarity with real, working code (code you use | |
902 | every day); and, second, to give you familiarity with the way Emacs | |
903 | works. It is interesting to see how a working environment is | |
904 | implemented. | |
905 | Also, I | |
906 | hope that you will pick up the habit of browsing through source code. | |
907 | You can learn from it and mine it for ideas. Having GNU Emacs is like | |
908 | having a dragon's cave of treasures. | |
909 | ||
910 | In addition to learning about Emacs as an editor and Emacs Lisp as a | |
911 | programming language, the examples and guided tours will give you an | |
912 | opportunity to get acquainted with Emacs as a Lisp programming | |
913 | environment. GNU Emacs supports programming and provides tools that | |
914 | you will want to become comfortable using, such as @kbd{M-.} (the key | |
915 | which invokes the @code{find-tag} command). You will also learn about | |
916 | buffers and other objects that are part of the environment. | |
917 | Learning about these features of Emacs is like learning new routes | |
918 | around your home town. | |
919 | ||
920 | @ignore | |
921 | In addition, I have written several programs as extended examples. | |
922 | Although these are examples, the programs are real. I use them. | |
923 | Other people use them. You may use them. Beyond the fragments of | |
924 | programs used for illustrations, there is very little in here that is | |
925 | `just for teaching purposes'; what you see is used. This is a great | |
926 | advantage of Emacs Lisp: it is easy to learn to use it for work. | |
927 | @end ignore | |
928 | ||
929 | Finally, I hope to convey some of the skills for using Emacs to | |
930 | learn aspects of programming that you don't know. You can often use | |
931 | Emacs to help you understand what puzzles you or to find out how to do | |
932 | something new. This self-reliance is not only a pleasure, but an | |
933 | advantage. | |
934 | ||
d6adf7e7 | 935 | @node Who You Are |
8cda6f8f GM |
936 | @unnumberedsec For Whom This is Written |
937 | ||
938 | This text is written as an elementary introduction for people who are | |
939 | not programmers. If you are a programmer, you may not be satisfied with | |
940 | this primer. The reason is that you may have become expert at reading | |
941 | reference manuals and be put off by the way this text is organized. | |
942 | ||
943 | An expert programmer who reviewed this text said to me: | |
944 | ||
945 | @quotation | |
946 | @i{I prefer to learn from reference manuals. I ``dive into'' each | |
947 | paragraph, and ``come up for air'' between paragraphs.} | |
948 | ||
949 | @i{When I get to the end of a paragraph, I assume that that subject is | |
950 | done, finished, that I know everything I need (with the | |
951 | possible exception of the case when the next paragraph starts talking | |
952 | about it in more detail). I expect that a well written reference manual | |
953 | will not have a lot of redundancy, and that it will have excellent | |
954 | pointers to the (one) place where the information I want is.} | |
955 | @end quotation | |
956 | ||
957 | This introduction is not written for this person! | |
958 | ||
959 | Firstly, I try to say everything at least three times: first, to | |
960 | introduce it; second, to show it in context; and third, to show it in a | |
961 | different context, or to review it. | |
962 | ||
963 | Secondly, I hardly ever put all the information about a subject in one | |
964 | place, much less in one paragraph. To my way of thinking, that imposes | |
965 | too heavy a burden on the reader. Instead I try to explain only what | |
966 | you need to know at the time. (Sometimes I include a little extra | |
967 | information so you won't be surprised later when the additional | |
968 | information is formally introduced.) | |
969 | ||
970 | When you read this text, you are not expected to learn everything the | |
971 | first time. Frequently, you need only make, as it were, a `nodding | |
972 | acquaintance' with some of the items mentioned. My hope is that I have | |
973 | structured the text and given you enough hints that you will be alert to | |
974 | what is important, and concentrate on it. | |
975 | ||
976 | You will need to ``dive into'' some paragraphs; there is no other way | |
977 | to read them. But I have tried to keep down the number of such | |
978 | paragraphs. This book is intended as an approachable hill, rather than | |
979 | as a daunting mountain. | |
980 | ||
981 | This introduction to @cite{Programming in Emacs Lisp} has a companion | |
982 | document, | |
983 | @iftex | |
984 | @cite{The GNU Emacs Lisp Reference Manual}. | |
985 | @end iftex | |
986 | @ifnottex | |
987 | @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU | |
988 | Emacs Lisp Reference Manual}. | |
989 | @end ifnottex | |
990 | The reference manual has more detail than this introduction. In the | |
991 | reference manual, all the information about one topic is concentrated | |
992 | in one place. You should turn to it if you are like the programmer | |
993 | quoted above. And, of course, after you have read this | |
994 | @cite{Introduction}, you will find the @cite{Reference Manual} useful | |
995 | when you are writing your own programs. | |
996 | ||
d6adf7e7 | 997 | @node Lisp History |
8cda6f8f GM |
998 | @unnumberedsec Lisp History |
999 | @cindex Lisp history | |
1000 | ||
1001 | Lisp was first developed in the late 1950s at the Massachusetts | |
1002 | Institute of Technology for research in artificial intelligence. The | |
1003 | great power of the Lisp language makes it superior for other purposes as | |
1004 | well, such as writing editor commands and integrated environments. | |
1005 | ||
1006 | @cindex Maclisp | |
1007 | @cindex Common Lisp | |
1008 | GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT | |
1009 | in the 1960s. It is somewhat inspired by Common Lisp, which became a | |
1010 | standard in the 1980s. However, Emacs Lisp is much simpler than Common | |
1011 | Lisp. (The standard Emacs distribution contains an optional extensions | |
1012 | file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) | |
1013 | ||
d6adf7e7 | 1014 | @node Note for Novices |
8cda6f8f GM |
1015 | @unnumberedsec A Note for Novices |
1016 | ||
1017 | If you don't know GNU Emacs, you can still read this document | |
1018 | profitably. However, I recommend you learn Emacs, if only to learn to | |
1019 | move around your computer screen. You can teach yourself how to use | |
1020 | Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This | |
1021 | means you press and release the @key{CTRL} key and the @kbd{h} at the | |
1022 | same time, and then press and release @kbd{t}.) | |
1023 | ||
44e97401 | 1024 | Also, I often refer to one of Emacs's standard commands by listing the |
8cda6f8f GM |
1025 | keys which you press to invoke the command and then giving the name of |
1026 | the command in parentheses, like this: @kbd{M-C-\} | |
1027 | (@code{indent-region}). What this means is that the | |
1028 | @code{indent-region} command is customarily invoked by typing | |
1029 | @kbd{M-C-\}. (You can, if you wish, change the keys that are typed to | |
1030 | invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, , | |
1031 | Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your | |
1032 | @key{META} key, @key{CTRL} key and @key{\} key all at the same time. | |
09e80d9f | 1033 | (On many modern keyboards the @key{META} key is labeled |
8cda6f8f GM |
1034 | @key{ALT}.) |
1035 | Sometimes a combination like this is called a keychord, since it is | |
1036 | similar to the way you play a chord on a piano. If your keyboard does | |
1037 | not have a @key{META} key, the @key{ESC} key prefix is used in place | |
1038 | of it. In this case, @kbd{M-C-\} means that you press and release your | |
1039 | @key{ESC} key and then type the @key{CTRL} key and the @key{\} key at | |
1040 | the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key | |
09e80d9f | 1041 | along with the key that is labeled @key{ALT} and, at the same time, |
8cda6f8f GM |
1042 | press the @key{\} key. |
1043 | ||
1044 | In addition to typing a lone keychord, you can prefix what you type | |
1045 | with @kbd{C-u}, which is called the `universal argument'. The | |
1046 | @kbd{C-u} keychord passes an argument to the subsequent command. | |
1047 | Thus, to indent a region of plain text by 6 spaces, mark the region, | |
1048 | and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number, | |
1049 | Emacs either passes the number 4 to the command or otherwise runs the | |
1050 | command differently than it would otherwise.) @xref{Arguments, , | |
1051 | Numeric Arguments, emacs, The GNU Emacs Manual}. | |
1052 | ||
1053 | If you are reading this in Info using GNU Emacs, you can read through | |
1054 | this whole document just by pressing the space bar, @key{SPC}. | |
1055 | (To learn about Info, type @kbd{C-h i} and then select Info.) | |
1056 | ||
1057 | A note on terminology: when I use the word Lisp alone, I often am | |
1058 | referring to the various dialects of Lisp in general, but when I speak | |
1059 | of Emacs Lisp, I am referring to GNU Emacs Lisp in particular. | |
1060 | ||
d6adf7e7 | 1061 | @node Thank You |
8cda6f8f GM |
1062 | @unnumberedsec Thank You |
1063 | ||
1064 | My thanks to all who helped me with this book. My especial thanks to | |
1065 | @r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland | |
1df7defd | 1066 | McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M. |
8cda6f8f GM |
1067 | Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both |
1068 | @w{Philip Johnson} and @w{David Stampe} for their patient | |
1069 | encouragement. My mistakes are my own. | |
1070 | ||
1071 | @flushright | |
1072 | Robert J. Chassell | |
4724cafb | 1073 | @email{bob@@gnu.org} |
8cda6f8f GM |
1074 | @end flushright |
1075 | ||
1076 | @c ================ Beginning of main text ================ | |
1077 | ||
1078 | @c Start main text on right-hand (verso) page | |
1079 | ||
1080 | @tex | |
1081 | \par\vfill\supereject | |
1082 | \headings off | |
1083 | \ifodd\pageno | |
1084 | \par\vfill\supereject | |
1085 | \else | |
1086 | \par\vfill\supereject | |
1087 | \page\hbox{}\page | |
1088 | \par\vfill\supereject | |
1089 | \fi | |
1090 | @end tex | |
1091 | ||
52af8e0a GM |
1092 | @c Note: this resetting of the page number back to 1 causes TeX to gripe |
1093 | @c about already having seen page numbers 1-4 before (in the preface): | |
1094 | @c pdfTeX warning (ext4): destination with the same identifier (name{1}) | |
1095 | @c has been already used, duplicate ignored | |
1096 | @c I guess that is harmless (what happens if a later part of the text | |
1097 | @c makes a link to something in the first 4 pages though?). | |
1df7defd | 1098 | @c E.g., note that the Emacs manual has a preface, but does not bother |
52af8e0a | 1099 | @c resetting the page numbers back to 1 after that. |
8cda6f8f GM |
1100 | @iftex |
1101 | @headings off | |
1102 | @evenheading @thispage @| @| @thischapter | |
1103 | @oddheading @thissection @| @| @thispage | |
1104 | @global@pageno = 1 | |
1105 | @end iftex | |
1106 | ||
d6adf7e7 | 1107 | @node List Processing |
8cda6f8f GM |
1108 | @chapter List Processing |
1109 | ||
1110 | To the untutored eye, Lisp is a strange programming language. In Lisp | |
1111 | code there are parentheses everywhere. Some people even claim that | |
1112 | the name stands for `Lots of Isolated Silly Parentheses'. But the | |
1113 | claim is unwarranted. Lisp stands for LISt Processing, and the | |
1114 | programming language handles @emph{lists} (and lists of lists) by | |
1115 | putting them between parentheses. The parentheses mark the boundaries | |
1116 | of the list. Sometimes a list is preceded by a single apostrophe or | |
1117 | quotation mark, @samp{'}@footnote{The single apostrophe or quotation | |
1118 | mark is an abbreviation for the function @code{quote}; you need not | |
1119 | think about functions now; functions are defined in @ref{Making | |
1120 | Errors, , Generate an Error Message}.} Lists are the basis of Lisp. | |
1121 | ||
1122 | @menu | |
1123 | * Lisp Lists:: What are lists? | |
1124 | * Run a Program:: Any list in Lisp is a program ready to run. | |
1125 | * Making Errors:: Generating an error message. | |
1126 | * Names & Definitions:: Names of symbols and function definitions. | |
1127 | * Lisp Interpreter:: What the Lisp interpreter does. | |
1128 | * Evaluation:: Running a program. | |
1129 | * Variables:: Returning a value from a variable. | |
1130 | * Arguments:: Passing information to a function. | |
1131 | * set & setq:: Setting the value of a variable. | |
1132 | * Summary:: The major points. | |
1133 | * Error Message Exercises:: | |
1134 | @end menu | |
1135 | ||
d6adf7e7 | 1136 | @node Lisp Lists |
8cda6f8f GM |
1137 | @section Lisp Lists |
1138 | @cindex Lisp Lists | |
1139 | ||
1140 | In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}. | |
1141 | This list is preceded by a single apostrophe. It could just as well be | |
1142 | written as follows, which looks more like the kind of list you are likely | |
1143 | to be familiar with: | |
1144 | ||
1145 | @smallexample | |
1146 | @group | |
1147 | '(rose | |
1148 | violet | |
1149 | daisy | |
1150 | buttercup) | |
1151 | @end group | |
1152 | @end smallexample | |
1153 | ||
1154 | @noindent | |
1155 | The elements of this list are the names of the four different flowers, | |
1156 | separated from each other by whitespace and surrounded by parentheses, | |
1157 | like flowers in a field with a stone wall around them. | |
1158 | @cindex Flowers in a field | |
1159 | ||
1160 | @menu | |
1161 | * Numbers Lists:: List have numbers, other lists, in them. | |
1162 | * Lisp Atoms:: Elemental entities. | |
1163 | * Whitespace in Lists:: Formatting lists to be readable. | |
1164 | * Typing Lists:: How GNU Emacs helps you type lists. | |
1165 | @end menu | |
1166 | ||
8cda6f8f | 1167 | @ifnottex |
d6adf7e7 | 1168 | @node Numbers Lists |
8cda6f8f GM |
1169 | @unnumberedsubsec Numbers, Lists inside of Lists |
1170 | @end ifnottex | |
1171 | ||
1172 | Lists can also have numbers in them, as in this list: @code{(+ 2 2)}. | |
1173 | This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each | |
1174 | separated by whitespace. | |
1175 | ||
1176 | In Lisp, both data and programs are represented the same way; that is, | |
1177 | they are both lists of words, numbers, or other lists, separated by | |
1178 | whitespace and surrounded by parentheses. (Since a program looks like | |
1179 | data, one program may easily serve as data for another; this is a very | |
1180 | powerful feature of Lisp.) (Incidentally, these two parenthetical | |
1181 | remarks are @emph{not} Lisp lists, because they contain @samp{;} and | |
1182 | @samp{.} as punctuation marks.) | |
1183 | ||
1184 | @need 1200 | |
1185 | Here is another list, this time with a list inside of it: | |
1186 | ||
1187 | @smallexample | |
1188 | '(this list has (a list inside of it)) | |
1189 | @end smallexample | |
1190 | ||
1191 | The components of this list are the words @samp{this}, @samp{list}, | |
1192 | @samp{has}, and the list @samp{(a list inside of it)}. The interior | |
1193 | list is made up of the words @samp{a}, @samp{list}, @samp{inside}, | |
1194 | @samp{of}, @samp{it}. | |
1195 | ||
d6adf7e7 | 1196 | @node Lisp Atoms |
8cda6f8f GM |
1197 | @subsection Lisp Atoms |
1198 | @cindex Lisp Atoms | |
1199 | ||
1200 | In Lisp, what we have been calling words are called @dfn{atoms}. This | |
1201 | term comes from the historical meaning of the word atom, which means | |
1202 | `indivisible'. As far as Lisp is concerned, the words we have been | |
1203 | using in the lists cannot be divided into any smaller parts and still | |
1204 | mean the same thing as part of a program; likewise with numbers and | |
1205 | single character symbols like @samp{+}. On the other hand, unlike an | |
1206 | ancient atom, a list can be split into parts. (@xref{car cdr & cons, | |
1207 | , @code{car} @code{cdr} & @code{cons} Fundamental Functions}.) | |
1208 | ||
1209 | In a list, atoms are separated from each other by whitespace. They can be | |
1210 | right next to a parenthesis. | |
1211 | ||
1212 | @cindex @samp{empty list} defined | |
1213 | Technically speaking, a list in Lisp consists of parentheses surrounding | |
1214 | atoms separated by whitespace or surrounding other lists or surrounding | |
1215 | both atoms and other lists. A list can have just one atom in it or | |
1216 | have nothing in it at all. A list with nothing in it looks like this: | |
1217 | @code{()}, and is called the @dfn{empty list}. Unlike anything else, an | |
1218 | empty list is considered both an atom and a list at the same time. | |
1219 | ||
1220 | @cindex Symbolic expressions, introduced | |
1221 | @cindex @samp{expression} defined | |
1222 | @cindex @samp{form} defined | |
1223 | The printed representation of both atoms and lists are called | |
1224 | @dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}. | |
1225 | The word @dfn{expression} by itself can refer to either the printed | |
1226 | representation, or to the atom or list as it is held internally in the | |
1227 | computer. Often, people use the term @dfn{expression} | |
1228 | indiscriminately. (Also, in many texts, the word @dfn{form} is used | |
1229 | as a synonym for expression.) | |
1230 | ||
1231 | Incidentally, the atoms that make up our universe were named such when | |
1232 | they were thought to be indivisible; but it has been found that physical | |
1233 | atoms are not indivisible. Parts can split off an atom or it can | |
1234 | fission into two parts of roughly equal size. Physical atoms were named | |
1235 | prematurely, before their truer nature was found. In Lisp, certain | |
1236 | kinds of atom, such as an array, can be separated into parts; but the | |
1237 | mechanism for doing this is different from the mechanism for splitting a | |
1238 | list. As far as list operations are concerned, the atoms of a list are | |
1239 | unsplittable. | |
1240 | ||
1241 | As in English, the meanings of the component letters of a Lisp atom | |
1242 | are different from the meaning the letters make as a word. For | |
1243 | example, the word for the South American sloth, the @samp{ai}, is | |
1244 | completely different from the two words, @samp{a}, and @samp{i}. | |
1245 | ||
1246 | There are many kinds of atom in nature but only a few in Lisp: for | |
1247 | example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such | |
1248 | as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have | |
1249 | listed in the examples above are all symbols. In everyday Lisp | |
1250 | conversation, the word ``atom'' is not often used, because programmers | |
1251 | usually try to be more specific about what kind of atom they are dealing | |
1252 | with. Lisp programming is mostly about symbols (and sometimes numbers) | |
1253 | within lists. (Incidentally, the preceding three word parenthetical | |
1254 | remark is a proper list in Lisp, since it consists of atoms, which in | |
1255 | this case are symbols, separated by whitespace and enclosed by | |
1256 | parentheses, without any non-Lisp punctuation.) | |
1257 | ||
1258 | @need 1250 | |
6c499932 CY |
1259 | Text between double quotation marks---even sentences or |
1260 | paragraphs---is also an atom. Here is an example: | |
8cda6f8f GM |
1261 | @cindex Text between double quotation marks |
1262 | ||
1263 | @smallexample | |
1264 | '(this list includes "text between quotation marks.") | |
1265 | @end smallexample | |
1266 | ||
1267 | @cindex @samp{string} defined | |
1268 | @noindent | |
1269 | In Lisp, all of the quoted text including the punctuation mark and the | |
1270 | blank spaces is a single atom. This kind of atom is called a | |
1271 | @dfn{string} (for `string of characters') and is the sort of thing that | |
1272 | is used for messages that a computer can print for a human to read. | |
1273 | Strings are a different kind of atom than numbers or symbols and are | |
1274 | used differently. | |
1275 | ||
d6adf7e7 | 1276 | @node Whitespace in Lists |
8cda6f8f GM |
1277 | @subsection Whitespace in Lists |
1278 | @cindex Whitespace in lists | |
1279 | ||
1280 | @need 1200 | |
1281 | The amount of whitespace in a list does not matter. From the point of view | |
1282 | of the Lisp language, | |
1283 | ||
1284 | @smallexample | |
1285 | @group | |
1286 | '(this list | |
1287 | looks like this) | |
1288 | @end group | |
1289 | @end smallexample | |
1290 | ||
1291 | @need 800 | |
1292 | @noindent | |
1293 | is exactly the same as this: | |
1294 | ||
1295 | @smallexample | |
1296 | '(this list looks like this) | |
1297 | @end smallexample | |
1298 | ||
1299 | Both examples show what to Lisp is the same list, the list made up of | |
1300 | the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and | |
1301 | @samp{this} in that order. | |
1302 | ||
1303 | Extra whitespace and newlines are designed to make a list more readable | |
1304 | by humans. When Lisp reads the expression, it gets rid of all the extra | |
1305 | whitespace (but it needs to have at least one space between atoms in | |
1306 | order to tell them apart.) | |
1307 | ||
1308 | Odd as it seems, the examples we have seen cover almost all of what Lisp | |
1309 | lists look like! Every other list in Lisp looks more or less like one | |
1310 | of these examples, except that the list may be longer and more complex. | |
1311 | In brief, a list is between parentheses, a string is between quotation | |
1312 | marks, a symbol looks like a word, and a number looks like a number. | |
1313 | (For certain situations, square brackets, dots and a few other special | |
1314 | characters may be used; however, we will go quite far without them.) | |
1315 | ||
d6adf7e7 | 1316 | @node Typing Lists |
8cda6f8f GM |
1317 | @subsection GNU Emacs Helps You Type Lists |
1318 | @cindex Help typing lists | |
1319 | @cindex Formatting help | |
1320 | ||
1321 | When you type a Lisp expression in GNU Emacs using either Lisp | |
1322 | Interaction mode or Emacs Lisp mode, you have available to you several | |
1323 | commands to format the Lisp expression so it is easy to read. For | |
1324 | example, pressing the @key{TAB} key automatically indents the line the | |
1325 | cursor is on by the right amount. A command to properly indent the | |
1326 | code in a region is customarily bound to @kbd{M-C-\}. Indentation is | |
1327 | designed so that you can see which elements of a list belong to which | |
1328 | list---elements of a sub-list are indented more than the elements of | |
1329 | the enclosing list. | |
1330 | ||
1331 | In addition, when you type a closing parenthesis, Emacs momentarily | |
1332 | jumps the cursor back to the matching opening parenthesis, so you can | |
1333 | see which one it is. This is very useful, since every list you type | |
1334 | in Lisp must have its closing parenthesis match its opening | |
1335 | parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs | |
44e97401 | 1336 | Manual}, for more information about Emacs's modes.) |
8cda6f8f | 1337 | |
d6adf7e7 | 1338 | @node Run a Program |
8cda6f8f GM |
1339 | @section Run a Program |
1340 | @cindex Run a program | |
1341 | @cindex Program, running one | |
1342 | ||
1343 | @cindex @samp{evaluate} defined | |
1344 | A list in Lisp---any list---is a program ready to run. If you run it | |
1345 | (for which the Lisp jargon is @dfn{evaluate}), the computer will do one | |
1346 | of three things: do nothing except return to you the list itself; send | |
1347 | you an error message; or, treat the first symbol in the list as a | |
1348 | command to do something. (Usually, of course, it is the last of these | |
1349 | three things that you really want!) | |
1350 | ||
1351 | @c use code for the single apostrophe, not samp. | |
1352 | The single apostrophe, @code{'}, that I put in front of some of the | |
1353 | example lists in preceding sections is called a @dfn{quote}; when it | |
1354 | precedes a list, it tells Lisp to do nothing with the list, other than | |
1355 | take it as it is written. But if there is no quote preceding a list, | |
1356 | the first item of the list is special: it is a command for the computer | |
1357 | to obey. (In Lisp, these commands are called @emph{functions}.) The list | |
1358 | @code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp | |
1359 | understands that the @code{+} is an instruction to do something with the | |
1360 | rest of the list: add the numbers that follow. | |
1361 | ||
1362 | @need 1250 | |
1363 | If you are reading this inside of GNU Emacs in Info, here is how you can | |
1364 | evaluate such a list: place your cursor immediately after the right | |
1365 | hand parenthesis of the following list and then type @kbd{C-x C-e}: | |
1366 | ||
1367 | @smallexample | |
1368 | (+ 2 2) | |
1369 | @end smallexample | |
1370 | ||
1371 | @c use code for the number four, not samp. | |
1372 | @noindent | |
1373 | You will see the number @code{4} appear in the echo area. (In the | |
1374 | jargon, what you have just done is ``evaluate the list.'' The echo area | |
1375 | is the line at the bottom of the screen that displays or ``echoes'' | |
1376 | text.) Now try the same thing with a quoted list: place the cursor | |
1377 | right after the following list and type @kbd{C-x C-e}: | |
1378 | ||
1379 | @smallexample | |
1380 | '(this is a quoted list) | |
1381 | @end smallexample | |
1382 | ||
1383 | @noindent | |
1384 | You will see @code{(this is a quoted list)} appear in the echo area. | |
1385 | ||
1386 | @cindex Lisp interpreter, explained | |
1387 | @cindex Interpreter, Lisp, explained | |
1388 | In both cases, what you are doing is giving a command to the program | |
1389 | inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the | |
1390 | interpreter a command to evaluate the expression. The name of the Lisp | |
1391 | interpreter comes from the word for the task done by a human who comes | |
1392 | up with the meaning of an expression---who ``interprets'' it. | |
1393 | ||
1394 | You can also evaluate an atom that is not part of a list---one that is | |
1395 | not surrounded by parentheses; again, the Lisp interpreter translates | |
1396 | from the humanly readable expression to the language of the computer. | |
1397 | But before discussing this (@pxref{Variables}), we will discuss what the | |
1398 | Lisp interpreter does when you make an error. | |
1399 | ||
d6adf7e7 | 1400 | @node Making Errors |
8cda6f8f GM |
1401 | @section Generate an Error Message |
1402 | @cindex Generate an error message | |
1403 | @cindex Error message generation | |
1404 | ||
1405 | Partly so you won't worry if you do it accidentally, we will now give | |
1406 | a command to the Lisp interpreter that generates an error message. | |
1407 | This is a harmless activity; and indeed, we will often try to generate | |
1408 | error messages intentionally. Once you understand the jargon, error | |
1409 | messages can be informative. Instead of being called ``error'' | |
1410 | messages, they should be called ``help'' messages. They are like | |
ee7683eb | 1411 | signposts to a traveler in a strange country; deciphering them can be |
8cda6f8f GM |
1412 | hard, but once understood, they can point the way. |
1413 | ||
1414 | The error message is generated by a built-in GNU Emacs debugger. We | |
1415 | will `enter the debugger'. You get out of the debugger by typing @code{q}. | |
1416 | ||
1417 | What we will do is evaluate a list that is not quoted and does not | |
1418 | have a meaningful command as its first element. Here is a list almost | |
1419 | exactly the same as the one we just used, but without the single-quote | |
1420 | in front of it. Position the cursor right after it and type @kbd{C-x | |
1421 | C-e}: | |
1422 | ||
1423 | @smallexample | |
1424 | (this is an unquoted list) | |
1425 | @end smallexample | |
1426 | ||
8f4ea8e0 | 1427 | @ignore |
8cda6f8f GM |
1428 | @noindent |
1429 | What you see depends on which version of Emacs you are running. GNU | |
1430 | Emacs version 22 provides more information than version 20 and before. | |
1431 | First, the more recent result of generating an error; then the | |
1432 | earlier, version 20 result. | |
1433 | ||
1434 | @need 1250 | |
1435 | @noindent | |
1436 | In GNU Emacs version 22, a @file{*Backtrace*} window will open up and | |
1437 | you will see the following in it: | |
8f4ea8e0 GM |
1438 | @end ignore |
1439 | ||
1440 | A @file{*Backtrace*} window will open up and you should see the | |
1441 | following in it: | |
8cda6f8f GM |
1442 | |
1443 | @smallexample | |
1444 | @group | |
1445 | ---------- Buffer: *Backtrace* ---------- | |
1446 | Debugger entered--Lisp error: (void-function this) | |
1447 | (this is an unquoted list) | |
1448 | eval((this is an unquoted list)) | |
1449 | eval-last-sexp-1(nil) | |
1450 | eval-last-sexp(nil) | |
1451 | call-interactively(eval-last-sexp) | |
1452 | ---------- Buffer: *Backtrace* ---------- | |
1453 | @end group | |
1454 | @end smallexample | |
1455 | ||
1456 | @need 1200 | |
1457 | @noindent | |
1458 | Your cursor will be in this window (you may have to wait a few seconds | |
1459 | before it becomes visible). To quit the debugger and make the | |
1460 | debugger window go away, type: | |
1461 | ||
1462 | @smallexample | |
1463 | q | |
1464 | @end smallexample | |
1465 | ||
1466 | @noindent | |
1467 | Please type @kbd{q} right now, so you become confident that you can | |
1468 | get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter | |
1469 | it. | |
1470 | ||
1471 | @cindex @samp{function} defined | |
1472 | Based on what we already know, we can almost read this error message. | |
1473 | ||
1474 | You read the @file{*Backtrace*} buffer from the bottom up; it tells | |
1475 | you what Emacs did. When you typed @kbd{C-x C-e}, you made an | |
1476 | interactive call to the command @code{eval-last-sexp}. @code{eval} is | |
1477 | an abbreviation for `evaluate' and @code{sexp} is an abbreviation for | |
1478 | `symbolic expression'. The command means `evaluate last symbolic | |
1479 | expression', which is the expression just before your cursor. | |
1480 | ||
1481 | Each line above tells you what the Lisp interpreter evaluated next. | |
1482 | The most recent action is at the top. The buffer is called the | |
1483 | @file{*Backtrace*} buffer because it enables you to track Emacs | |
1484 | backwards. | |
1485 | ||
1486 | @need 800 | |
1487 | At the top of the @file{*Backtrace*} buffer, you see the line: | |
1488 | ||
1489 | @smallexample | |
1490 | Debugger entered--Lisp error: (void-function this) | |
1491 | @end smallexample | |
1492 | ||
1493 | @noindent | |
1494 | The Lisp interpreter tried to evaluate the first atom of the list, the | |
1495 | word @samp{this}. It is this action that generated the error message | |
1496 | @samp{void-function this}. | |
1497 | ||
1498 | The message contains the words @samp{void-function} and @samp{this}. | |
1499 | ||
1500 | @cindex @samp{function} defined | |
1501 | The word @samp{function} was mentioned once before. It is a very | |
1502 | important word. For our purposes, we can define it by saying that a | |
1503 | @dfn{function} is a set of instructions to the computer that tell the | |
1504 | computer to do something. | |
1505 | ||
1506 | Now we can begin to understand the error message: @samp{void-function | |
1507 | this}. The function (that is, the word @samp{this}) does not have a | |
1508 | definition of any set of instructions for the computer to carry out. | |
1509 | ||
1510 | The slightly odd word, @samp{void-function}, is designed to cover the | |
1511 | way Emacs Lisp is implemented, which is that when a symbol does not | |
1512 | have a function definition attached to it, the place that should | |
1513 | contain the instructions is `void'. | |
1514 | ||
1515 | On the other hand, since we were able to add 2 plus 2 successfully, by | |
1516 | evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must | |
1517 | have a set of instructions for the computer to obey and those | |
1518 | instructions must be to add the numbers that follow the @code{+}. | |
1519 | ||
8f4ea8e0 GM |
1520 | It is possible to prevent Emacs entering the debugger in cases like |
1521 | this. We do not explain how to do that here, but we will mention what | |
1522 | the result looks like, because you may encounter a similar situation | |
1523 | if there is a bug in some Emacs code that you are using. In such | |
1524 | cases, you will see only one line of error message; it will appear in | |
1525 | the echo area and look like this: | |
8cda6f8f GM |
1526 | |
1527 | @smallexample | |
1528 | Symbol's function definition is void:@: this | |
1529 | @end smallexample | |
1530 | ||
1531 | @noindent | |
8f4ea8e0 | 1532 | @ignore |
8cda6f8f | 1533 | (Also, your terminal may beep at you---some do, some don't; and others |
8f4ea8e0 GM |
1534 | blink. This is just a device to get your attention.) |
1535 | @end ignore | |
1536 | The message goes away as soon as you type a key, even just to | |
1537 | move the cursor. | |
8cda6f8f GM |
1538 | |
1539 | We know the meaning of the word @samp{Symbol}. It refers to the first | |
1540 | atom of the list, the word @samp{this}. The word @samp{function} | |
1541 | refers to the instructions that tell the computer what to do. | |
1542 | (Technically, the symbol tells the computer where to find the | |
1543 | instructions, but this is a complication we can ignore for the | |
1544 | moment.) | |
1545 | ||
1546 | The error message can be understood: @samp{Symbol's function | |
1547 | definition is void:@: this}. The symbol (that is, the word | |
1548 | @samp{this}) lacks instructions for the computer to carry out. | |
1549 | ||
d6adf7e7 | 1550 | @node Names & Definitions |
8cda6f8f GM |
1551 | @section Symbol Names and Function Definitions |
1552 | @cindex Symbol names | |
1553 | ||
1554 | We can articulate another characteristic of Lisp based on what we have | |
1555 | discussed so far---an important characteristic: a symbol, like | |
1556 | @code{+}, is not itself the set of instructions for the computer to | |
1557 | carry out. Instead, the symbol is used, perhaps temporarily, as a way | |
1558 | of locating the definition or set of instructions. What we see is the | |
1559 | name through which the instructions can be found. Names of people | |
1560 | work the same way. I can be referred to as @samp{Bob}; however, I am | |
1561 | not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the | |
1562 | consciousness consistently associated with a particular life-form. | |
1563 | The name is not me, but it can be used to refer to me. | |
1564 | ||
1565 | In Lisp, one set of instructions can be attached to several names. | |
1566 | For example, the computer instructions for adding numbers can be | |
1567 | linked to the symbol @code{plus} as well as to the symbol @code{+} | |
1568 | (and are in some dialects of Lisp). Among humans, I can be referred | |
1569 | to as @samp{Robert} as well as @samp{Bob} and by other words as well. | |
1570 | ||
1571 | On the other hand, a symbol can have only one function definition | |
1572 | attached to it at a time. Otherwise, the computer would be confused as | |
1573 | to which definition to use. If this were the case among people, only | |
1574 | one person in the world could be named @samp{Bob}. However, the function | |
1575 | definition to which the name refers can be changed readily. | |
1576 | (@xref{Install, , Install a Function Definition}.) | |
1577 | ||
1578 | Since Emacs Lisp is large, it is customary to name symbols in a way | |
1579 | that identifies the part of Emacs to which the function belongs. | |
1580 | Thus, all the names for functions that deal with Texinfo start with | |
1581 | @samp{texinfo-} and those for functions that deal with reading mail | |
1582 | start with @samp{rmail-}. | |
1583 | ||
d6adf7e7 | 1584 | @node Lisp Interpreter |
8cda6f8f GM |
1585 | @section The Lisp Interpreter |
1586 | @cindex Lisp interpreter, what it does | |
1587 | @cindex Interpreter, what it does | |
1588 | ||
1589 | Based on what we have seen, we can now start to figure out what the | |
1590 | Lisp interpreter does when we command it to evaluate a list. | |
1591 | First, it looks to see whether there is a quote before the list; if | |
1592 | there is, the interpreter just gives us the list. On the other | |
1593 | hand, if there is no quote, the interpreter looks at the first element | |
1594 | in the list and sees whether it has a function definition. If it does, | |
1595 | the interpreter carries out the instructions in the function definition. | |
1596 | Otherwise, the interpreter prints an error message. | |
1597 | ||
1598 | This is how Lisp works. Simple. There are added complications which we | |
1599 | will get to in a minute, but these are the fundamentals. Of course, to | |
1600 | write Lisp programs, you need to know how to write function definitions | |
1601 | and attach them to names, and how to do this without confusing either | |
1602 | yourself or the computer. | |
1603 | ||
1604 | @menu | |
1605 | * Complications:: Variables, Special forms, Lists within. | |
1606 | * Byte Compiling:: Specially processing code for speed. | |
1607 | @end menu | |
1608 | ||
8cda6f8f | 1609 | @ifnottex |
d6adf7e7 | 1610 | @node Complications |
8cda6f8f GM |
1611 | @unnumberedsubsec Complications |
1612 | @end ifnottex | |
1613 | ||
1614 | Now, for the first complication. In addition to lists, the Lisp | |
1615 | interpreter can evaluate a symbol that is not quoted and does not have | |
1616 | parentheses around it. The Lisp interpreter will attempt to determine | |
1617 | the symbol's value as a @dfn{variable}. This situation is described | |
1618 | in the section on variables. (@xref{Variables}.) | |
1619 | ||
1620 | @cindex Special form | |
2325c82f XF |
1621 | The second complication occurs because some functions are unusual and |
1622 | do not work in the usual manner. Those that don't are called | |
1623 | @dfn{special forms}. They are used for special jobs, like defining a | |
1624 | function, and there are not many of them. In the next few chapters, | |
1625 | you will be introduced to several of the more important special forms. | |
1626 | And there are also @dfn{macros}. Macro is a construct defined in | |
1627 | Lisp, which differs from a function in that it translates a Lisp | |
1628 | expression into another expression which is to be evaluated instead of | |
1629 | the original expression. (@xref{Lisp macro}.) | |
1630 | ||
8cda6f8f GM |
1631 | |
1632 | The third and final complication is this: if the function that the | |
1633 | Lisp interpreter is looking at is not a special form, and if it is part | |
1634 | of a list, the Lisp interpreter looks to see whether the list has a list | |
1635 | inside of it. If there is an inner list, the Lisp interpreter first | |
1636 | figures out what it should do with the inside list, and then it works on | |
1637 | the outside list. If there is yet another list embedded inside the | |
1638 | inner list, it works on that one first, and so on. It always works on | |
1639 | the innermost list first. The interpreter works on the innermost list | |
1640 | first, to evaluate the result of that list. The result may be | |
1641 | used by the enclosing expression. | |
1642 | ||
1643 | Otherwise, the interpreter works left to right, from one expression to | |
1644 | the next. | |
1645 | ||
d6adf7e7 | 1646 | @node Byte Compiling |
8cda6f8f GM |
1647 | @subsection Byte Compiling |
1648 | @cindex Byte compiling | |
1649 | ||
1650 | One other aspect of interpreting: the Lisp interpreter is able to | |
1651 | interpret two kinds of entity: humanly readable code, on which we will | |
1652 | focus exclusively, and specially processed code, called @dfn{byte | |
1653 | compiled} code, which is not humanly readable. Byte compiled code | |
1654 | runs faster than humanly readable code. | |
1655 | ||
1656 | You can transform humanly readable code into byte compiled code by | |
1657 | running one of the compile commands such as @code{byte-compile-file}. | |
1658 | Byte compiled code is usually stored in a file that ends with a | |
1659 | @file{.elc} extension rather than a @file{.el} extension. You will | |
1660 | see both kinds of file in the @file{emacs/lisp} directory; the files | |
1661 | to read are those with @file{.el} extensions. | |
1662 | ||
1663 | As a practical matter, for most things you might do to customize or | |
1664 | extend Emacs, you do not need to byte compile; and I will not discuss | |
1665 | the topic here. @xref{Byte Compilation, , Byte Compilation, elisp, | |
1666 | The GNU Emacs Lisp Reference Manual}, for a full description of byte | |
1667 | compilation. | |
1668 | ||
d6adf7e7 | 1669 | @node Evaluation |
8cda6f8f GM |
1670 | @section Evaluation |
1671 | @cindex Evaluation | |
1672 | ||
1673 | When the Lisp interpreter works on an expression, the term for the | |
1674 | activity is called @dfn{evaluation}. We say that the interpreter | |
1675 | `evaluates the expression'. I've used this term several times before. | |
1676 | The word comes from its use in everyday language, `to ascertain the | |
1677 | value or amount of; to appraise', according to @cite{Webster's New | |
1678 | Collegiate Dictionary}. | |
1679 | ||
1680 | @menu | |
1681 | * How the Interpreter Acts:: Returns and Side Effects... | |
1682 | * Evaluating Inner Lists:: Lists within lists... | |
1683 | @end menu | |
1684 | ||
8cda6f8f | 1685 | @ifnottex |
d6adf7e7 | 1686 | @node How the Interpreter Acts |
8cda6f8f GM |
1687 | @unnumberedsubsec How the Lisp Interpreter Acts |
1688 | @end ifnottex | |
1689 | ||
1690 | @cindex @samp{returned value} explained | |
1691 | After evaluating an expression, the Lisp interpreter will most likely | |
1692 | @dfn{return} the value that the computer produces by carrying out the | |
1693 | instructions it found in the function definition, or perhaps it will | |
1694 | give up on that function and produce an error message. (The interpreter | |
1695 | may also find itself tossed, so to speak, to a different function or it | |
1696 | may attempt to repeat continually what it is doing for ever and ever in | |
1697 | what is called an `infinite loop'. These actions are less common; and | |
1698 | we can ignore them.) Most frequently, the interpreter returns a value. | |
1699 | ||
1700 | @cindex @samp{side effect} defined | |
1701 | At the same time the interpreter returns a value, it may do something | |
1702 | else as well, such as move a cursor or copy a file; this other kind of | |
1703 | action is called a @dfn{side effect}. Actions that we humans think are | |
1704 | important, such as printing results, are often ``side effects'' to the | |
1705 | Lisp interpreter. The jargon can sound peculiar, but it turns out that | |
1706 | it is fairly easy to learn to use side effects. | |
1707 | ||
1708 | In summary, evaluating a symbolic expression most commonly causes the | |
1709 | Lisp interpreter to return a value and perhaps carry out a side effect; | |
1710 | or else produce an error. | |
1711 | ||
d6adf7e7 | 1712 | @node Evaluating Inner Lists |
8cda6f8f GM |
1713 | @subsection Evaluating Inner Lists |
1714 | @cindex Inner list evaluation | |
1715 | @cindex Evaluating inner lists | |
1716 | ||
1717 | If evaluation applies to a list that is inside another list, the outer | |
1718 | list may use the value returned by the first evaluation as information | |
1719 | when the outer list is evaluated. This explains why inner expressions | |
1720 | are evaluated first: the values they return are used by the outer | |
1721 | expressions. | |
1722 | ||
1723 | @need 1250 | |
1724 | We can investigate this process by evaluating another addition example. | |
1725 | Place your cursor after the following expression and type @kbd{C-x C-e}: | |
1726 | ||
1727 | @smallexample | |
1728 | (+ 2 (+ 3 3)) | |
1729 | @end smallexample | |
1730 | ||
1731 | @noindent | |
1732 | The number 8 will appear in the echo area. | |
1733 | ||
1734 | What happens is that the Lisp interpreter first evaluates the inner | |
1735 | expression, @code{(+ 3 3)}, for which the value 6 is returned; then it | |
1736 | evaluates the outer expression as if it were written @code{(+ 2 6)}, which | |
1737 | returns the value 8. Since there are no more enclosing expressions to | |
1738 | evaluate, the interpreter prints that value in the echo area. | |
1739 | ||
1740 | Now it is easy to understand the name of the command invoked by the | |
1741 | keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The | |
1742 | letters @code{sexp} are an abbreviation for `symbolic expression', and | |
1743 | @code{eval} is an abbreviation for `evaluate'. The command means | |
1744 | `evaluate last symbolic expression'. | |
1745 | ||
1746 | As an experiment, you can try evaluating the expression by putting the | |
1747 | cursor at the beginning of the next line immediately following the | |
1748 | expression, or inside the expression. | |
1749 | ||
1750 | @need 800 | |
1751 | Here is another copy of the expression: | |
1752 | ||
1753 | @smallexample | |
1754 | (+ 2 (+ 3 3)) | |
1755 | @end smallexample | |
1756 | ||
1757 | @noindent | |
1758 | If you place the cursor at the beginning of the blank line that | |
1759 | immediately follows the expression and type @kbd{C-x C-e}, you will | |
1760 | still get the value 8 printed in the echo area. Now try putting the | |
1761 | cursor inside the expression. If you put it right after the next to | |
1762 | last parenthesis (so it appears to sit on top of the last parenthesis), | |
1763 | you will get a 6 printed in the echo area! This is because the command | |
1764 | evaluates the expression @code{(+ 3 3)}. | |
1765 | ||
1766 | Now put the cursor immediately after a number. Type @kbd{C-x C-e} and | |
1767 | you will get the number itself. In Lisp, if you evaluate a number, you | |
1768 | get the number itself---this is how numbers differ from symbols. If you | |
1769 | evaluate a list starting with a symbol like @code{+}, you will get a | |
1770 | value returned that is the result of the computer carrying out the | |
1771 | instructions in the function definition attached to that name. If a | |
1772 | symbol by itself is evaluated, something different happens, as we will | |
1773 | see in the next section. | |
1774 | ||
d6adf7e7 | 1775 | @node Variables |
8cda6f8f GM |
1776 | @section Variables |
1777 | @cindex Variables | |
1778 | ||
1779 | In Emacs Lisp, a symbol can have a value attached to it just as it can | |
1780 | have a function definition attached to it. The two are different. | |
1781 | The function definition is a set of instructions that a computer will | |
1782 | obey. A value, on the other hand, is something, such as number or a | |
1783 | name, that can vary (which is why such a symbol is called a variable). | |
1784 | The value of a symbol can be any expression in Lisp, such as a symbol, | |
1785 | number, list, or string. A symbol that has a value is often called a | |
1786 | @dfn{variable}. | |
1787 | ||
1788 | A symbol can have both a function definition and a value attached to | |
1789 | it at the same time. Or it can have just one or the other. | |
1790 | The two are separate. This is somewhat similar | |
1791 | to the way the name Cambridge can refer to the city in Massachusetts | |
1792 | and have some information attached to the name as well, such as | |
1793 | ``great programming center''. | |
1794 | ||
1795 | @ignore | |
1796 | (Incidentally, in Emacs Lisp, a symbol can have two | |
1797 | other things attached to it, too: a property list and a documentation | |
1798 | string; these are discussed later.) | |
1799 | @end ignore | |
1800 | ||
1801 | Another way to think about this is to imagine a symbol as being a chest | |
1802 | of drawers. The function definition is put in one drawer, the value in | |
1803 | another, and so on. What is put in the drawer holding the value can be | |
1804 | changed without affecting the contents of the drawer holding the | |
1805 | function definition, and vice-verse. | |
1806 | ||
1807 | @menu | |
1808 | * fill-column Example:: | |
1809 | * Void Function:: The error message for a symbol | |
1810 | without a function. | |
1811 | * Void Variable:: The error message for a symbol without a value. | |
1812 | @end menu | |
1813 | ||
8cda6f8f | 1814 | @ifnottex |
d6adf7e7 | 1815 | @node fill-column Example |
8cda6f8f GM |
1816 | @unnumberedsubsec @code{fill-column}, an Example Variable |
1817 | @end ifnottex | |
1818 | ||
1819 | @findex fill-column, @r{an example variable} | |
1820 | @cindex Example variable, @code{fill-column} | |
1821 | @cindex Variable, example of, @code{fill-column} | |
1822 | The variable @code{fill-column} illustrates a symbol with a value | |
1823 | attached to it: in every GNU Emacs buffer, this symbol is set to some | |
1824 | value, usually 72 or 70, but sometimes to some other value. To find the | |
1825 | value of this symbol, evaluate it by itself. If you are reading this in | |
1826 | Info inside of GNU Emacs, you can do this by putting the cursor after | |
1827 | the symbol and typing @kbd{C-x C-e}: | |
1828 | ||
1829 | @smallexample | |
1830 | fill-column | |
1831 | @end smallexample | |
1832 | ||
1833 | @noindent | |
1834 | After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo | |
1835 | area. This is the value for which @code{fill-column} is set for me as I | |
1836 | write this. It may be different for you in your Info buffer. Notice | |
1837 | that the value returned as a variable is printed in exactly the same way | |
1838 | as the value returned by a function carrying out its instructions. From | |
1839 | the point of view of the Lisp interpreter, a value returned is a value | |
1840 | returned. What kind of expression it came from ceases to matter once | |
1841 | the value is known. | |
1842 | ||
1843 | A symbol can have any value attached to it or, to use the jargon, we can | |
1844 | @dfn{bind} the variable to a value: to a number, such as 72; to a | |
1845 | string, @code{"such as this"}; to a list, such as @code{(spruce pine | |
1846 | oak)}; we can even bind a variable to a function definition. | |
1847 | ||
1848 | A symbol can be bound to a value in several ways. @xref{set & setq, , | |
1849 | Setting the Value of a Variable}, for information about one way to do | |
1850 | this. | |
1851 | ||
d6adf7e7 | 1852 | @node Void Function |
8cda6f8f GM |
1853 | @subsection Error Message for a Symbol Without a Function |
1854 | @cindex Symbol without function error | |
1855 | @cindex Error for symbol without function | |
1856 | ||
1857 | When we evaluated @code{fill-column} to find its value as a variable, | |
1858 | we did not place parentheses around the word. This is because we did | |
1859 | not intend to use it as a function name. | |
1860 | ||
1861 | If @code{fill-column} were the first or only element of a list, the | |
1862 | Lisp interpreter would attempt to find the function definition | |
1863 | attached to it. But @code{fill-column} has no function definition. | |
1864 | Try evaluating this: | |
1865 | ||
1866 | @smallexample | |
1867 | (fill-column) | |
1868 | @end smallexample | |
1869 | ||
1870 | @need 1250 | |
1871 | @noindent | |
8f4ea8e0 | 1872 | You will create a @file{*Backtrace*} buffer that says: |
8cda6f8f GM |
1873 | |
1874 | @smallexample | |
1875 | @group | |
1876 | ---------- Buffer: *Backtrace* ---------- | |
1877 | Debugger entered--Lisp error: (void-function fill-column) | |
1878 | (fill-column) | |
1879 | eval((fill-column)) | |
1880 | eval-last-sexp-1(nil) | |
1881 | eval-last-sexp(nil) | |
1882 | call-interactively(eval-last-sexp) | |
1883 | ---------- Buffer: *Backtrace* ---------- | |
1884 | @end group | |
1885 | @end smallexample | |
1886 | ||
1887 | @noindent | |
1888 | (Remember, to quit the debugger and make the debugger window go away, | |
1889 | type @kbd{q} in the @file{*Backtrace*} buffer.) | |
1890 | ||
1891 | @ignore | |
1892 | @need 800 | |
1893 | In GNU Emacs 20 and before, you will produce an error message that says: | |
1894 | ||
1895 | @smallexample | |
1896 | Symbol's function definition is void:@: fill-column | |
1897 | @end smallexample | |
1898 | ||
1899 | @noindent | |
1900 | (The message will go away as soon as you move the cursor or type | |
1901 | another key.) | |
1902 | @end ignore | |
1903 | ||
d6adf7e7 | 1904 | @node Void Variable |
8cda6f8f GM |
1905 | @subsection Error Message for a Symbol Without a Value |
1906 | @cindex Symbol without value error | |
1907 | @cindex Error for symbol without value | |
1908 | ||
1909 | If you attempt to evaluate a symbol that does not have a value bound to | |
1910 | it, you will receive an error message. You can see this by | |
1911 | experimenting with our 2 plus 2 addition. In the following expression, | |
1912 | put your cursor right after the @code{+}, before the first number 2, | |
1913 | type @kbd{C-x C-e}: | |
1914 | ||
1915 | @smallexample | |
1916 | (+ 2 2) | |
1917 | @end smallexample | |
1918 | ||
1919 | @need 1500 | |
1920 | @noindent | |
1921 | In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that | |
1922 | says: | |
1923 | ||
1924 | @smallexample | |
1925 | @group | |
1926 | ---------- Buffer: *Backtrace* ---------- | |
1927 | Debugger entered--Lisp error: (void-variable +) | |
1928 | eval(+) | |
1929 | eval-last-sexp-1(nil) | |
1930 | eval-last-sexp(nil) | |
1931 | call-interactively(eval-last-sexp) | |
1932 | ---------- Buffer: *Backtrace* ---------- | |
1933 | @end group | |
1934 | @end smallexample | |
1935 | ||
1936 | @noindent | |
8f4ea8e0 | 1937 | (Again, you can quit the debugger by |
8cda6f8f GM |
1938 | typing @kbd{q} in the @file{*Backtrace*} buffer.) |
1939 | ||
1940 | This backtrace is different from the very first error message we saw, | |
1941 | which said, @samp{Debugger entered--Lisp error: (void-function this)}. | |
1942 | In this case, the function does not have a value as a variable; while | |
1943 | in the other error message, the function (the word `this') did not | |
1944 | have a definition. | |
1945 | ||
1946 | In this experiment with the @code{+}, what we did was cause the Lisp | |
1947 | interpreter to evaluate the @code{+} and look for the value of the | |
1948 | variable instead of the function definition. We did this by placing the | |
1949 | cursor right after the symbol rather than after the parenthesis of the | |
1950 | enclosing list as we did before. As a consequence, the Lisp interpreter | |
8f4ea8e0 | 1951 | evaluated the preceding s-expression, which in this case was |
8cda6f8f GM |
1952 | @code{+} by itself. |
1953 | ||
1954 | Since @code{+} does not have a value bound to it, just the function | |
1955 | definition, the error message reported that the symbol's value as a | |
1956 | variable was void. | |
1957 | ||
1958 | @ignore | |
1959 | @need 800 | |
1960 | In GNU Emacs version 20 and before, your error message will say: | |
1961 | ||
1962 | @example | |
1963 | Symbol's value as variable is void:@: + | |
1964 | @end example | |
1965 | ||
1966 | @noindent | |
1967 | The meaning is the same as in GNU Emacs 22. | |
1968 | @end ignore | |
1969 | ||
d6adf7e7 | 1970 | @node Arguments |
8cda6f8f GM |
1971 | @section Arguments |
1972 | @cindex Arguments | |
1973 | @cindex Passing information to functions | |
1974 | ||
1975 | To see how information is passed to functions, let's look again at | |
1976 | our old standby, the addition of two plus two. In Lisp, this is written | |
1977 | as follows: | |
1978 | ||
1979 | @smallexample | |
1980 | (+ 2 2) | |
1981 | @end smallexample | |
1982 | ||
1983 | If you evaluate this expression, the number 4 will appear in your echo | |
1984 | area. What the Lisp interpreter does is add the numbers that follow | |
1985 | the @code{+}. | |
1986 | ||
1987 | @cindex @samp{argument} defined | |
1988 | The numbers added by @code{+} are called the @dfn{arguments} of the | |
1989 | function @code{+}. These numbers are the information that is given to | |
1990 | or @dfn{passed} to the function. | |
1991 | ||
1992 | The word `argument' comes from the way it is used in mathematics and | |
1993 | does not refer to a disputation between two people; instead it refers to | |
1994 | the information presented to the function, in this case, to the | |
1995 | @code{+}. In Lisp, the arguments to a function are the atoms or lists | |
1996 | that follow the function. The values returned by the evaluation of | |
1997 | these atoms or lists are passed to the function. Different functions | |
1998 | require different numbers of arguments; some functions require none at | |
1999 | all.@footnote{It is curious to track the path by which the word `argument' | |
2000 | came to have two different meanings, one in mathematics and the other in | |
2001 | everyday English. According to the @cite{Oxford English Dictionary}, | |
2002 | the word derives from the Latin for @samp{to make clear, prove}; thus it | |
2003 | came to mean, by one thread of derivation, `the evidence offered as | |
2004 | proof', which is to say, `the information offered', which led to its | |
2005 | meaning in Lisp. But in the other thread of derivation, it came to mean | |
2006 | `to assert in a manner against which others may make counter | |
2007 | assertions', which led to the meaning of the word as a disputation. | |
2008 | (Note here that the English word has two different definitions attached | |
2009 | to it at the same time. By contrast, in Emacs Lisp, a symbol cannot | |
2010 | have two different function definitions at the same time.)} | |
2011 | ||
2012 | @menu | |
2013 | * Data types:: Types of data passed to a function. | |
2014 | * Args as Variable or List:: An argument can be the value | |
2015 | of a variable or list. | |
2016 | * Variable Number of Arguments:: Some functions may take a | |
2017 | variable number of arguments. | |
2018 | * Wrong Type of Argument:: Passing an argument of the wrong type | |
2019 | to a function. | |
2020 | * message:: A useful function for sending messages. | |
2021 | @end menu | |
2022 | ||
d6adf7e7 | 2023 | @node Data types |
8cda6f8f GM |
2024 | @subsection Arguments' Data Types |
2025 | @cindex Data types | |
2026 | @cindex Types of data | |
2027 | @cindex Arguments' data types | |
2028 | ||
2029 | The type of data that should be passed to a function depends on what | |
2030 | kind of information it uses. The arguments to a function such as | |
2031 | @code{+} must have values that are numbers, since @code{+} adds numbers. | |
2032 | Other functions use different kinds of data for their arguments. | |
2033 | ||
2034 | @need 1250 | |
2035 | @findex concat | |
2036 | For example, the @code{concat} function links together or unites two or | |
2037 | more strings of text to produce a string. The arguments are strings. | |
2038 | Concatenating the two character strings @code{abc}, @code{def} produces | |
2039 | the single string @code{abcdef}. This can be seen by evaluating the | |
2040 | following: | |
2041 | ||
2042 | @smallexample | |
2043 | (concat "abc" "def") | |
2044 | @end smallexample | |
2045 | ||
2046 | @noindent | |
2047 | The value produced by evaluating this expression is @code{"abcdef"}. | |
2048 | ||
2049 | A function such as @code{substring} uses both a string and numbers as | |
2050 | arguments. The function returns a part of the string, a substring of | |
2051 | the first argument. This function takes three arguments. Its first | |
2052 | argument is the string of characters, the second and third arguments are | |
2053 | numbers that indicate the beginning and end of the substring. The | |
2054 | numbers are a count of the number of characters (including spaces and | |
e4920bc9 | 2055 | punctuation) from the beginning of the string. |
8cda6f8f GM |
2056 | |
2057 | @need 800 | |
2058 | For example, if you evaluate the following: | |
2059 | ||
2060 | @smallexample | |
2061 | (substring "The quick brown fox jumped." 16 19) | |
2062 | @end smallexample | |
2063 | ||
2064 | @noindent | |
2065 | you will see @code{"fox"} appear in the echo area. The arguments are the | |
2066 | string and the two numbers. | |
2067 | ||
2068 | Note that the string passed to @code{substring} is a single atom even | |
2069 | though it is made up of several words separated by spaces. Lisp counts | |
2070 | everything between the two quotation marks as part of the string, | |
2071 | including the spaces. You can think of the @code{substring} function as | |
2072 | a kind of `atom smasher' since it takes an otherwise indivisible atom | |
2073 | and extracts a part. However, @code{substring} is only able to extract | |
2074 | a substring from an argument that is a string, not from another type of | |
2075 | atom such as a number or symbol. | |
2076 | ||
d6adf7e7 | 2077 | @node Args as Variable or List |
8cda6f8f GM |
2078 | @subsection An Argument as the Value of a Variable or List |
2079 | ||
2080 | An argument can be a symbol that returns a value when it is evaluated. | |
2081 | For example, when the symbol @code{fill-column} by itself is evaluated, | |
2082 | it returns a number. This number can be used in an addition. | |
2083 | ||
2084 | @need 1250 | |
2085 | Position the cursor after the following expression and type @kbd{C-x | |
2086 | C-e}: | |
2087 | ||
2088 | @smallexample | |
2089 | (+ 2 fill-column) | |
2090 | @end smallexample | |
2091 | ||
2092 | @noindent | |
2093 | The value will be a number two more than what you get by evaluating | |
2094 | @code{fill-column} alone. For me, this is 74, because my value of | |
2095 | @code{fill-column} is 72. | |
2096 | ||
2097 | As we have just seen, an argument can be a symbol that returns a value | |
2098 | when evaluated. In addition, an argument can be a list that returns a | |
2099 | value when it is evaluated. For example, in the following expression, | |
2100 | the arguments to the function @code{concat} are the strings | |
2101 | @w{@code{"The "}} and @w{@code{" red foxes."}} and the list | |
2102 | @code{(number-to-string (+ 2 fill-column))}. | |
2103 | ||
2104 | @c For GNU Emacs 22, need number-to-string | |
2105 | @smallexample | |
2106 | (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.") | |
2107 | @end smallexample | |
2108 | ||
2109 | @noindent | |
2110 | If you evaluate this expression---and if, as with my Emacs, | |
2111 | @code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will | |
2112 | appear in the echo area. (Note that you must put spaces after the | |
2113 | word @samp{The} and before the word @samp{red} so they will appear in | |
2114 | the final string. The function @code{number-to-string} converts the | |
2115 | integer that the addition function returns to a string. | |
2116 | @code{number-to-string} is also known as @code{int-to-string}.) | |
2117 | ||
d6adf7e7 | 2118 | @node Variable Number of Arguments |
8cda6f8f GM |
2119 | @subsection Variable Number of Arguments |
2120 | @cindex Variable number of arguments | |
2121 | @cindex Arguments, variable number of | |
2122 | ||
2123 | Some functions, such as @code{concat}, @code{+} or @code{*}, take any | |
2124 | number of arguments. (The @code{*} is the symbol for multiplication.) | |
2125 | This can be seen by evaluating each of the following expressions in | |
2126 | the usual way. What you will see in the echo area is printed in this | |
2127 | text after @samp{@result{}}, which you may read as `evaluates to'. | |
2128 | ||
2129 | @need 1250 | |
2130 | In the first set, the functions have no arguments: | |
2131 | ||
2132 | @smallexample | |
2133 | @group | |
2134 | (+) @result{} 0 | |
2135 | ||
2136 | (*) @result{} 1 | |
2137 | @end group | |
2138 | @end smallexample | |
2139 | ||
2140 | @need 1250 | |
2141 | In this set, the functions have one argument each: | |
2142 | ||
2143 | @smallexample | |
2144 | @group | |
2145 | (+ 3) @result{} 3 | |
2146 | ||
2147 | (* 3) @result{} 3 | |
2148 | @end group | |
2149 | @end smallexample | |
2150 | ||
2151 | @need 1250 | |
2152 | In this set, the functions have three arguments each: | |
2153 | ||
2154 | @smallexample | |
2155 | @group | |
2156 | (+ 3 4 5) @result{} 12 | |
2157 | ||
2158 | (* 3 4 5) @result{} 60 | |
2159 | @end group | |
2160 | @end smallexample | |
2161 | ||
d6adf7e7 | 2162 | @node Wrong Type of Argument |
8cda6f8f GM |
2163 | @subsection Using the Wrong Type Object as an Argument |
2164 | @cindex Wrong type of argument | |
2165 | @cindex Argument, wrong type of | |
2166 | ||
2167 | When a function is passed an argument of the wrong type, the Lisp | |
2168 | interpreter produces an error message. For example, the @code{+} | |
2169 | function expects the values of its arguments to be numbers. As an | |
2170 | experiment we can pass it the quoted symbol @code{hello} instead of a | |
2171 | number. Position the cursor after the following expression and type | |
2172 | @kbd{C-x C-e}: | |
2173 | ||
2174 | @smallexample | |
2175 | (+ 2 'hello) | |
2176 | @end smallexample | |
2177 | ||
2178 | @noindent | |
2179 | When you do this you will generate an error message. What has happened | |
2180 | is that @code{+} has tried to add the 2 to the value returned by | |
2181 | @code{'hello}, but the value returned by @code{'hello} is the symbol | |
2182 | @code{hello}, not a number. Only numbers can be added. So @code{+} | |
2183 | could not carry out its addition. | |
2184 | ||
2185 | @need 1250 | |
8f4ea8e0 | 2186 | You will create and enter a @file{*Backtrace*} buffer that says: |
8cda6f8f GM |
2187 | |
2188 | @noindent | |
2189 | @smallexample | |
2190 | @group | |
2191 | ---------- Buffer: *Backtrace* ---------- | |
2192 | Debugger entered--Lisp error: | |
2193 | (wrong-type-argument number-or-marker-p hello) | |
2194 | +(2 hello) | |
2195 | eval((+ 2 (quote hello))) | |
2196 | eval-last-sexp-1(nil) | |
2197 | eval-last-sexp(nil) | |
2198 | call-interactively(eval-last-sexp) | |
2199 | ---------- Buffer: *Backtrace* ---------- | |
2200 | @end group | |
2201 | @end smallexample | |
2202 | ||
2203 | @need 1250 | |
2204 | As usual, the error message tries to be helpful and makes sense after you | |
2205 | learn how to read it.@footnote{@code{(quote hello)} is an expansion of | |
2206 | the abbreviation @code{'hello}.} | |
2207 | ||
2208 | The first part of the error message is straightforward; it says | |
2209 | @samp{wrong type argument}. Next comes the mysterious jargon word | |
2210 | @w{@samp{number-or-marker-p}}. This word is trying to tell you what | |
2211 | kind of argument the @code{+} expected. | |
2212 | ||
2213 | The symbol @code{number-or-marker-p} says that the Lisp interpreter is | |
2214 | trying to determine whether the information presented it (the value of | |
2215 | the argument) is a number or a marker (a special object representing a | |
2216 | buffer position). What it does is test to see whether the @code{+} is | |
2217 | being given numbers to add. It also tests to see whether the | |
2218 | argument is something called a marker, which is a specific feature of | |
2219 | Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers. | |
2220 | When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command, | |
2221 | its position is kept as a marker. The mark can be considered a | |
2222 | number---the number of characters the location is from the beginning | |
2223 | of the buffer.) In Emacs Lisp, @code{+} can be used to add the | |
2224 | numeric value of marker positions as numbers. | |
2225 | ||
2226 | The @samp{p} of @code{number-or-marker-p} is the embodiment of a | |
2227 | practice started in the early days of Lisp programming. The @samp{p} | |
2228 | stands for `predicate'. In the jargon used by the early Lisp | |
2229 | researchers, a predicate refers to a function to determine whether some | |
2230 | property is true or false. So the @samp{p} tells us that | |
2231 | @code{number-or-marker-p} is the name of a function that determines | |
2232 | whether it is true or false that the argument supplied is a number or | |
2233 | a marker. Other Lisp symbols that end in @samp{p} include @code{zerop}, | |
2234 | a function that tests whether its argument has the value of zero, and | |
2235 | @code{listp}, a function that tests whether its argument is a list. | |
2236 | ||
2237 | Finally, the last part of the error message is the symbol @code{hello}. | |
2238 | This is the value of the argument that was passed to @code{+}. If the | |
2239 | addition had been passed the correct type of object, the value passed | |
2240 | would have been a number, such as 37, rather than a symbol like | |
2241 | @code{hello}. But then you would not have got the error message. | |
2242 | ||
2243 | @ignore | |
2244 | @need 1250 | |
2245 | In GNU Emacs version 20 and before, the echo area displays an error | |
2246 | message that says: | |
2247 | ||
2248 | @smallexample | |
2249 | Wrong type argument:@: number-or-marker-p, hello | |
2250 | @end smallexample | |
2251 | ||
2252 | This says, in different words, the same as the top line of the | |
2253 | @file{*Backtrace*} buffer. | |
2254 | @end ignore | |
2255 | ||
d6adf7e7 | 2256 | @node message |
8cda6f8f GM |
2257 | @subsection The @code{message} Function |
2258 | @findex message | |
2259 | ||
2260 | Like @code{+}, the @code{message} function takes a variable number of | |
2261 | arguments. It is used to send messages to the user and is so useful | |
2262 | that we will describe it here. | |
2263 | ||
2264 | @need 1250 | |
2265 | A message is printed in the echo area. For example, you can print a | |
2266 | message in your echo area by evaluating the following list: | |
2267 | ||
2268 | @smallexample | |
2269 | (message "This message appears in the echo area!") | |
2270 | @end smallexample | |
2271 | ||
2272 | The whole string between double quotation marks is a single argument | |
2273 | and is printed @i{in toto}. (Note that in this example, the message | |
2274 | itself will appear in the echo area within double quotes; that is | |
2275 | because you see the value returned by the @code{message} function. In | |
2276 | most uses of @code{message} in programs that you write, the text will | |
2277 | be printed in the echo area as a side-effect, without the quotes. | |
2278 | @xref{multiply-by-seven in detail, , @code{multiply-by-seven} in | |
2279 | detail}, for an example of this.) | |
2280 | ||
2281 | However, if there is a @samp{%s} in the quoted string of characters, the | |
2282 | @code{message} function does not print the @samp{%s} as such, but looks | |
2283 | to the argument that follows the string. It evaluates the second | |
2284 | argument and prints the value at the location in the string where the | |
2285 | @samp{%s} is. | |
2286 | ||
2287 | @need 1250 | |
2288 | You can see this by positioning the cursor after the following | |
2289 | expression and typing @kbd{C-x C-e}: | |
2290 | ||
2291 | @smallexample | |
2292 | (message "The name of this buffer is: %s." (buffer-name)) | |
2293 | @end smallexample | |
2294 | ||
2295 | @noindent | |
2296 | In Info, @code{"The name of this buffer is: *info*."} will appear in the | |
2297 | echo area. The function @code{buffer-name} returns the name of the | |
2298 | buffer as a string, which the @code{message} function inserts in place | |
2299 | of @code{%s}. | |
2300 | ||
2301 | To print a value as an integer, use @samp{%d} in the same way as | |
2302 | @samp{%s}. For example, to print a message in the echo area that | |
2303 | states the value of the @code{fill-column}, evaluate the following: | |
2304 | ||
2305 | @smallexample | |
2306 | (message "The value of fill-column is %d." fill-column) | |
2307 | @end smallexample | |
2308 | ||
2309 | @noindent | |
2310 | On my system, when I evaluate this list, @code{"The value of | |
2311 | fill-column is 72."} appears in my echo area@footnote{Actually, you | |
2312 | can use @code{%s} to print a number. It is non-specific. @code{%d} | |
2313 | prints only the part of a number left of a decimal point, and not | |
2314 | anything that is not a number.}. | |
2315 | ||
2316 | If there is more than one @samp{%s} in the quoted string, the value of | |
2317 | the first argument following the quoted string is printed at the | |
2318 | location of the first @samp{%s} and the value of the second argument is | |
2319 | printed at the location of the second @samp{%s}, and so on. | |
2320 | ||
2321 | @need 1250 | |
2322 | For example, if you evaluate the following, | |
2323 | ||
2324 | @smallexample | |
2325 | @group | |
2326 | (message "There are %d %s in the office!" | |
2327 | (- fill-column 14) "pink elephants") | |
2328 | @end group | |
2329 | @end smallexample | |
2330 | ||
2331 | @noindent | |
2332 | a rather whimsical message will appear in your echo area. On my system | |
2333 | it says, @code{"There are 58 pink elephants in the office!"}. | |
2334 | ||
2335 | The expression @code{(- fill-column 14)} is evaluated and the resulting | |
2336 | number is inserted in place of the @samp{%d}; and the string in double | |
2337 | quotes, @code{"pink elephants"}, is treated as a single argument and | |
2338 | inserted in place of the @samp{%s}. (That is to say, a string between | |
2339 | double quotes evaluates to itself, like a number.) | |
2340 | ||
2341 | Finally, here is a somewhat complex example that not only illustrates | |
2342 | the computation of a number, but also shows how you can use an | |
2343 | expression within an expression to generate the text that is substituted | |
2344 | for @samp{%s}: | |
2345 | ||
2346 | @smallexample | |
2347 | @group | |
2348 | (message "He saw %d %s" | |
2349 | (- fill-column 32) | |
2350 | (concat "red " | |
2351 | (substring | |
2352 | "The quick brown foxes jumped." 16 21) | |
2353 | " leaping.")) | |
2354 | @end group | |
2355 | @end smallexample | |
2356 | ||
2357 | In this example, @code{message} has three arguments: the string, | |
2358 | @code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and | |
2359 | the expression beginning with the function @code{concat}. The value | |
2360 | resulting from the evaluation of @code{(- fill-column 32)} is inserted | |
2361 | in place of the @samp{%d}; and the value returned by the expression | |
2362 | beginning with @code{concat} is inserted in place of the @samp{%s}. | |
2363 | ||
2364 | When your fill column is 70 and you evaluate the expression, the | |
2365 | message @code{"He saw 38 red foxes leaping."} appears in your echo | |
2366 | area. | |
2367 | ||
d6adf7e7 | 2368 | @node set & setq |
8cda6f8f GM |
2369 | @section Setting the Value of a Variable |
2370 | @cindex Variable, setting value | |
2371 | @cindex Setting value of variable | |
2372 | ||
2373 | @cindex @samp{bind} defined | |
2374 | There are several ways by which a variable can be given a value. One of | |
2375 | the ways is to use either the function @code{set} or the function | |
2376 | @code{setq}. Another way is to use @code{let} (@pxref{let}). (The | |
2377 | jargon for this process is to @dfn{bind} a variable to a value.) | |
2378 | ||
2379 | The following sections not only describe how @code{set} and @code{setq} | |
2380 | work but also illustrate how arguments are passed. | |
2381 | ||
2382 | @menu | |
2383 | * Using set:: Setting values. | |
2384 | * Using setq:: Setting a quoted value. | |
2385 | * Counting:: Using @code{setq} to count. | |
2386 | @end menu | |
2387 | ||
d6adf7e7 | 2388 | @node Using set |
8cda6f8f GM |
2389 | @subsection Using @code{set} |
2390 | @findex set | |
2391 | ||
2392 | To set the value of the symbol @code{flowers} to the list @code{'(rose | |
2393 | violet daisy buttercup)}, evaluate the following expression by | |
2394 | positioning the cursor after the expression and typing @kbd{C-x C-e}. | |
2395 | ||
2396 | @smallexample | |
2397 | (set 'flowers '(rose violet daisy buttercup)) | |
2398 | @end smallexample | |
2399 | ||
2400 | @noindent | |
2401 | The list @code{(rose violet daisy buttercup)} will appear in the echo | |
2402 | area. This is what is @emph{returned} by the @code{set} function. As a | |
2403 | side effect, the symbol @code{flowers} is bound to the list; that is, | |
2404 | the symbol @code{flowers}, which can be viewed as a variable, is given | |
2405 | the list as its value. (This process, by the way, illustrates how a | |
2406 | side effect to the Lisp interpreter, setting the value, can be the | |
2407 | primary effect that we humans are interested in. This is because every | |
2408 | Lisp function must return a value if it does not get an error, but it | |
2409 | will only have a side effect if it is designed to have one.) | |
2410 | ||
2411 | After evaluating the @code{set} expression, you can evaluate the symbol | |
2412 | @code{flowers} and it will return the value you just set. Here is the | |
2413 | symbol. Place your cursor after it and type @kbd{C-x C-e}. | |
2414 | ||
2415 | @smallexample | |
2416 | flowers | |
2417 | @end smallexample | |
2418 | ||
2419 | @noindent | |
2420 | When you evaluate @code{flowers}, the list | |
2421 | @code{(rose violet daisy buttercup)} appears in the echo area. | |
2422 | ||
2423 | Incidentally, if you evaluate @code{'flowers}, the variable with a quote | |
2424 | in front of it, what you will see in the echo area is the symbol itself, | |
2425 | @code{flowers}. Here is the quoted symbol, so you can try this: | |
2426 | ||
2427 | @smallexample | |
2428 | 'flowers | |
2429 | @end smallexample | |
2430 | ||
2431 | Note also, that when you use @code{set}, you need to quote both | |
2432 | arguments to @code{set}, unless you want them evaluated. Since we do | |
2433 | not want either argument evaluated, neither the variable | |
2434 | @code{flowers} nor the list @code{(rose violet daisy buttercup)}, both | |
2435 | are quoted. (When you use @code{set} without quoting its first | |
2436 | argument, the first argument is evaluated before anything else is | |
2437 | done. If you did this and @code{flowers} did not have a value | |
2438 | already, you would get an error message that the @samp{Symbol's value | |
2439 | as variable is void}; on the other hand, if @code{flowers} did return | |
2440 | a value after it was evaluated, the @code{set} would attempt to set | |
2441 | the value that was returned. There are situations where this is the | |
2442 | right thing for the function to do; but such situations are rare.) | |
2443 | ||
d6adf7e7 | 2444 | @node Using setq |
8cda6f8f GM |
2445 | @subsection Using @code{setq} |
2446 | @findex setq | |
2447 | ||
2448 | As a practical matter, you almost always quote the first argument to | |
2449 | @code{set}. The combination of @code{set} and a quoted first argument | |
2450 | is so common that it has its own name: the special form @code{setq}. | |
2451 | This special form is just like @code{set} except that the first argument | |
2452 | is quoted automatically, so you don't need to type the quote mark | |
2453 | yourself. Also, as an added convenience, @code{setq} permits you to set | |
2454 | several different variables to different values, all in one expression. | |
2455 | ||
2456 | To set the value of the variable @code{carnivores} to the list | |
2457 | @code{'(lion tiger leopard)} using @code{setq}, the following expression | |
2458 | is used: | |
2459 | ||
2460 | @smallexample | |
2461 | (setq carnivores '(lion tiger leopard)) | |
2462 | @end smallexample | |
2463 | ||
2464 | @noindent | |
2465 | This is exactly the same as using @code{set} except the first argument | |
2466 | is automatically quoted by @code{setq}. (The @samp{q} in @code{setq} | |
2467 | means @code{quote}.) | |
2468 | ||
2469 | @need 1250 | |
2470 | With @code{set}, the expression would look like this: | |
2471 | ||
2472 | @smallexample | |
2473 | (set 'carnivores '(lion tiger leopard)) | |
2474 | @end smallexample | |
2475 | ||
2476 | Also, @code{setq} can be used to assign different values to | |
2477 | different variables. The first argument is bound to the value | |
2478 | of the second argument, the third argument is bound to the value of the | |
2479 | fourth argument, and so on. For example, you could use the following to | |
2480 | assign a list of trees to the symbol @code{trees} and a list of herbivores | |
2481 | to the symbol @code{herbivores}: | |
2482 | ||
2483 | @smallexample | |
2484 | @group | |
2485 | (setq trees '(pine fir oak maple) | |
2486 | herbivores '(gazelle antelope zebra)) | |
2487 | @end group | |
2488 | @end smallexample | |
2489 | ||
2490 | @noindent | |
2491 | (The expression could just as well have been on one line, but it might | |
2492 | not have fit on a page; and humans find it easier to read nicely | |
2493 | formatted lists.) | |
2494 | ||
2495 | Although I have been using the term `assign', there is another way of | |
2496 | thinking about the workings of @code{set} and @code{setq}; and that is to | |
2497 | say that @code{set} and @code{setq} make the symbol @emph{point} to the | |
2498 | list. This latter way of thinking is very common and in forthcoming | |
2499 | chapters we shall come upon at least one symbol that has `pointer' as | |
2500 | part of its name. The name is chosen because the symbol has a value, | |
2501 | specifically a list, attached to it; or, expressed another way, | |
2502 | the symbol is set to ``point'' to the list. | |
2503 | ||
d6adf7e7 | 2504 | @node Counting |
8cda6f8f GM |
2505 | @subsection Counting |
2506 | @cindex Counting | |
2507 | ||
2508 | Here is an example that shows how to use @code{setq} in a counter. You | |
2509 | might use this to count how many times a part of your program repeats | |
2510 | itself. First set a variable to zero; then add one to the number each | |
2511 | time the program repeats itself. To do this, you need a variable that | |
2512 | serves as a counter, and two expressions: an initial @code{setq} | |
2513 | expression that sets the counter variable to zero; and a second | |
2514 | @code{setq} expression that increments the counter each time it is | |
2515 | evaluated. | |
2516 | ||
2517 | @smallexample | |
2518 | @group | |
2519 | (setq counter 0) ; @r{Let's call this the initializer.} | |
2520 | ||
2521 | (setq counter (+ counter 1)) ; @r{This is the incrementer.} | |
2522 | ||
2523 | counter ; @r{This is the counter.} | |
2524 | @end group | |
2525 | @end smallexample | |
2526 | ||
2527 | @noindent | |
2528 | (The text following the @samp{;} are comments. @xref{Change a | |
2529 | defun, , Change a Function Definition}.) | |
2530 | ||
2531 | If you evaluate the first of these expressions, the initializer, | |
2532 | @code{(setq counter 0)}, and then evaluate the third expression, | |
2533 | @code{counter}, the number @code{0} will appear in the echo area. If | |
2534 | you then evaluate the second expression, the incrementer, @code{(setq | |
2535 | counter (+ counter 1))}, the counter will get the value 1. So if you | |
2536 | again evaluate @code{counter}, the number @code{1} will appear in the | |
2537 | echo area. Each time you evaluate the second expression, the value of | |
2538 | the counter will be incremented. | |
2539 | ||
2540 | When you evaluate the incrementer, @code{(setq counter (+ counter 1))}, | |
2541 | the Lisp interpreter first evaluates the innermost list; this is the | |
2542 | addition. In order to evaluate this list, it must evaluate the variable | |
2543 | @code{counter} and the number @code{1}. When it evaluates the variable | |
2544 | @code{counter}, it receives its current value. It passes this value and | |
2545 | the number @code{1} to the @code{+} which adds them together. The sum | |
2546 | is then returned as the value of the inner list and passed to the | |
2547 | @code{setq} which sets the variable @code{counter} to this new value. | |
2548 | Thus, the value of the variable, @code{counter}, is changed. | |
2549 | ||
d6adf7e7 | 2550 | @node Summary |
8cda6f8f GM |
2551 | @section Summary |
2552 | ||
2553 | Learning Lisp is like climbing a hill in which the first part is the | |
2554 | steepest. You have now climbed the most difficult part; what remains | |
2555 | becomes easier as you progress onwards. | |
2556 | ||
2557 | @need 1000 | |
2558 | In summary, | |
2559 | ||
2560 | @itemize @bullet | |
2561 | ||
2562 | @item | |
2563 | Lisp programs are made up of expressions, which are lists or single atoms. | |
2564 | ||
2565 | @item | |
2566 | Lists are made up of zero or more atoms or inner lists, separated by whitespace and | |
2567 | surrounded by parentheses. A list can be empty. | |
2568 | ||
2569 | @item | |
2570 | Atoms are multi-character symbols, like @code{forward-paragraph}, single | |
2571 | character symbols like @code{+}, strings of characters between double | |
2572 | quotation marks, or numbers. | |
2573 | ||
2574 | @item | |
2575 | A number evaluates to itself. | |
2576 | ||
2577 | @item | |
2578 | A string between double quotes also evaluates to itself. | |
2579 | ||
2580 | @item | |
2581 | When you evaluate a symbol by itself, its value is returned. | |
2582 | ||
2583 | @item | |
2584 | When you evaluate a list, the Lisp interpreter looks at the first symbol | |
2585 | in the list and then at the function definition bound to that symbol. | |
2586 | Then the instructions in the function definition are carried out. | |
2587 | ||
2588 | @item | |
2589 | A single quotation mark, | |
2590 | @ifinfo | |
2591 | ' | |
2592 | @end ifinfo | |
2593 | @ifnotinfo | |
2594 | @code{'} | |
2595 | @end ifnotinfo | |
2596 | , tells the Lisp interpreter that it should | |
2597 | return the following expression as written, and not evaluate it as it | |
2598 | would if the quote were not there. | |
2599 | ||
2600 | @item | |
2601 | Arguments are the information passed to a function. The arguments to a | |
2602 | function are computed by evaluating the rest of the elements of the list | |
2603 | of which the function is the first element. | |
2604 | ||
2605 | @item | |
2606 | A function always returns a value when it is evaluated (unless it gets | |
2607 | an error); in addition, it may also carry out some action called a | |
2608 | ``side effect''. In many cases, a function's primary purpose is to | |
2609 | create a side effect. | |
2610 | @end itemize | |
2611 | ||
d6adf7e7 | 2612 | @node Error Message Exercises |
8cda6f8f GM |
2613 | @section Exercises |
2614 | ||
2615 | A few simple exercises: | |
2616 | ||
2617 | @itemize @bullet | |
2618 | @item | |
2619 | Generate an error message by evaluating an appropriate symbol that is | |
2620 | not within parentheses. | |
2621 | ||
2622 | @item | |
2623 | Generate an error message by evaluating an appropriate symbol that is | |
2624 | between parentheses. | |
2625 | ||
2626 | @item | |
2627 | Create a counter that increments by two rather than one. | |
2628 | ||
2629 | @item | |
2630 | Write an expression that prints a message in the echo area when | |
2631 | evaluated. | |
2632 | @end itemize | |
2633 | ||
d6adf7e7 | 2634 | @node Practicing Evaluation |
8cda6f8f GM |
2635 | @chapter Practicing Evaluation |
2636 | @cindex Practicing evaluation | |
2637 | @cindex Evaluation practice | |
2638 | ||
2639 | Before learning how to write a function definition in Emacs Lisp, it is | |
2640 | useful to spend a little time evaluating various expressions that have | |
2641 | already been written. These expressions will be lists with the | |
2642 | functions as their first (and often only) element. Since some of the | |
2643 | functions associated with buffers are both simple and interesting, we | |
2644 | will start with those. In this section, we will evaluate a few of | |
2645 | these. In another section, we will study the code of several other | |
2646 | buffer-related functions, to see how they were written. | |
2647 | ||
2648 | @menu | |
2649 | * How to Evaluate:: Typing editing commands or @kbd{C-x C-e} | |
2650 | causes evaluation. | |
2651 | * Buffer Names:: Buffers and files are different. | |
2652 | * Getting Buffers:: Getting a buffer itself, not merely its name. | |
2653 | * Switching Buffers:: How to change to another buffer. | |
2654 | * Buffer Size & Locations:: Where point is located and the size of | |
2655 | the buffer. | |
2656 | * Evaluation Exercise:: | |
2657 | @end menu | |
2658 | ||
8cda6f8f | 2659 | @ifnottex |
d6adf7e7 | 2660 | @node How to Evaluate |
8cda6f8f GM |
2661 | @unnumberedsec How to Evaluate |
2662 | @end ifnottex | |
2663 | ||
2664 | @i{Whenever you give an editing command} to Emacs Lisp, such as the | |
2665 | command to move the cursor or to scroll the screen, @i{you are evaluating | |
2666 | an expression,} the first element of which is a function. @i{This is | |
2667 | how Emacs works.} | |
2668 | ||
2669 | @cindex @samp{interactive function} defined | |
2670 | @cindex @samp{command} defined | |
2671 | When you type keys, you cause the Lisp interpreter to evaluate an | |
2672 | expression and that is how you get your results. Even typing plain text | |
2673 | involves evaluating an Emacs Lisp function, in this case, one that uses | |
2674 | @code{self-insert-command}, which simply inserts the character you | |
2675 | typed. The functions you evaluate by typing keystrokes are called | |
2676 | @dfn{interactive} functions, or @dfn{commands}; how you make a function | |
2677 | interactive will be illustrated in the chapter on how to write function | |
2678 | definitions. @xref{Interactive, , Making a Function Interactive}. | |
2679 | ||
2680 | In addition to typing keyboard commands, we have seen a second way to | |
2681 | evaluate an expression: by positioning the cursor after a list and | |
2682 | typing @kbd{C-x C-e}. This is what we will do in the rest of this | |
2683 | section. There are other ways to evaluate an expression as well; these | |
2684 | will be described as we come to them. | |
2685 | ||
2686 | Besides being used for practicing evaluation, the functions shown in the | |
2687 | next few sections are important in their own right. A study of these | |
2688 | functions makes clear the distinction between buffers and files, how to | |
2689 | switch to a buffer, and how to determine a location within it. | |
2690 | ||
d6adf7e7 | 2691 | @node Buffer Names |
8cda6f8f GM |
2692 | @section Buffer Names |
2693 | @findex buffer-name | |
2694 | @findex buffer-file-name | |
2695 | ||
2696 | The two functions, @code{buffer-name} and @code{buffer-file-name}, show | |
2697 | the difference between a file and a buffer. When you evaluate the | |
2698 | following expression, @code{(buffer-name)}, the name of the buffer | |
2699 | appears in the echo area. When you evaluate @code{(buffer-file-name)}, | |
2700 | the name of the file to which the buffer refers appears in the echo | |
2701 | area. Usually, the name returned by @code{(buffer-name)} is the same as | |
2702 | the name of the file to which it refers, and the name returned by | |
2703 | @code{(buffer-file-name)} is the full path-name of the file. | |
2704 | ||
2705 | A file and a buffer are two different entities. A file is information | |
2706 | recorded permanently in the computer (unless you delete it). A buffer, | |
2707 | on the other hand, is information inside of Emacs that will vanish at | |
2708 | the end of the editing session (or when you kill the buffer). Usually, | |
2709 | a buffer contains information that you have copied from a file; we say | |
2710 | the buffer is @dfn{visiting} that file. This copy is what you work on | |
2711 | and modify. Changes to the buffer do not change the file, until you | |
2712 | save the buffer. When you save the buffer, the buffer is copied to the file | |
2713 | and is thus saved permanently. | |
2714 | ||
2715 | @need 1250 | |
2716 | If you are reading this in Info inside of GNU Emacs, you can evaluate | |
2717 | each of the following expressions by positioning the cursor after it and | |
2718 | typing @kbd{C-x C-e}. | |
2719 | ||
2720 | @example | |
2721 | @group | |
2722 | (buffer-name) | |
2723 | ||
2724 | (buffer-file-name) | |
2725 | @end group | |
2726 | @end example | |
2727 | ||
2728 | @noindent | |
2729 | When I do this in Info, the value returned by evaluating | |
2730 | @code{(buffer-name)} is @file{"*info*"}, and the value returned by | |
2731 | evaluating @code{(buffer-file-name)} is @file{nil}. | |
2732 | ||
a9097c6d | 2733 | On the other hand, while I am writing this document, the value |
8cda6f8f GM |
2734 | returned by evaluating @code{(buffer-name)} is |
2735 | @file{"introduction.texinfo"}, and the value returned by evaluating | |
2736 | @code{(buffer-file-name)} is | |
2737 | @file{"/gnu/work/intro/introduction.texinfo"}. | |
2738 | ||
2739 | @cindex @code{nil}, history of word | |
2740 | The former is the name of the buffer and the latter is the name of the | |
2741 | file. In Info, the buffer name is @file{"*info*"}. Info does not | |
2742 | point to any file, so the result of evaluating | |
2743 | @code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is | |
2744 | from the Latin word for `nothing'; in this case, it means that the | |
2745 | buffer is not associated with any file. (In Lisp, @code{nil} is also | |
2746 | used to mean `false' and is a synonym for the empty list, @code{()}.) | |
2747 | ||
2748 | When I am writing, the name of my buffer is | |
2749 | @file{"introduction.texinfo"}. The name of the file to which it | |
2750 | points is @file{"/gnu/work/intro/introduction.texinfo"}. | |
2751 | ||
2752 | (In the expressions, the parentheses tell the Lisp interpreter to | |
2753 | treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as | |
2754 | functions; without the parentheses, the interpreter would attempt to | |
2755 | evaluate the symbols as variables. @xref{Variables}.) | |
2756 | ||
2757 | In spite of the distinction between files and buffers, you will often | |
2758 | find that people refer to a file when they mean a buffer and vice-verse. | |
2759 | Indeed, most people say, ``I am editing a file,'' rather than saying, | |
2760 | ``I am editing a buffer which I will soon save to a file.'' It is | |
2761 | almost always clear from context what people mean. When dealing with | |
2762 | computer programs, however, it is important to keep the distinction in mind, | |
2763 | since the computer is not as smart as a person. | |
2764 | ||
2765 | @cindex Buffer, history of word | |
2766 | The word `buffer', by the way, comes from the meaning of the word as a | |
2767 | cushion that deadens the force of a collision. In early computers, a | |
2768 | buffer cushioned the interaction between files and the computer's | |
2769 | central processing unit. The drums or tapes that held a file and the | |
2770 | central processing unit were pieces of equipment that were very | |
2771 | different from each other, working at their own speeds, in spurts. The | |
2772 | buffer made it possible for them to work together effectively. | |
2773 | Eventually, the buffer grew from being an intermediary, a temporary | |
2774 | holding place, to being the place where work is done. This | |
2775 | transformation is rather like that of a small seaport that grew into a | |
2776 | great city: once it was merely the place where cargo was warehoused | |
2777 | temporarily before being loaded onto ships; then it became a business | |
2778 | and cultural center in its own right. | |
2779 | ||
2780 | Not all buffers are associated with files. For example, a | |
2781 | @file{*scratch*} buffer does not visit any file. Similarly, a | |
2782 | @file{*Help*} buffer is not associated with any file. | |
2783 | ||
2784 | In the old days, when you lacked a @file{~/.emacs} file and started an | |
2785 | Emacs session by typing the command @code{emacs} alone, without naming | |
2786 | any files, Emacs started with the @file{*scratch*} buffer visible. | |
2787 | Nowadays, you will see a splash screen. You can follow one of the | |
2788 | commands suggested on the splash screen, visit a file, or press the | |
2789 | spacebar to reach the @file{*scratch*} buffer. | |
2790 | ||
2791 | If you switch to the @file{*scratch*} buffer, type | |
2792 | @code{(buffer-name)}, position the cursor after it, and then type | |
2793 | @kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"} | |
2794 | will be returned and will appear in the echo area. @code{"*scratch*"} | |
2795 | is the name of the buffer. When you type @code{(buffer-file-name)} in | |
2796 | the @file{*scratch*} buffer and evaluate that, @code{nil} will appear | |
2797 | in the echo area, just as it does when you evaluate | |
2798 | @code{(buffer-file-name)} in Info. | |
2799 | ||
2800 | Incidentally, if you are in the @file{*scratch*} buffer and want the | |
2801 | value returned by an expression to appear in the @file{*scratch*} | |
2802 | buffer itself rather than in the echo area, type @kbd{C-u C-x C-e} | |
2803 | instead of @kbd{C-x C-e}. This causes the value returned to appear | |
2804 | after the expression. The buffer will look like this: | |
2805 | ||
2806 | @smallexample | |
2807 | (buffer-name)"*scratch*" | |
2808 | @end smallexample | |
2809 | ||
2810 | @noindent | |
2811 | You cannot do this in Info since Info is read-only and it will not allow | |
2812 | you to change the contents of the buffer. But you can do this in any | |
2813 | buffer you can edit; and when you write code or documentation (such as | |
2814 | this book), this feature is very useful. | |
2815 | ||
d6adf7e7 | 2816 | @node Getting Buffers |
8cda6f8f GM |
2817 | @section Getting Buffers |
2818 | @findex current-buffer | |
2819 | @findex other-buffer | |
2820 | @cindex Getting a buffer | |
2821 | ||
2822 | The @code{buffer-name} function returns the @emph{name} of the buffer; | |
2823 | to get the buffer @emph{itself}, a different function is needed: the | |
2824 | @code{current-buffer} function. If you use this function in code, what | |
2825 | you get is the buffer itself. | |
2826 | ||
2827 | A name and the object or entity to which the name refers are different | |
2828 | from each other. You are not your name. You are a person to whom | |
2829 | others refer by name. If you ask to speak to George and someone hands you | |
2830 | a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r}, | |
2831 | @samp{g}, and @samp{e} written on it, you might be amused, but you would | |
2832 | not be satisfied. You do not want to speak to the name, but to the | |
2833 | person to whom the name refers. A buffer is similar: the name of the | |
2834 | scratch buffer is @file{*scratch*}, but the name is not the buffer. To | |
2835 | get a buffer itself, you need to use a function such as | |
2836 | @code{current-buffer}. | |
2837 | ||
2838 | However, there is a slight complication: if you evaluate | |
2839 | @code{current-buffer} in an expression on its own, as we will do here, | |
2840 | what you see is a printed representation of the name of the buffer | |
2841 | without the contents of the buffer. Emacs works this way for two | |
2842 | reasons: the buffer may be thousands of lines long---too long to be | |
2843 | conveniently displayed; and, another buffer may have the same contents | |
2844 | but a different name, and it is important to distinguish between them. | |
2845 | ||
2846 | @need 800 | |
2847 | Here is an expression containing the function: | |
2848 | ||
2849 | @smallexample | |
2850 | (current-buffer) | |
2851 | @end smallexample | |
2852 | ||
2853 | @noindent | |
2854 | If you evaluate this expression in Info in Emacs in the usual way, | |
2855 | @file{#<buffer *info*>} will appear in the echo area. The special | |
2856 | format indicates that the buffer itself is being returned, rather than | |
2857 | just its name. | |
2858 | ||
2859 | Incidentally, while you can type a number or symbol into a program, you | |
2860 | cannot do that with the printed representation of a buffer: the only way | |
2861 | to get a buffer itself is with a function such as @code{current-buffer}. | |
2862 | ||
2863 | A related function is @code{other-buffer}. This returns the most | |
2864 | recently selected buffer other than the one you are in currently, not | |
2865 | a printed representation of its name. If you have recently switched | |
2866 | back and forth from the @file{*scratch*} buffer, @code{other-buffer} | |
2867 | will return that buffer. | |
2868 | ||
2869 | @need 800 | |
2870 | You can see this by evaluating the expression: | |
2871 | ||
2872 | @smallexample | |
2873 | (other-buffer) | |
2874 | @end smallexample | |
2875 | ||
2876 | @noindent | |
2877 | You should see @file{#<buffer *scratch*>} appear in the echo area, or | |
2878 | the name of whatever other buffer you switched back from most | |
2879 | recently@footnote{Actually, by default, if the buffer from which you | |
2880 | just switched is visible to you in another window, @code{other-buffer} | |
2881 | will choose the most recent buffer that you cannot see; this is a | |
2882 | subtlety that I often forget.}. | |
2883 | ||
d6adf7e7 | 2884 | @node Switching Buffers |
8cda6f8f GM |
2885 | @section Switching Buffers |
2886 | @findex switch-to-buffer | |
2887 | @findex set-buffer | |
2888 | @cindex Switching to a buffer | |
2889 | ||
2890 | The @code{other-buffer} function actually provides a buffer when it is | |
2891 | used as an argument to a function that requires one. We can see this | |
2892 | by using @code{other-buffer} and @code{switch-to-buffer} to switch to a | |
2893 | different buffer. | |
2894 | ||
2895 | But first, a brief introduction to the @code{switch-to-buffer} | |
2896 | function. When you switched back and forth from Info to the | |
2897 | @file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most | |
2898 | likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or | |
2899 | rather, to save typing, you probably only typed @kbd{RET} if the | |
2900 | default buffer was @file{*scratch*}, or if it was different, then you | |
2901 | typed just part of the name, such as @code{*sc}, pressed your | |
2902 | @kbd{TAB} key to cause it to expand to the full name, and then typed | |
8f4ea8e0 | 2903 | @kbd{RET}.} when prompted in the minibuffer for the name of |
8cda6f8f GM |
2904 | the buffer to which you wanted to switch. The keystrokes, @kbd{C-x |
2905 | b}, cause the Lisp interpreter to evaluate the interactive function | |
2906 | @code{switch-to-buffer}. As we said before, this is how Emacs works: | |
2907 | different keystrokes call or run different functions. For example, | |
2908 | @kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls | |
2909 | @code{forward-sentence}, and so on. | |
2910 | ||
2911 | By writing @code{switch-to-buffer} in an expression, and giving it a | |
2912 | buffer to switch to, we can switch buffers just the way @kbd{C-x b} | |
8f4ea8e0 | 2913 | does: |
8cda6f8f GM |
2914 | |
2915 | @smallexample | |
2916 | (switch-to-buffer (other-buffer)) | |
2917 | @end smallexample | |
2918 | ||
2919 | @noindent | |
2920 | The symbol @code{switch-to-buffer} is the first element of the list, | |
2921 | so the Lisp interpreter will treat it as a function and carry out the | |
2922 | instructions that are attached to it. But before doing that, the | |
2923 | interpreter will note that @code{other-buffer} is inside parentheses | |
2924 | and work on that symbol first. @code{other-buffer} is the first (and | |
2925 | in this case, the only) element of this list, so the Lisp interpreter | |
2926 | calls or runs the function. It returns another buffer. Next, the | |
2927 | interpreter runs @code{switch-to-buffer}, passing to it, as an | |
2928 | argument, the other buffer, which is what Emacs will switch to. If | |
2929 | you are reading this in Info, try this now. Evaluate the expression. | |
2930 | (To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this | |
2931 | expression will move you to your most recent other buffer that you | |
2932 | cannot see. If you really want to go to your most recently selected | |
2933 | buffer, even if you can still see it, you need to evaluate the | |
2934 | following more complex expression: | |
2935 | ||
2936 | @smallexample | |
2937 | (switch-to-buffer (other-buffer (current-buffer) t)) | |
2938 | @end smallexample | |
2939 | ||
2940 | @c noindent | |
2941 | In this case, the first argument to @code{other-buffer} tells it which | |
2942 | buffer to skip---the current one---and the second argument tells | |
2943 | @code{other-buffer} it is OK to switch to a visible buffer. | |
2944 | In regular use, @code{switch-to-buffer} takes you to an invisible | |
2945 | window since you would most likely use @kbd{C-x o} (@code{other-window}) | |
2946 | to go to another visible buffer.} | |
2947 | ||
2948 | In the programming examples in later sections of this document, you will | |
2949 | see the function @code{set-buffer} more often than | |
2950 | @code{switch-to-buffer}. This is because of a difference between | |
2951 | computer programs and humans: humans have eyes and expect to see the | |
2952 | buffer on which they are working on their computer terminals. This is | |
2953 | so obvious, it almost goes without saying. However, programs do not | |
2954 | have eyes. When a computer program works on a buffer, that buffer does | |
2955 | not need to be visible on the screen. | |
2956 | ||
2957 | @code{switch-to-buffer} is designed for humans and does two different | |
44e97401 | 2958 | things: it switches the buffer to which Emacs's attention is directed; and |
8cda6f8f GM |
2959 | it switches the buffer displayed in the window to the new buffer. |
2960 | @code{set-buffer}, on the other hand, does only one thing: it switches | |
2961 | the attention of the computer program to a different buffer. The buffer | |
2962 | on the screen remains unchanged (of course, normally nothing happens | |
2963 | there until the command finishes running). | |
2964 | ||
2965 | @cindex @samp{call} defined | |
2966 | Also, we have just introduced another jargon term, the word @dfn{call}. | |
2967 | When you evaluate a list in which the first symbol is a function, you | |
2968 | are calling that function. The use of the term comes from the notion of | |
2969 | the function as an entity that can do something for you if you `call' | |
2970 | it---just as a plumber is an entity who can fix a leak if you call him | |
2971 | or her. | |
2972 | ||
d6adf7e7 | 2973 | @node Buffer Size & Locations |
8cda6f8f GM |
2974 | @section Buffer Size and the Location of Point |
2975 | @cindex Size of buffer | |
2976 | @cindex Buffer size | |
2977 | @cindex Point location | |
2978 | @cindex Location of point | |
2979 | ||
2980 | Finally, let's look at several rather simple functions, | |
2981 | @code{buffer-size}, @code{point}, @code{point-min}, and | |
2982 | @code{point-max}. These give information about the size of a buffer and | |
2983 | the location of point within it. | |
2984 | ||
2985 | The function @code{buffer-size} tells you the size of the current | |
2986 | buffer; that is, the function returns a count of the number of | |
2987 | characters in the buffer. | |
2988 | ||
2989 | @smallexample | |
2990 | (buffer-size) | |
2991 | @end smallexample | |
2992 | ||
2993 | @noindent | |
2994 | You can evaluate this in the usual way, by positioning the | |
2995 | cursor after the expression and typing @kbd{C-x C-e}. | |
2996 | ||
2997 | @cindex @samp{point} defined | |
2998 | In Emacs, the current position of the cursor is called @dfn{point}. | |
2999 | The expression @code{(point)} returns a number that tells you where the | |
3000 | cursor is located as a count of the number of characters from the | |
3001 | beginning of the buffer up to point. | |
3002 | ||
3003 | @need 1250 | |
3004 | You can see the character count for point in this buffer by evaluating | |
3005 | the following expression in the usual way: | |
3006 | ||
3007 | @smallexample | |
3008 | (point) | |
3009 | @end smallexample | |
3010 | ||
3011 | @noindent | |
3012 | As I write this, the value of @code{point} is 65724. The @code{point} | |
3013 | function is frequently used in some of the examples later in this | |
3014 | book. | |
3015 | ||
3016 | @need 1250 | |
3017 | The value of point depends, of course, on its location within the | |
3018 | buffer. If you evaluate point in this spot, the number will be larger: | |
3019 | ||
3020 | @smallexample | |
3021 | (point) | |
3022 | @end smallexample | |
3023 | ||
3024 | @noindent | |
3025 | For me, the value of point in this location is 66043, which means that | |
3026 | there are 319 characters (including spaces) between the two | |
3027 | expressions. (Doubtless, you will see different numbers, since I will | |
3028 | have edited this since I first evaluated point.) | |
3029 | ||
3030 | @cindex @samp{narrowing} defined | |
3031 | The function @code{point-min} is somewhat similar to @code{point}, but | |
3032 | it returns the value of the minimum permissible value of point in the | |
3033 | current buffer. This is the number 1 unless @dfn{narrowing} is in | |
3034 | effect. (Narrowing is a mechanism whereby you can restrict yourself, | |
3035 | or a program, to operations on just a part of a buffer. | |
3036 | @xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the | |
3037 | function @code{point-max} returns the value of the maximum permissible | |
3038 | value of point in the current buffer. | |
3039 | ||
d6adf7e7 | 3040 | @node Evaluation Exercise |
8cda6f8f GM |
3041 | @section Exercise |
3042 | ||
3043 | Find a file with which you are working and move towards its middle. | |
3044 | Find its buffer name, file name, length, and your position in the file. | |
3045 | ||
d6adf7e7 | 3046 | @node Writing Defuns |
8cda6f8f GM |
3047 | @chapter How To Write Function Definitions |
3048 | @cindex Definition writing | |
3049 | @cindex Function definition writing | |
3050 | @cindex Writing a function definition | |
3051 | ||
3052 | When the Lisp interpreter evaluates a list, it looks to see whether the | |
3053 | first symbol on the list has a function definition attached to it; or, | |
3054 | put another way, whether the symbol points to a function definition. If | |
3055 | it does, the computer carries out the instructions in the definition. A | |
3056 | symbol that has a function definition is called, simply, a function | |
3057 | (although, properly speaking, the definition is the function and the | |
3058 | symbol refers to it.) | |
3059 | ||
3060 | @menu | |
3061 | * Primitive Functions:: | |
3062 | * defun:: The @code{defun} special form. | |
3063 | * Install:: Install a function definition. | |
3064 | * Interactive:: Making a function interactive. | |
3065 | * Interactive Options:: Different options for @code{interactive}. | |
3066 | * Permanent Installation:: Installing code permanently. | |
3067 | * let:: Creating and initializing local variables. | |
3068 | * if:: What if? | |
3069 | * else:: If--then--else expressions. | |
3070 | * Truth & Falsehood:: What Lisp considers false and true. | |
3071 | * save-excursion:: Keeping track of point, mark, and buffer. | |
3072 | * Review:: | |
3073 | * defun Exercises:: | |
3074 | @end menu | |
3075 | ||
8cda6f8f | 3076 | @ifnottex |
d6adf7e7 | 3077 | @node Primitive Functions |
8cda6f8f GM |
3078 | @unnumberedsec An Aside about Primitive Functions |
3079 | @end ifnottex | |
3080 | @cindex Primitive functions | |
3081 | @cindex Functions, primitive | |
3082 | ||
3083 | @cindex C language primitives | |
3084 | @cindex Primitives written in C | |
3085 | All functions are defined in terms of other functions, except for a few | |
3086 | @dfn{primitive} functions that are written in the C programming | |
3087 | language. When you write functions' definitions, you will write them in | |
3088 | Emacs Lisp and use other functions as your building blocks. Some of the | |
3089 | functions you will use will themselves be written in Emacs Lisp (perhaps | |
1df7defd | 3090 | by you) and some will be primitives written in C@. The primitive |
8cda6f8f GM |
3091 | functions are used exactly like those written in Emacs Lisp and behave |
3092 | like them. They are written in C so we can easily run GNU Emacs on any | |
3093 | computer that has sufficient power and can run C. | |
3094 | ||
3095 | Let me re-emphasize this: when you write code in Emacs Lisp, you do not | |
3096 | distinguish between the use of functions written in C and the use of | |
3097 | functions written in Emacs Lisp. The difference is irrelevant. I | |
3098 | mention the distinction only because it is interesting to know. Indeed, | |
3099 | unless you investigate, you won't know whether an already-written | |
3100 | function is written in Emacs Lisp or C. | |
3101 | ||
d6adf7e7 | 3102 | @node defun |
767b8eae | 3103 | @section The @code{defun} Macro |
8cda6f8f | 3104 | @findex defun |
8cda6f8f GM |
3105 | |
3106 | @cindex @samp{function definition} defined | |
3107 | In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to | |
3108 | it that tells the computer what to do when the function is called. | |
3109 | This code is called the @dfn{function definition} and is created by | |
3110 | evaluating a Lisp expression that starts with the symbol @code{defun} | |
767b8eae | 3111 | (which is an abbreviation for @emph{define function}). |
8cda6f8f GM |
3112 | |
3113 | In subsequent sections, we will look at function definitions from the | |
3114 | Emacs source code, such as @code{mark-whole-buffer}. In this section, | |
3115 | we will describe a simple function definition so you can see how it | |
3116 | looks. This function definition uses arithmetic because it makes for a | |
3117 | simple example. Some people dislike examples using arithmetic; however, | |
3118 | if you are such a person, do not despair. Hardly any of the code we | |
3119 | will study in the remainder of this introduction involves arithmetic or | |
3120 | mathematics. The examples mostly involve text in one way or another. | |
3121 | ||
3122 | A function definition has up to five parts following the word | |
3123 | @code{defun}: | |
3124 | ||
3125 | @enumerate | |
3126 | @item | |
3127 | The name of the symbol to which the function definition should be | |
3128 | attached. | |
3129 | ||
3130 | @item | |
3131 | A list of the arguments that will be passed to the function. If no | |
3132 | arguments will be passed to the function, this is an empty list, | |
3133 | @code{()}. | |
3134 | ||
3135 | @item | |
3136 | Documentation describing the function. (Technically optional, but | |
3137 | strongly recommended.) | |
3138 | ||
3139 | @item | |
3140 | Optionally, an expression to make the function interactive so you can | |
3141 | use it by typing @kbd{M-x} and then the name of the function; or by | |
3142 | typing an appropriate key or keychord. | |
3143 | ||
3144 | @cindex @samp{body} defined | |
3145 | @item | |
3146 | The code that instructs the computer what to do: the @dfn{body} of the | |
3147 | function definition. | |
3148 | @end enumerate | |
3149 | ||
3150 | It is helpful to think of the five parts of a function definition as | |
3151 | being organized in a template, with slots for each part: | |
3152 | ||
3153 | @smallexample | |
3154 | @group | |
3155 | (defun @var{function-name} (@var{arguments}@dots{}) | |
3156 | "@var{optional-documentation}@dots{}" | |
3157 | (interactive @var{argument-passing-info}) ; @r{optional} | |
3158 | @var{body}@dots{}) | |
3159 | @end group | |
3160 | @end smallexample | |
3161 | ||
3162 | As an example, here is the code for a function that multiplies its | |
3163 | argument by 7. (This example is not interactive. @xref{Interactive, | |
3164 | , Making a Function Interactive}, for that information.) | |
3165 | ||
3166 | @smallexample | |
3167 | @group | |
3168 | (defun multiply-by-seven (number) | |
3169 | "Multiply NUMBER by seven." | |
3170 | (* 7 number)) | |
3171 | @end group | |
3172 | @end smallexample | |
3173 | ||
3174 | This definition begins with a parenthesis and the symbol @code{defun}, | |
3175 | followed by the name of the function. | |
3176 | ||
3177 | @cindex @samp{argument list} defined | |
3178 | The name of the function is followed by a list that contains the | |
3179 | arguments that will be passed to the function. This list is called | |
3180 | the @dfn{argument list}. In this example, the list has only one | |
3181 | element, the symbol, @code{number}. When the function is used, the | |
3182 | symbol will be bound to the value that is used as the argument to the | |
3183 | function. | |
3184 | ||
3185 | Instead of choosing the word @code{number} for the name of the argument, | |
3186 | I could have picked any other name. For example, I could have chosen | |
3187 | the word @code{multiplicand}. I picked the word `number' because it | |
3188 | tells what kind of value is intended for this slot; but I could just as | |
3189 | well have chosen the word `multiplicand' to indicate the role that the | |
3190 | value placed in this slot will play in the workings of the function. I | |
3191 | could have called it @code{foogle}, but that would have been a bad | |
3192 | choice because it would not tell humans what it means. The choice of | |
3193 | name is up to the programmer and should be chosen to make the meaning of | |
3194 | the function clear. | |
3195 | ||
3196 | Indeed, you can choose any name you wish for a symbol in an argument | |
3197 | list, even the name of a symbol used in some other function: the name | |
3198 | you use in an argument list is private to that particular definition. | |
3199 | In that definition, the name refers to a different entity than any use | |
3200 | of the same name outside the function definition. Suppose you have a | |
3201 | nick-name `Shorty' in your family; when your family members refer to | |
3202 | `Shorty', they mean you. But outside your family, in a movie, for | |
3203 | example, the name `Shorty' refers to someone else. Because a name in an | |
3204 | argument list is private to the function definition, you can change the | |
3205 | value of such a symbol inside the body of a function without changing | |
3206 | its value outside the function. The effect is similar to that produced | |
3207 | by a @code{let} expression. (@xref{let, , @code{let}}.) | |
3208 | ||
3209 | @ignore | |
3210 | Note also that we discuss the word `number' in two different ways: as a | |
3211 | symbol that appears in the code, and as the name of something that will | |
3212 | be replaced by a something else during the evaluation of the function. | |
3213 | In the first case, @code{number} is a symbol, not a number; it happens | |
3214 | that within the function, it is a variable who value is the number in | |
3215 | question, but our primary interest in it is as a symbol. On the other | |
3216 | hand, when we are talking about the function, our interest is that we | |
3217 | will substitute a number for the word @var{number}. To keep this | |
3218 | distinction clear, we use different typography for the two | |
3219 | circumstances. When we talk about this function, or about how it works, | |
3220 | we refer to this number by writing @var{number}. In the function | |
3221 | itself, we refer to it by writing @code{number}. | |
3222 | @end ignore | |
3223 | ||
3224 | The argument list is followed by the documentation string that | |
3225 | describes the function. This is what you see when you type | |
3226 | @w{@kbd{C-h f}} and the name of a function. Incidentally, when you | |
3227 | write a documentation string like this, you should make the first line | |
3228 | a complete sentence since some commands, such as @code{apropos}, print | |
3229 | only the first line of a multi-line documentation string. Also, you | |
3230 | should not indent the second line of a documentation string, if you | |
3231 | have one, because that looks odd when you use @kbd{C-h f} | |
3232 | (@code{describe-function}). The documentation string is optional, but | |
3233 | it is so useful, it should be included in almost every function you | |
3234 | write. | |
3235 | ||
3236 | @findex * @r{(multiplication)} | |
3237 | The third line of the example consists of the body of the function | |
3238 | definition. (Most functions' definitions, of course, are longer than | |
3239 | this.) In this function, the body is the list, @code{(* 7 number)}, which | |
3240 | says to multiply the value of @var{number} by 7. (In Emacs Lisp, | |
3241 | @code{*} is the function for multiplication, just as @code{+} is the | |
3242 | function for addition.) | |
3243 | ||
3244 | When you use the @code{multiply-by-seven} function, the argument | |
3245 | @code{number} evaluates to the actual number you want used. Here is an | |
3246 | example that shows how @code{multiply-by-seven} is used; but don't try | |
3247 | to evaluate this yet! | |
3248 | ||
3249 | @smallexample | |
3250 | (multiply-by-seven 3) | |
3251 | @end smallexample | |
3252 | ||
3253 | @noindent | |
3254 | The symbol @code{number}, specified in the function definition in the | |
3255 | next section, is given or ``bound to'' the value 3 in the actual use of | |
3256 | the function. Note that although @code{number} was inside parentheses | |
3257 | in the function definition, the argument passed to the | |
3258 | @code{multiply-by-seven} function is not in parentheses. The | |
3259 | parentheses are written in the function definition so the computer can | |
3260 | figure out where the argument list ends and the rest of the function | |
3261 | definition begins. | |
3262 | ||
3263 | If you evaluate this example, you are likely to get an error message. | |
3264 | (Go ahead, try it!) This is because we have written the function | |
3265 | definition, but not yet told the computer about the definition---we have | |
3266 | not yet installed (or `loaded') the function definition in Emacs. | |
3267 | Installing a function is the process that tells the Lisp interpreter the | |
3268 | definition of the function. Installation is described in the next | |
3269 | section. | |
3270 | ||
d6adf7e7 | 3271 | @node Install |
8cda6f8f GM |
3272 | @section Install a Function Definition |
3273 | @cindex Install a Function Definition | |
3274 | @cindex Definition installation | |
3275 | @cindex Function definition installation | |
3276 | ||
3277 | If you are reading this inside of Info in Emacs, you can try out the | |
3278 | @code{multiply-by-seven} function by first evaluating the function | |
3279 | definition and then evaluating @code{(multiply-by-seven 3)}. A copy of | |
3280 | the function definition follows. Place the cursor after the last | |
3281 | parenthesis of the function definition and type @kbd{C-x C-e}. When you | |
3282 | do this, @code{multiply-by-seven} will appear in the echo area. (What | |
3283 | this means is that when a function definition is evaluated, the value it | |
3284 | returns is the name of the defined function.) At the same time, this | |
3285 | action installs the function definition. | |
3286 | ||
3287 | @smallexample | |
3288 | @group | |
3289 | (defun multiply-by-seven (number) | |
3290 | "Multiply NUMBER by seven." | |
3291 | (* 7 number)) | |
3292 | @end group | |
3293 | @end smallexample | |
3294 | ||
3295 | @noindent | |
3296 | By evaluating this @code{defun}, you have just installed | |
3297 | @code{multiply-by-seven} in Emacs. The function is now just as much a | |
3298 | part of Emacs as @code{forward-word} or any other editing function you | |
3299 | use. (@code{multiply-by-seven} will stay installed until you quit | |
3300 | Emacs. To reload code automatically whenever you start Emacs, see | |
3301 | @ref{Permanent Installation, , Installing Code Permanently}.) | |
3302 | ||
3303 | @menu | |
3304 | * Effect of installation:: | |
3305 | * Change a defun:: How to change a function definition. | |
3306 | @end menu | |
3307 | ||
8cda6f8f | 3308 | @ifnottex |
d6adf7e7 | 3309 | @node Effect of installation |
8cda6f8f GM |
3310 | @unnumberedsubsec The effect of installation |
3311 | @end ifnottex | |
3312 | ||
3313 | You can see the effect of installing @code{multiply-by-seven} by | |
3314 | evaluating the following sample. Place the cursor after the following | |
3315 | expression and type @kbd{C-x C-e}. The number 21 will appear in the | |
3316 | echo area. | |
3317 | ||
3318 | @smallexample | |
3319 | (multiply-by-seven 3) | |
3320 | @end smallexample | |
3321 | ||
3322 | If you wish, you can read the documentation for the function by typing | |
3323 | @kbd{C-h f} (@code{describe-function}) and then the name of the | |
3324 | function, @code{multiply-by-seven}. When you do this, a | |
3325 | @file{*Help*} window will appear on your screen that says: | |
3326 | ||
3327 | @smallexample | |
3328 | @group | |
3329 | multiply-by-seven is a Lisp function. | |
3330 | (multiply-by-seven NUMBER) | |
3331 | ||
3332 | Multiply NUMBER by seven. | |
3333 | @end group | |
3334 | @end smallexample | |
3335 | ||
3336 | @noindent | |
3337 | (To return to a single window on your screen, type @kbd{C-x 1}.) | |
3338 | ||
d6adf7e7 | 3339 | @node Change a defun |
8cda6f8f GM |
3340 | @subsection Change a Function Definition |
3341 | @cindex Changing a function definition | |
3342 | @cindex Function definition, how to change | |
3343 | @cindex Definition, how to change | |
3344 | ||
3345 | If you want to change the code in @code{multiply-by-seven}, just rewrite | |
3346 | it. To install the new version in place of the old one, evaluate the | |
3347 | function definition again. This is how you modify code in Emacs. It is | |
3348 | very simple. | |
3349 | ||
3350 | As an example, you can change the @code{multiply-by-seven} function to | |
3351 | add the number to itself seven times instead of multiplying the number | |
3352 | by seven. It produces the same answer, but by a different path. At | |
3353 | the same time, we will add a comment to the code; a comment is text | |
3354 | that the Lisp interpreter ignores, but that a human reader may find | |
3355 | useful or enlightening. The comment is that this is the ``second | |
3356 | version''. | |
3357 | ||
3358 | @smallexample | |
3359 | @group | |
3360 | (defun multiply-by-seven (number) ; @r{Second version.} | |
3361 | "Multiply NUMBER by seven." | |
3362 | (+ number number number number number number number)) | |
3363 | @end group | |
3364 | @end smallexample | |
3365 | ||
3366 | @cindex Comments in Lisp code | |
3367 | The comment follows a semicolon, @samp{;}. In Lisp, everything on a | |
3368 | line that follows a semicolon is a comment. The end of the line is the | |
3369 | end of the comment. To stretch a comment over two or more lines, begin | |
3370 | each line with a semicolon. | |
3371 | ||
3372 | @xref{Beginning a .emacs File, , Beginning a @file{.emacs} | |
3373 | File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp | |
3374 | Reference Manual}, for more about comments. | |
3375 | ||
3376 | You can install this version of the @code{multiply-by-seven} function by | |
3377 | evaluating it in the same way you evaluated the first function: place | |
3378 | the cursor after the last parenthesis and type @kbd{C-x C-e}. | |
3379 | ||
3380 | In summary, this is how you write code in Emacs Lisp: you write a | |
3381 | function; install it; test it; and then make fixes or enhancements and | |
3382 | install it again. | |
3383 | ||
d6adf7e7 | 3384 | @node Interactive |
8cda6f8f GM |
3385 | @section Make a Function Interactive |
3386 | @cindex Interactive functions | |
3387 | @findex interactive | |
3388 | ||
3389 | You make a function interactive by placing a list that begins with | |
3390 | the special form @code{interactive} immediately after the | |
3391 | documentation. A user can invoke an interactive function by typing | |
3392 | @kbd{M-x} and then the name of the function; or by typing the keys to | |
3393 | which it is bound, for example, by typing @kbd{C-n} for | |
3394 | @code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}. | |
3395 | ||
3396 | Interestingly, when you call an interactive function interactively, | |
3397 | the value returned is not automatically displayed in the echo area. | |
3398 | This is because you often call an interactive function for its side | |
3399 | effects, such as moving forward by a word or line, and not for the | |
3400 | value returned. If the returned value were displayed in the echo area | |
3401 | each time you typed a key, it would be very distracting. | |
3402 | ||
3403 | @menu | |
3404 | * Interactive multiply-by-seven:: An overview. | |
3405 | * multiply-by-seven in detail:: The interactive version. | |
3406 | @end menu | |
3407 | ||
8cda6f8f | 3408 | @ifnottex |
d6adf7e7 | 3409 | @node Interactive multiply-by-seven |
8cda6f8f GM |
3410 | @unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview |
3411 | @end ifnottex | |
3412 | ||
3413 | Both the use of the special form @code{interactive} and one way to | |
3414 | display a value in the echo area can be illustrated by creating an | |
3415 | interactive version of @code{multiply-by-seven}. | |
3416 | ||
3417 | @need 1250 | |
3418 | Here is the code: | |
3419 | ||
3420 | @smallexample | |
3421 | @group | |
3422 | (defun multiply-by-seven (number) ; @r{Interactive version.} | |
3423 | "Multiply NUMBER by seven." | |
3424 | (interactive "p") | |
3425 | (message "The result is %d" (* 7 number))) | |
3426 | @end group | |
3427 | @end smallexample | |
3428 | ||
3429 | @noindent | |
3430 | You can install this code by placing your cursor after it and typing | |
3431 | @kbd{C-x C-e}. The name of the function will appear in your echo area. | |
3432 | Then, you can use this code by typing @kbd{C-u} and a number and then | |
3433 | typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase | |
3434 | @samp{The result is @dots{}} followed by the product will appear in the | |
3435 | echo area. | |
3436 | ||
3437 | Speaking more generally, you invoke a function like this in either of two | |
3438 | ways: | |
3439 | ||
3440 | @enumerate | |
3441 | @item | |
3442 | By typing a prefix argument that contains the number to be passed, and | |
3443 | then typing @kbd{M-x} and the name of the function, as with | |
3444 | @kbd{C-u 3 M-x forward-sentence}; or, | |
3445 | ||
3446 | @item | |
3447 | By typing whatever key or keychord the function is bound to, as with | |
3448 | @kbd{C-u 3 M-e}. | |
3449 | @end enumerate | |
3450 | ||
3451 | @noindent | |
3452 | Both the examples just mentioned work identically to move point forward | |
3453 | three sentences. (Since @code{multiply-by-seven} is not bound to a key, | |
3454 | it could not be used as an example of key binding.) | |
3455 | ||
3456 | (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command | |
3457 | to a key.) | |
3458 | ||
3459 | A prefix argument is passed to an interactive function by typing the | |
3460 | @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by | |
3461 | typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you | |
3462 | type @kbd{C-u} without a number, it defaults to 4). | |
3463 | ||
d6adf7e7 | 3464 | @node multiply-by-seven in detail |
8cda6f8f GM |
3465 | @subsection An Interactive @code{multiply-by-seven} |
3466 | ||
3467 | Let's look at the use of the special form @code{interactive} and then at | |
3468 | the function @code{message} in the interactive version of | |
3469 | @code{multiply-by-seven}. You will recall that the function definition | |
3470 | looks like this: | |
3471 | ||
3472 | @smallexample | |
3473 | @group | |
3474 | (defun multiply-by-seven (number) ; @r{Interactive version.} | |
3475 | "Multiply NUMBER by seven." | |
3476 | (interactive "p") | |
3477 | (message "The result is %d" (* 7 number))) | |
3478 | @end group | |
3479 | @end smallexample | |
3480 | ||
3481 | In this function, the expression, @code{(interactive "p")}, is a list of | |
3482 | two elements. The @code{"p"} tells Emacs to pass the prefix argument to | |
3483 | the function and use its value for the argument of the function. | |
3484 | ||
3485 | @need 1000 | |
3486 | The argument will be a number. This means that the symbol | |
3487 | @code{number} will be bound to a number in the line: | |
3488 | ||
3489 | @smallexample | |
3490 | (message "The result is %d" (* 7 number)) | |
3491 | @end smallexample | |
3492 | ||
3493 | @need 1250 | |
3494 | @noindent | |
3495 | For example, if your prefix argument is 5, the Lisp interpreter will | |
3496 | evaluate the line as if it were: | |
3497 | ||
3498 | @smallexample | |
3499 | (message "The result is %d" (* 7 5)) | |
3500 | @end smallexample | |
3501 | ||
3502 | @noindent | |
3503 | (If you are reading this in GNU Emacs, you can evaluate this expression | |
3504 | yourself.) First, the interpreter will evaluate the inner list, which | |
3505 | is @code{(* 7 5)}. This returns a value of 35. Next, it | |
3506 | will evaluate the outer list, passing the values of the second and | |
3507 | subsequent elements of the list to the function @code{message}. | |
3508 | ||
3509 | As we have seen, @code{message} is an Emacs Lisp function especially | |
3510 | designed for sending a one line message to a user. (@xref{message, , | |
3511 | The @code{message} function}.) In summary, the @code{message} | |
3512 | function prints its first argument in the echo area as is, except for | |
3513 | occurrences of @samp{%d} or @samp{%s} (and various other %-sequences | |
3514 | which we have not mentioned). When it sees a control sequence, the | |
3515 | function looks to the second or subsequent arguments and prints the | |
3516 | value of the argument in the location in the string where the control | |
3517 | sequence is located. | |
3518 | ||
3519 | In the interactive @code{multiply-by-seven} function, the control string | |
3520 | is @samp{%d}, which requires a number, and the value returned by | |
3521 | evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35 | |
3522 | is printed in place of the @samp{%d} and the message is @samp{The result | |
3523 | is 35}. | |
3524 | ||
3525 | (Note that when you call the function @code{multiply-by-seven}, the | |
3526 | message is printed without quotes, but when you call @code{message}, the | |
3527 | text is printed in double quotes. This is because the value returned by | |
3528 | @code{message} is what appears in the echo area when you evaluate an | |
3529 | expression whose first element is @code{message}; but when embedded in a | |
3530 | function, @code{message} prints the text as a side effect without | |
3531 | quotes.) | |
3532 | ||
d6adf7e7 | 3533 | @node Interactive Options |
8cda6f8f GM |
3534 | @section Different Options for @code{interactive} |
3535 | @cindex Options for @code{interactive} | |
3536 | @cindex Interactive options | |
3537 | ||
3538 | In the example, @code{multiply-by-seven} used @code{"p"} as the | |
3539 | argument to @code{interactive}. This argument told Emacs to interpret | |
3540 | your typing either @kbd{C-u} followed by a number or @key{META} | |
3541 | followed by a number as a command to pass that number to the function | |
3542 | as its argument. Emacs has more than twenty characters predefined for | |
3543 | use with @code{interactive}. In almost every case, one of these | |
3544 | options will enable you to pass the right information interactively to | |
3545 | a function. (@xref{Interactive Codes, , Code Characters for | |
3546 | @code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.) | |
3547 | ||
3548 | @need 1250 | |
3549 | Consider the function @code{zap-to-char}. Its interactive expression | |
3550 | is | |
3551 | ||
3552 | @smallexample | |
3553 | (interactive "p\ncZap to char: ") | |
3554 | @end smallexample | |
3555 | ||
3556 | The first part of the argument to @code{interactive} is @samp{p}, with | |
3557 | which you are already familiar. This argument tells Emacs to | |
3558 | interpret a `prefix', as a number to be passed to the function. You | |
3559 | can specify a prefix either by typing @kbd{C-u} followed by a number | |
3560 | or by typing @key{META} followed by a number. The prefix is the | |
3561 | number of specified characters. Thus, if your prefix is three and the | |
3562 | specified character is @samp{x}, then you will delete all the text up | |
3563 | to and including the third next @samp{x}. If you do not set a prefix, | |
3564 | then you delete all the text up to and including the specified | |
3565 | character, but no more. | |
3566 | ||
3567 | The @samp{c} tells the function the name of the character to which to delete. | |
3568 | ||
3569 | More formally, a function with two or more arguments can have | |
3570 | information passed to each argument by adding parts to the string that | |
3571 | follows @code{interactive}. When you do this, the information is | |
3572 | passed to each argument in the same order it is specified in the | |
3573 | @code{interactive} list. In the string, each part is separated from | |
3574 | the next part by a @samp{\n}, which is a newline. For example, you | |
3575 | can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }. | |
3576 | This causes Emacs to pass the value of the prefix argument (if there | |
3577 | is one) and the character. | |
3578 | ||
3579 | In this case, the function definition looks like the following, where | |
3580 | @code{arg} and @code{char} are the symbols to which @code{interactive} | |
3581 | binds the prefix argument and the specified character: | |
3582 | ||
3583 | @smallexample | |
3584 | @group | |
3585 | (defun @var{name-of-function} (arg char) | |
3586 | "@var{documentation}@dots{}" | |
3587 | (interactive "p\ncZap to char: ") | |
3588 | @var{body-of-function}@dots{}) | |
3589 | @end group | |
3590 | @end smallexample | |
3591 | ||
3592 | @noindent | |
3593 | (The space after the colon in the prompt makes it look better when you | |
3594 | are prompted. @xref{copy-to-buffer, , The Definition of | |
3595 | @code{copy-to-buffer}}, for an example.) | |
3596 | ||
3597 | When a function does not take arguments, @code{interactive} does not | |
3598 | require any. Such a function contains the simple expression | |
3599 | @code{(interactive)}. The @code{mark-whole-buffer} function is like | |
3600 | this. | |
3601 | ||
3602 | Alternatively, if the special letter-codes are not right for your | |
3603 | application, you can pass your own arguments to @code{interactive} as | |
3604 | a list. | |
3605 | ||
3606 | @xref{append-to-buffer, , The Definition of @code{append-to-buffer}}, | |
3607 | for an example. @xref{Using Interactive, , Using @code{Interactive}, | |
3608 | elisp, The GNU Emacs Lisp Reference Manual}, for a more complete | |
3609 | explanation about this technique. | |
3610 | ||
d6adf7e7 | 3611 | @node Permanent Installation |
8cda6f8f GM |
3612 | @section Install Code Permanently |
3613 | @cindex Install code permanently | |
3614 | @cindex Permanent code installation | |
3615 | @cindex Code installation | |
3616 | ||
3617 | When you install a function definition by evaluating it, it will stay | |
3618 | installed until you quit Emacs. The next time you start a new session | |
3619 | of Emacs, the function will not be installed unless you evaluate the | |
3620 | function definition again. | |
3621 | ||
3622 | At some point, you may want to have code installed automatically | |
3623 | whenever you start a new session of Emacs. There are several ways of | |
3624 | doing this: | |
3625 | ||
3626 | @itemize @bullet | |
3627 | @item | |
3628 | If you have code that is just for yourself, you can put the code for the | |
3629 | function definition in your @file{.emacs} initialization file. When you | |
3630 | start Emacs, your @file{.emacs} file is automatically evaluated and all | |
3631 | the function definitions within it are installed. | |
3632 | @xref{Emacs Initialization, , Your @file{.emacs} File}. | |
3633 | ||
3634 | @item | |
3635 | Alternatively, you can put the function definitions that you want | |
3636 | installed in one or more files of their own and use the @code{load} | |
3637 | function to cause Emacs to evaluate and thereby install each of the | |
3638 | functions in the files. | |
3639 | @xref{Loading Files, , Loading Files}. | |
3640 | ||
3641 | @item | |
3642 | Thirdly, if you have code that your whole site will use, it is usual | |
3643 | to put it in a file called @file{site-init.el} that is loaded when | |
3644 | Emacs is built. This makes the code available to everyone who uses | |
3645 | your machine. (See the @file{INSTALL} file that is part of the Emacs | |
3646 | distribution.) | |
3647 | @end itemize | |
3648 | ||
3649 | Finally, if you have code that everyone who uses Emacs may want, you | |
3650 | can post it on a computer network or send a copy to the Free Software | |
3651 | Foundation. (When you do this, please license the code and its | |
3652 | documentation under a license that permits other people to run, copy, | |
3653 | study, modify, and redistribute the code and which protects you from | |
3654 | having your work taken from you.) If you send a copy of your code to | |
3655 | the Free Software Foundation, and properly protect yourself and | |
3656 | others, it may be included in the next release of Emacs. In large | |
3657 | part, this is how Emacs has grown over the past years, by donations. | |
3658 | ||
d6adf7e7 | 3659 | @node let |
8cda6f8f GM |
3660 | @section @code{let} |
3661 | @findex let | |
3662 | ||
3663 | The @code{let} expression is a special form in Lisp that you will need | |
3664 | to use in most function definitions. | |
3665 | ||
3666 | @code{let} is used to attach or bind a symbol to a value in such a way | |
3667 | that the Lisp interpreter will not confuse the variable with a | |
3668 | variable of the same name that is not part of the function. | |
3669 | ||
3670 | To understand why the @code{let} special form is necessary, consider | |
3671 | the situation in which you own a home that you generally refer to as | |
3672 | `the house', as in the sentence, ``The house needs painting.'' If you | |
3673 | are visiting a friend and your host refers to `the house', he is | |
3674 | likely to be referring to @emph{his} house, not yours, that is, to a | |
3675 | different house. | |
3676 | ||
3677 | If your friend is referring to his house and you think he is referring | |
3678 | to your house, you may be in for some confusion. The same thing could | |
3679 | happen in Lisp if a variable that is used inside of one function has | |
3680 | the same name as a variable that is used inside of another function, | |
3681 | and the two are not intended to refer to the same value. The | |
3682 | @code{let} special form prevents this kind of confusion. | |
3683 | ||
3684 | @menu | |
3685 | * Prevent confusion:: | |
3686 | * Parts of let Expression:: | |
3687 | * Sample let Expression:: | |
3688 | * Uninitialized let Variables:: | |
3689 | @end menu | |
3690 | ||
8cda6f8f | 3691 | @ifnottex |
d6adf7e7 | 3692 | @node Prevent confusion |
8cda6f8f GM |
3693 | @unnumberedsubsec @code{let} Prevents Confusion |
3694 | @end ifnottex | |
3695 | ||
3696 | @cindex @samp{local variable} defined | |
3697 | @cindex @samp{variable, local}, defined | |
3698 | The @code{let} special form prevents confusion. @code{let} creates a | |
3699 | name for a @dfn{local variable} that overshadows any use of the same | |
3700 | name outside the @code{let} expression. This is like understanding | |
3701 | that whenever your host refers to `the house', he means his house, not | |
3702 | yours. (Symbols used in argument lists work the same way. | |
3703 | @xref{defun, , The @code{defun} Special Form}.) | |
3704 | ||
3705 | Local variables created by a @code{let} expression retain their value | |
3706 | @emph{only} within the @code{let} expression itself (and within | |
3707 | expressions called within the @code{let} expression); the local | |
3708 | variables have no effect outside the @code{let} expression. | |
3709 | ||
3710 | Another way to think about @code{let} is that it is like a @code{setq} | |
3711 | that is temporary and local. The values set by @code{let} are | |
3712 | automatically undone when the @code{let} is finished. The setting | |
3713 | only affects expressions that are inside the bounds of the @code{let} | |
3714 | expression. In computer science jargon, we would say ``the binding of | |
3715 | a symbol is visible only in functions called in the @code{let} form; | |
3716 | in Emacs Lisp, scoping is dynamic, not lexical.'' | |
3717 | ||
3718 | @code{let} can create more than one variable at once. Also, | |
3719 | @code{let} gives each variable it creates an initial value, either a | |
3720 | value specified by you, or @code{nil}. (In the jargon, this is called | |
3721 | `binding the variable to the value'.) After @code{let} has created | |
3722 | and bound the variables, it executes the code in the body of the | |
3723 | @code{let}, and returns the value of the last expression in the body, | |
3724 | as the value of the whole @code{let} expression. (`Execute' is a jargon | |
3725 | term that means to evaluate a list; it comes from the use of the word | |
3726 | meaning `to give practical effect to' (@cite{Oxford English | |
3727 | Dictionary}). Since you evaluate an expression to perform an action, | |
3728 | `execute' has evolved as a synonym to `evaluate'.) | |
3729 | ||
d6adf7e7 | 3730 | @node Parts of let Expression |
8cda6f8f GM |
3731 | @subsection The Parts of a @code{let} Expression |
3732 | @cindex @code{let} expression, parts of | |
3733 | @cindex Parts of @code{let} expression | |
3734 | ||
3735 | @cindex @samp{varlist} defined | |
3736 | A @code{let} expression is a list of three parts. The first part is | |
3737 | the symbol @code{let}. The second part is a list, called a | |
3738 | @dfn{varlist}, each element of which is either a symbol by itself or a | |
3739 | two-element list, the first element of which is a symbol. The third | |
3740 | part of the @code{let} expression is the body of the @code{let}. The | |
3741 | body usually consists of one or more lists. | |
3742 | ||
3743 | @need 800 | |
3744 | A template for a @code{let} expression looks like this: | |
3745 | ||
3746 | @smallexample | |
3747 | (let @var{varlist} @var{body}@dots{}) | |
3748 | @end smallexample | |
3749 | ||
3750 | @noindent | |
3751 | The symbols in the varlist are the variables that are given initial | |
3752 | values by the @code{let} special form. Symbols by themselves are given | |
3753 | the initial value of @code{nil}; and each symbol that is the first | |
3754 | element of a two-element list is bound to the value that is returned | |
3755 | when the Lisp interpreter evaluates the second element. | |
3756 | ||
3757 | Thus, a varlist might look like this: @code{(thread (needles 3))}. In | |
3758 | this case, in a @code{let} expression, Emacs binds the symbol | |
3759 | @code{thread} to an initial value of @code{nil}, and binds the symbol | |
3760 | @code{needles} to an initial value of 3. | |
3761 | ||
3762 | When you write a @code{let} expression, what you do is put the | |
3763 | appropriate expressions in the slots of the @code{let} expression | |
3764 | template. | |
3765 | ||
3766 | If the varlist is composed of two-element lists, as is often the case, | |
3767 | the template for the @code{let} expression looks like this: | |
3768 | ||
3769 | @smallexample | |
3770 | @group | |
3771 | (let ((@var{variable} @var{value}) | |
3772 | (@var{variable} @var{value}) | |
3773 | @dots{}) | |
3774 | @var{body}@dots{}) | |
3775 | @end group | |
3776 | @end smallexample | |
3777 | ||
d6adf7e7 | 3778 | @node Sample let Expression |
8cda6f8f GM |
3779 | @subsection Sample @code{let} Expression |
3780 | @cindex Sample @code{let} expression | |
3781 | @cindex @code{let} expression sample | |
3782 | ||
3783 | The following expression creates and gives initial values | |
3784 | to the two variables @code{zebra} and @code{tiger}. The body of the | |
3785 | @code{let} expression is a list which calls the @code{message} function. | |
3786 | ||
3787 | @smallexample | |
3788 | @group | |
3789 | (let ((zebra 'stripes) | |
3790 | (tiger 'fierce)) | |
3791 | (message "One kind of animal has %s and another is %s." | |
3792 | zebra tiger)) | |
3793 | @end group | |
3794 | @end smallexample | |
3795 | ||
3796 | Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}. | |
3797 | ||
3798 | The two variables are @code{zebra} and @code{tiger}. Each variable is | |
3799 | the first element of a two-element list and each value is the second | |
3800 | element of its two-element list. In the varlist, Emacs binds the | |
3801 | variable @code{zebra} to the value @code{stripes}@footnote{According | |
3802 | to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras | |
3803 | become impossibly dangerous as they grow older'' but the claim here is | |
3804 | that they do not become fierce like a tiger. (1997, W. W. Norton and | |
3805 | Co., ISBN 0-393-03894-2, page 171)}, and binds the | |
3806 | variable @code{tiger} to the value @code{fierce}. In this example, | |
3807 | both values are symbols preceded by a quote. The values could just as | |
3808 | well have been another list or a string. The body of the @code{let} | |
3809 | follows after the list holding the variables. In this example, the | |
3810 | body is a list that uses the @code{message} function to print a string | |
3811 | in the echo area. | |
3812 | ||
3813 | @need 1500 | |
3814 | You may evaluate the example in the usual fashion, by placing the | |
3815 | cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do | |
3816 | this, the following will appear in the echo area: | |
3817 | ||
3818 | @smallexample | |
3819 | "One kind of animal has stripes and another is fierce." | |
3820 | @end smallexample | |
3821 | ||
3822 | As we have seen before, the @code{message} function prints its first | |
3823 | argument, except for @samp{%s}. In this example, the value of the variable | |
3824 | @code{zebra} is printed at the location of the first @samp{%s} and the | |
3825 | value of the variable @code{tiger} is printed at the location of the | |
3826 | second @samp{%s}. | |
3827 | ||
d6adf7e7 | 3828 | @node Uninitialized let Variables |
8cda6f8f GM |
3829 | @subsection Uninitialized Variables in a @code{let} Statement |
3830 | @cindex Uninitialized @code{let} variables | |
3831 | @cindex @code{let} variables uninitialized | |
3832 | ||
3833 | If you do not bind the variables in a @code{let} statement to specific | |
3834 | initial values, they will automatically be bound to an initial value of | |
3835 | @code{nil}, as in the following expression: | |
3836 | ||
3837 | @smallexample | |
3838 | @group | |
3839 | (let ((birch 3) | |
3840 | pine | |
3841 | fir | |
3842 | (oak 'some)) | |
3843 | (message | |
3844 | "Here are %d variables with %s, %s, and %s value." | |
3845 | birch pine fir oak)) | |
3846 | @end group | |
3847 | @end smallexample | |
3848 | ||
3849 | @noindent | |
3850 | Here, the varlist is @code{((birch 3) pine fir (oak 'some))}. | |
3851 | ||
3852 | @need 1250 | |
3853 | If you evaluate this expression in the usual way, the following will | |
3854 | appear in your echo area: | |
3855 | ||
3856 | @smallexample | |
3857 | "Here are 3 variables with nil, nil, and some value." | |
3858 | @end smallexample | |
3859 | ||
3860 | @noindent | |
3861 | In this example, Emacs binds the symbol @code{birch} to the number 3, | |
3862 | binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds | |
3863 | the symbol @code{oak} to the value @code{some}. | |
3864 | ||
3865 | Note that in the first part of the @code{let}, the variables @code{pine} | |
3866 | and @code{fir} stand alone as atoms that are not surrounded by | |
3867 | parentheses; this is because they are being bound to @code{nil}, the | |
3868 | empty list. But @code{oak} is bound to @code{some} and so is a part of | |
3869 | the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the | |
3870 | number 3 and so is in a list with that number. (Since a number | |
3871 | evaluates to itself, the number does not need to be quoted. Also, the | |
3872 | number is printed in the message using a @samp{%d} rather than a | |
3873 | @samp{%s}.) The four variables as a group are put into a list to | |
3874 | delimit them from the body of the @code{let}. | |
3875 | ||
d6adf7e7 | 3876 | @node if |
8cda6f8f GM |
3877 | @section The @code{if} Special Form |
3878 | @findex if | |
3879 | @cindex Conditional with @code{if} | |
3880 | ||
3881 | A third special form, in addition to @code{defun} and @code{let}, is the | |
3882 | conditional @code{if}. This form is used to instruct the computer to | |
3883 | make decisions. You can write function definitions without using | |
3884 | @code{if}, but it is used often enough, and is important enough, to be | |
3885 | included here. It is used, for example, in the code for the | |
3886 | function @code{beginning-of-buffer}. | |
3887 | ||
3888 | The basic idea behind an @code{if}, is that ``@emph{if} a test is true, | |
3889 | @emph{then} an expression is evaluated.'' If the test is not true, the | |
3890 | expression is not evaluated. For example, you might make a decision | |
3891 | such as, ``if it is warm and sunny, then go to the beach!'' | |
3892 | ||
3893 | @menu | |
3894 | * if in more detail:: | |
3895 | * type-of-animal in detail:: An example of an @code{if} expression. | |
3896 | @end menu | |
3897 | ||
8cda6f8f | 3898 | @ifnottex |
d6adf7e7 | 3899 | @node if in more detail |
8cda6f8f GM |
3900 | @unnumberedsubsec @code{if} in more detail |
3901 | @end ifnottex | |
3902 | ||
3903 | @cindex @samp{if-part} defined | |
3904 | @cindex @samp{then-part} defined | |
3905 | An @code{if} expression written in Lisp does not use the word `then'; | |
3906 | the test and the action are the second and third elements of the list | |
3907 | whose first element is @code{if}. Nonetheless, the test part of an | |
3908 | @code{if} expression is often called the @dfn{if-part} and the second | |
3909 | argument is often called the @dfn{then-part}. | |
3910 | ||
3911 | Also, when an @code{if} expression is written, the true-or-false-test | |
3912 | is usually written on the same line as the symbol @code{if}, but the | |
3913 | action to carry out if the test is true, the ``then-part'', is written | |
3914 | on the second and subsequent lines. This makes the @code{if} | |
3915 | expression easier to read. | |
3916 | ||
3917 | @smallexample | |
3918 | @group | |
3919 | (if @var{true-or-false-test} | |
3920 | @var{action-to-carry-out-if-test-is-true}) | |
3921 | @end group | |
3922 | @end smallexample | |
3923 | ||
3924 | @noindent | |
3925 | The true-or-false-test will be an expression that | |
3926 | is evaluated by the Lisp interpreter. | |
3927 | ||
3928 | Here is an example that you can evaluate in the usual manner. The test | |
3929 | is whether the number 5 is greater than the number 4. Since it is, the | |
3930 | message @samp{5 is greater than 4!} will be printed. | |
3931 | ||
3932 | @smallexample | |
3933 | @group | |
3934 | (if (> 5 4) ; @r{if-part} | |
3935 | (message "5 is greater than 4!")) ; @r{then-part} | |
3936 | @end group | |
3937 | @end smallexample | |
3938 | ||
3939 | @noindent | |
3940 | (The function @code{>} tests whether its first argument is greater than | |
3941 | its second argument and returns true if it is.) | |
3942 | @findex > (greater than) | |
3943 | ||
3944 | Of course, in actual use, the test in an @code{if} expression will not | |
3945 | be fixed for all time as it is by the expression @code{(> 5 4)}. | |
3946 | Instead, at least one of the variables used in the test will be bound to | |
3947 | a value that is not known ahead of time. (If the value were known ahead | |
3948 | of time, we would not need to run the test!) | |
3949 | ||
3950 | For example, the value may be bound to an argument of a function | |
3951 | definition. In the following function definition, the character of the | |
3952 | animal is a value that is passed to the function. If the value bound to | |
3953 | @code{characteristic} is @code{fierce}, then the message, @samp{It's a | |
3954 | tiger!} will be printed; otherwise, @code{nil} will be returned. | |
3955 | ||
3956 | @smallexample | |
3957 | @group | |
3958 | (defun type-of-animal (characteristic) | |
3959 | "Print message in echo area depending on CHARACTERISTIC. | |
3960 | If the CHARACTERISTIC is the symbol `fierce', | |
3961 | then warn of a tiger." | |
3962 | (if (equal characteristic 'fierce) | |
3963 | (message "It's a tiger!"))) | |
3964 | @end group | |
3965 | @end smallexample | |
3966 | ||
3967 | @need 1500 | |
3968 | @noindent | |
3969 | If you are reading this inside of GNU Emacs, you can evaluate the | |
3970 | function definition in the usual way to install it in Emacs, and then you | |
3971 | can evaluate the following two expressions to see the results: | |
3972 | ||
3973 | @smallexample | |
3974 | @group | |
3975 | (type-of-animal 'fierce) | |
3976 | ||
3977 | (type-of-animal 'zebra) | |
3978 | ||
3979 | @end group | |
3980 | @end smallexample | |
3981 | ||
3982 | @c Following sentences rewritten to prevent overfull hbox. | |
3983 | @noindent | |
3984 | When you evaluate @code{(type-of-animal 'fierce)}, you will see the | |
3985 | following message printed in the echo area: @code{"It's a tiger!"}; and | |
3986 | when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil} | |
3987 | printed in the echo area. | |
3988 | ||
d6adf7e7 | 3989 | @node type-of-animal in detail |
8cda6f8f GM |
3990 | @subsection The @code{type-of-animal} Function in Detail |
3991 | ||
3992 | Let's look at the @code{type-of-animal} function in detail. | |
3993 | ||
3994 | The function definition for @code{type-of-animal} was written by filling | |
3995 | the slots of two templates, one for a function definition as a whole, and | |
3996 | a second for an @code{if} expression. | |
3997 | ||
3998 | @need 1250 | |
3999 | The template for every function that is not interactive is: | |
4000 | ||
4001 | @smallexample | |
4002 | @group | |
4003 | (defun @var{name-of-function} (@var{argument-list}) | |
4004 | "@var{documentation}@dots{}" | |
4005 | @var{body}@dots{}) | |
4006 | @end group | |
4007 | @end smallexample | |
4008 | ||
4009 | @need 800 | |
4010 | The parts of the function that match this template look like this: | |
4011 | ||
4012 | @smallexample | |
4013 | @group | |
4014 | (defun type-of-animal (characteristic) | |
4015 | "Print message in echo area depending on CHARACTERISTIC. | |
4016 | If the CHARACTERISTIC is the symbol `fierce', | |
4017 | then warn of a tiger." | |
4018 | @var{body: the} @code{if} @var{expression}) | |
4019 | @end group | |
4020 | @end smallexample | |
4021 | ||
4022 | The name of function is @code{type-of-animal}; it is passed the value | |
4023 | of one argument. The argument list is followed by a multi-line | |
4024 | documentation string. The documentation string is included in the | |
4025 | example because it is a good habit to write documentation string for | |
4026 | every function definition. The body of the function definition | |
4027 | consists of the @code{if} expression. | |
4028 | ||
4029 | @need 800 | |
4030 | The template for an @code{if} expression looks like this: | |
4031 | ||
4032 | @smallexample | |
4033 | @group | |
4034 | (if @var{true-or-false-test} | |
4035 | @var{action-to-carry-out-if-the-test-returns-true}) | |
4036 | @end group | |
4037 | @end smallexample | |
4038 | ||
4039 | @need 1250 | |
4040 | In the @code{type-of-animal} function, the code for the @code{if} | |
4041 | looks like this: | |
4042 | ||
4043 | @smallexample | |
4044 | @group | |
4045 | (if (equal characteristic 'fierce) | |
4046 | (message "It's a tiger!"))) | |
4047 | @end group | |
4048 | @end smallexample | |
4049 | ||
4050 | @need 800 | |
4051 | Here, the true-or-false-test is the expression: | |
4052 | ||
4053 | @smallexample | |
4054 | (equal characteristic 'fierce) | |
4055 | @end smallexample | |
4056 | ||
4057 | @noindent | |
4058 | In Lisp, @code{equal} is a function that determines whether its first | |
4059 | argument is equal to its second argument. The second argument is the | |
4060 | quoted symbol @code{'fierce} and the first argument is the value of the | |
4061 | symbol @code{characteristic}---in other words, the argument passed to | |
4062 | this function. | |
4063 | ||
4064 | In the first exercise of @code{type-of-animal}, the argument | |
4065 | @code{fierce} is passed to @code{type-of-animal}. Since @code{fierce} | |
4066 | is equal to @code{fierce}, the expression, @code{(equal characteristic | |
4067 | 'fierce)}, returns a value of true. When this happens, the @code{if} | |
4068 | evaluates the second argument or then-part of the @code{if}: | |
4069 | @code{(message "It's tiger!")}. | |
4070 | ||
4071 | On the other hand, in the second exercise of @code{type-of-animal}, the | |
4072 | argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra} | |
4073 | is not equal to @code{fierce}, so the then-part is not evaluated and | |
4074 | @code{nil} is returned by the @code{if} expression. | |
4075 | ||
d6adf7e7 | 4076 | @node else |
8cda6f8f GM |
4077 | @section If--then--else Expressions |
4078 | @cindex Else | |
4079 | ||
4080 | An @code{if} expression may have an optional third argument, called | |
4081 | the @dfn{else-part}, for the case when the true-or-false-test returns | |
4082 | false. When this happens, the second argument or then-part of the | |
4083 | overall @code{if} expression is @emph{not} evaluated, but the third or | |
4084 | else-part @emph{is} evaluated. You might think of this as the cloudy | |
4085 | day alternative for the decision ``if it is warm and sunny, then go to | |
4086 | the beach, else read a book!''. | |
4087 | ||
4088 | The word ``else'' is not written in the Lisp code; the else-part of an | |
4089 | @code{if} expression comes after the then-part. In the written Lisp, the | |
4090 | else-part is usually written to start on a line of its own and is | |
4091 | indented less than the then-part: | |
4092 | ||
4093 | @smallexample | |
4094 | @group | |
4095 | (if @var{true-or-false-test} | |
4096 | @var{action-to-carry-out-if-the-test-returns-true} | |
4097 | @var{action-to-carry-out-if-the-test-returns-false}) | |
4098 | @end group | |
4099 | @end smallexample | |
4100 | ||
4101 | For example, the following @code{if} expression prints the message @samp{4 | |
4102 | is not greater than 5!} when you evaluate it in the usual way: | |
4103 | ||
4104 | @smallexample | |
4105 | @group | |
4106 | (if (> 4 5) ; @r{if-part} | |
4107 | (message "4 falsely greater than 5!") ; @r{then-part} | |
4108 | (message "4 is not greater than 5!")) ; @r{else-part} | |
4109 | @end group | |
4110 | @end smallexample | |
4111 | ||
4112 | @noindent | |
4113 | Note that the different levels of indentation make it easy to | |
4114 | distinguish the then-part from the else-part. (GNU Emacs has several | |
4115 | commands that automatically indent @code{if} expressions correctly. | |
4116 | @xref{Typing Lists, , GNU Emacs Helps You Type Lists}.) | |
4117 | ||
4118 | We can extend the @code{type-of-animal} function to include an | |
4119 | else-part by simply incorporating an additional part to the @code{if} | |
4120 | expression. | |
4121 | ||
4122 | @need 1500 | |
4123 | You can see the consequences of doing this if you evaluate the following | |
4124 | version of the @code{type-of-animal} function definition to install it | |
4125 | and then evaluate the two subsequent expressions to pass different | |
4126 | arguments to the function. | |
4127 | ||
4128 | @smallexample | |
4129 | @group | |
4130 | (defun type-of-animal (characteristic) ; @r{Second version.} | |
4131 | "Print message in echo area depending on CHARACTERISTIC. | |
4132 | If the CHARACTERISTIC is the symbol `fierce', | |
4133 | then warn of a tiger; | |
4134 | else say it's not fierce." | |
4135 | (if (equal characteristic 'fierce) | |
4136 | (message "It's a tiger!") | |
4137 | (message "It's not fierce!"))) | |
4138 | @end group | |
4139 | @end smallexample | |
4140 | @sp 1 | |
4141 | ||
4142 | @smallexample | |
4143 | @group | |
4144 | (type-of-animal 'fierce) | |
4145 | ||
4146 | (type-of-animal 'zebra) | |
4147 | ||
4148 | @end group | |
4149 | @end smallexample | |
4150 | ||
4151 | @c Following sentence rewritten to prevent overfull hbox. | |
4152 | @noindent | |
4153 | When you evaluate @code{(type-of-animal 'fierce)}, you will see the | |
4154 | following message printed in the echo area: @code{"It's a tiger!"}; but | |
4155 | when you evaluate @code{(type-of-animal 'zebra)}, you will see | |
4156 | @code{"It's not fierce!"}. | |
4157 | ||
4158 | (Of course, if the @var{characteristic} were @code{ferocious}, the | |
4159 | message @code{"It's not fierce!"} would be printed; and it would be | |
4160 | misleading! When you write code, you need to take into account the | |
4161 | possibility that some such argument will be tested by the @code{if} | |
4162 | and write your program accordingly.) | |
4163 | ||
d6adf7e7 | 4164 | @node Truth & Falsehood |
8cda6f8f GM |
4165 | @section Truth and Falsehood in Emacs Lisp |
4166 | @cindex Truth and falsehood in Emacs Lisp | |
4167 | @cindex Falsehood and truth in Emacs Lisp | |
4168 | @findex nil | |
4169 | ||
4170 | There is an important aspect to the truth test in an @code{if} | |
4171 | expression. So far, we have spoken of `true' and `false' as values of | |
4172 | predicates as if they were new kinds of Emacs Lisp objects. In fact, | |
4173 | `false' is just our old friend @code{nil}. Anything else---anything | |
4174 | at all---is `true'. | |
4175 | ||
4176 | The expression that tests for truth is interpreted as @dfn{true} | |
4177 | if the result of evaluating it is a value that is not @code{nil}. In | |
4178 | other words, the result of the test is considered true if the value | |
4179 | returned is a number such as 47, a string such as @code{"hello"}, or a | |
4180 | symbol (other than @code{nil}) such as @code{flowers}, or a list (so | |
4181 | long as it is not empty), or even a buffer! | |
4182 | ||
4183 | @menu | |
4184 | * nil explained:: @code{nil} has two meanings. | |
4185 | @end menu | |
4186 | ||
8cda6f8f | 4187 | @ifnottex |
d6adf7e7 | 4188 | @node nil explained |
8cda6f8f GM |
4189 | @unnumberedsubsec An explanation of @code{nil} |
4190 | @end ifnottex | |
4191 | ||
4192 | Before illustrating a test for truth, we need an explanation of @code{nil}. | |
4193 | ||
4194 | In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the | |
4195 | empty list. Second, it means false and is the value returned when a | |
4196 | true-or-false-test tests false. @code{nil} can be written as an empty | |
4197 | list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is | |
4198 | concerned, @code{()} and @code{nil} are the same. Humans, however, tend | |
4199 | to use @code{nil} for false and @code{()} for the empty list. | |
4200 | ||
4201 | In Emacs Lisp, any value that is not @code{nil}---is not the empty | |
4202 | list---is considered true. This means that if an evaluation returns | |
4203 | something that is not an empty list, an @code{if} expression will test | |
4204 | true. For example, if a number is put in the slot for the test, it | |
4205 | will be evaluated and will return itself, since that is what numbers | |
4206 | do when evaluated. In this conditional, the @code{if} expression will | |
4207 | test true. The expression tests false only when @code{nil}, an empty | |
4208 | list, is returned by evaluating the expression. | |
4209 | ||
4210 | You can see this by evaluating the two expressions in the following examples. | |
4211 | ||
4212 | In the first example, the number 4 is evaluated as the test in the | |
4213 | @code{if} expression and returns itself; consequently, the then-part | |
4214 | of the expression is evaluated and returned: @samp{true} appears in | |
4215 | the echo area. In the second example, the @code{nil} indicates false; | |
4216 | consequently, the else-part of the expression is evaluated and | |
4217 | returned: @samp{false} appears in the echo area. | |
4218 | ||
4219 | @smallexample | |
4220 | @group | |
4221 | (if 4 | |
4222 | 'true | |
4223 | 'false) | |
4224 | @end group | |
4225 | ||
4226 | @group | |
4227 | (if nil | |
4228 | 'true | |
4229 | 'false) | |
4230 | @end group | |
4231 | @end smallexample | |
4232 | ||
4233 | @need 1250 | |
4234 | Incidentally, if some other useful value is not available for a test that | |
4235 | returns true, then the Lisp interpreter will return the symbol @code{t} | |
4236 | for true. For example, the expression @code{(> 5 4)} returns @code{t} | |
4237 | when evaluated, as you can see by evaluating it in the usual way: | |
4238 | ||
4239 | @smallexample | |
4240 | (> 5 4) | |
4241 | @end smallexample | |
4242 | ||
4243 | @need 1250 | |
4244 | @noindent | |
4245 | On the other hand, this function returns @code{nil} if the test is false. | |
4246 | ||
4247 | @smallexample | |
4248 | (> 4 5) | |
4249 | @end smallexample | |
4250 | ||
d6adf7e7 | 4251 | @node save-excursion |
8cda6f8f GM |
4252 | @section @code{save-excursion} |
4253 | @findex save-excursion | |
4254 | @cindex Region, what it is | |
4255 | @cindex Preserving point, mark, and buffer | |
4256 | @cindex Point, mark, buffer preservation | |
4257 | @findex point | |
4258 | @findex mark | |
4259 | ||
767b8eae | 4260 | The @code{save-excursion} function is the third and final special form |
8cda6f8f GM |
4261 | that we will discuss in this chapter. |
4262 | ||
4263 | In Emacs Lisp programs used for editing, the @code{save-excursion} | |
4264 | function is very common. It saves the location of point and mark, | |
4265 | executes the body of the function, and then restores point and mark to | |
4266 | their previous positions if their locations were changed. Its primary | |
4267 | purpose is to keep the user from being surprised and disturbed by | |
4268 | unexpected movement of point or mark. | |
4269 | ||
4270 | @menu | |
4271 | * Point and mark:: A review of various locations. | |
4272 | * Template for save-excursion:: | |
4273 | @end menu | |
4274 | ||
8cda6f8f | 4275 | @ifnottex |
d6adf7e7 | 4276 | @node Point and mark |
8cda6f8f GM |
4277 | @unnumberedsubsec Point and Mark |
4278 | @end ifnottex | |
4279 | ||
4280 | Before discussing @code{save-excursion}, however, it may be useful | |
4281 | first to review what point and mark are in GNU Emacs. @dfn{Point} is | |
4282 | the current location of the cursor. Wherever the cursor | |
4283 | is, that is point. More precisely, on terminals where the cursor | |
4284 | appears to be on top of a character, point is immediately before the | |
4285 | character. In Emacs Lisp, point is an integer. The first character in | |
4286 | a buffer is number one, the second is number two, and so on. The | |
4287 | function @code{point} returns the current position of the cursor as a | |
4288 | number. Each buffer has its own value for point. | |
4289 | ||
4290 | The @dfn{mark} is another position in the buffer; its value can be set | |
4291 | with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If | |
4292 | a mark has been set, you can use the command @kbd{C-x C-x} | |
4293 | (@code{exchange-point-and-mark}) to cause the cursor to jump to the mark | |
4294 | and set the mark to be the previous position of point. In addition, if | |
4295 | you set another mark, the position of the previous mark is saved in the | |
4296 | mark ring. Many mark positions can be saved this way. You can jump the | |
4297 | cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more | |
4298 | times. | |
4299 | ||
4300 | The part of the buffer between point and mark is called @dfn{the | |
4301 | region}. Numerous commands work on the region, including | |
4302 | @code{center-region}, @code{count-lines-region}, @code{kill-region}, and | |
4303 | @code{print-region}. | |
4304 | ||
4305 | The @code{save-excursion} special form saves the locations of point and | |
4306 | mark and restores those positions after the code within the body of the | |
4307 | special form is evaluated by the Lisp interpreter. Thus, if point were | |
4308 | in the beginning of a piece of text and some code moved point to the end | |
4309 | of the buffer, the @code{save-excursion} would put point back to where | |
4310 | it was before, after the expressions in the body of the function were | |
4311 | evaluated. | |
4312 | ||
4313 | In Emacs, a function frequently moves point as part of its internal | |
4314 | workings even though a user would not expect this. For example, | |
4315 | @code{count-lines-region} moves point. To prevent the user from being | |
4316 | bothered by jumps that are both unexpected and (from the user's point of | |
4317 | view) unnecessary, @code{save-excursion} is often used to keep point and | |
4318 | mark in the location expected by the user. The use of | |
4319 | @code{save-excursion} is good housekeeping. | |
4320 | ||
4321 | To make sure the house stays clean, @code{save-excursion} restores the | |
4322 | values of point and mark even if something goes wrong in the code inside | |
4323 | of it (or, to be more precise and to use the proper jargon, ``in case of | |
4324 | abnormal exit''). This feature is very helpful. | |
4325 | ||
4326 | In addition to recording the values of point and mark, | |
4327 | @code{save-excursion} keeps track of the current buffer, and restores | |
4328 | it, too. This means you can write code that will change the buffer and | |
4329 | have @code{save-excursion} switch you back to the original buffer. | |
4330 | This is how @code{save-excursion} is used in @code{append-to-buffer}. | |
4331 | (@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) | |
4332 | ||
d6adf7e7 | 4333 | @node Template for save-excursion |
8cda6f8f GM |
4334 | @subsection Template for a @code{save-excursion} Expression |
4335 | ||
4336 | @need 800 | |
4337 | The template for code using @code{save-excursion} is simple: | |
4338 | ||
4339 | @smallexample | |
4340 | @group | |
4341 | (save-excursion | |
4342 | @var{body}@dots{}) | |
4343 | @end group | |
4344 | @end smallexample | |
4345 | ||
4346 | @noindent | |
4347 | The body of the function is one or more expressions that will be | |
4348 | evaluated in sequence by the Lisp interpreter. If there is more than | |
4349 | one expression in the body, the value of the last one will be returned | |
4350 | as the value of the @code{save-excursion} function. The other | |
4351 | expressions in the body are evaluated only for their side effects; and | |
4352 | @code{save-excursion} itself is used only for its side effect (which | |
4353 | is restoring the positions of point and mark). | |
4354 | ||
4355 | @need 1250 | |
4356 | In more detail, the template for a @code{save-excursion} expression | |
4357 | looks like this: | |
4358 | ||
4359 | @smallexample | |
4360 | @group | |
4361 | (save-excursion | |
4362 | @var{first-expression-in-body} | |
4363 | @var{second-expression-in-body} | |
4364 | @var{third-expression-in-body} | |
4365 | @dots{} | |
4366 | @var{last-expression-in-body}) | |
4367 | @end group | |
4368 | @end smallexample | |
4369 | ||
4370 | @noindent | |
4371 | An expression, of course, may be a symbol on its own or a list. | |
4372 | ||
4373 | In Emacs Lisp code, a @code{save-excursion} expression often occurs | |
4374 | within the body of a @code{let} expression. It looks like this: | |
4375 | ||
4376 | @smallexample | |
4377 | @group | |
4378 | (let @var{varlist} | |
4379 | (save-excursion | |
4380 | @var{body}@dots{})) | |
4381 | @end group | |
4382 | @end smallexample | |
4383 | ||
d6adf7e7 | 4384 | @node Review |
8cda6f8f GM |
4385 | @section Review |
4386 | ||
767b8eae XF |
4387 | In the last few chapters we have introduced a macro and a fair number |
4388 | of functions and special forms. Here they are described in brief, | |
4389 | along with a few similar functions that have not been mentioned yet. | |
8cda6f8f GM |
4390 | |
4391 | @table @code | |
4392 | @item eval-last-sexp | |
4393 | Evaluate the last symbolic expression before the current location of | |
4394 | point. The value is printed in the echo area unless the function is | |
4395 | invoked with an argument; in that case, the output is printed in the | |
4396 | current buffer. This command is normally bound to @kbd{C-x C-e}. | |
4397 | ||
4398 | @item defun | |
767b8eae XF |
4399 | Define function. This macro has up to five parts: the name, a |
4400 | template for the arguments that will be passed to the function, | |
4401 | documentation, an optional interactive declaration, and the body of | |
4402 | the definition. | |
8cda6f8f GM |
4403 | |
4404 | @need 1250 | |
4405 | For example, in an early version of Emacs, the function definition was | |
4406 | as follows. (It is slightly more complex now that it seeks the first | |
4407 | non-whitespace character rather than the first visible character.) | |
4408 | ||
4409 | @smallexample | |
4410 | @group | |
4411 | (defun back-to-indentation () | |
4412 | "Move point to first visible character on line." | |
4413 | (interactive) | |
4414 | (beginning-of-line 1) | |
4415 | (skip-chars-forward " \t")) | |
4416 | @end group | |
4417 | @end smallexample | |
4418 | ||
4419 | @ignore | |
4420 | In GNU Emacs 22, | |
4421 | ||
4422 | (defun backward-to-indentation (&optional arg) | |
4423 | "Move backward ARG lines and position at first nonblank character." | |
4424 | (interactive "p") | |
4425 | (forward-line (- (or arg 1))) | |
4426 | (skip-chars-forward " \t")) | |
4427 | ||
4428 | (defun back-to-indentation () | |
4429 | "Move point to the first non-whitespace character on this line." | |
4430 | (interactive) | |
4431 | (beginning-of-line 1) | |
4432 | (skip-syntax-forward " " (line-end-position)) | |
4433 | ;; Move back over chars that have whitespace syntax but have the p flag. | |
4434 | (backward-prefix-chars)) | |
4435 | @end ignore | |
4436 | ||
4437 | @item interactive | |
4438 | Declare to the interpreter that the function can be used | |
4439 | interactively. This special form may be followed by a string with one | |
4440 | or more parts that pass the information to the arguments of the | |
4441 | function, in sequence. These parts may also tell the interpreter to | |
4442 | prompt for information. Parts of the string are separated by | |
4443 | newlines, @samp{\n}. | |
4444 | ||
4445 | @need 1000 | |
4446 | Common code characters are: | |
4447 | ||
4448 | @table @code | |
4449 | @item b | |
4450 | The name of an existing buffer. | |
4451 | ||
4452 | @item f | |
4453 | The name of an existing file. | |
4454 | ||
4455 | @item p | |
4456 | The numeric prefix argument. (Note that this `p' is lower case.) | |
4457 | ||
4458 | @item r | |
4459 | Point and the mark, as two numeric arguments, smallest first. This | |
4460 | is the only code letter that specifies two successive arguments | |
4461 | rather than one. | |
4462 | @end table | |
4463 | ||
4464 | @xref{Interactive Codes, , Code Characters for @samp{interactive}, | |
4465 | elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of | |
4466 | code characters. | |
4467 | ||
4468 | @item let | |
4469 | Declare that a list of variables is for use within the body of the | |
4470 | @code{let} and give them an initial value, either @code{nil} or a | |
4471 | specified value; then evaluate the rest of the expressions in the body | |
4472 | of the @code{let} and return the value of the last one. Inside the | |
4473 | body of the @code{let}, the Lisp interpreter does not see the values of | |
4474 | the variables of the same names that are bound outside of the | |
4475 | @code{let}. | |
4476 | ||
4477 | @need 1250 | |
4478 | For example, | |
4479 | ||
4480 | @smallexample | |
4481 | @group | |
4482 | (let ((foo (buffer-name)) | |
4483 | (bar (buffer-size))) | |
4484 | (message | |
4485 | "This buffer is %s and has %d characters." | |
4486 | foo bar)) | |
4487 | @end group | |
4488 | @end smallexample | |
4489 | ||
4490 | @item save-excursion | |
4491 | Record the values of point and mark and the current buffer before | |
4492 | evaluating the body of this special form. Restore the values of point | |
4493 | and mark and buffer afterward. | |
4494 | ||
4495 | @need 1250 | |
4496 | For example, | |
4497 | ||
4498 | @smallexample | |
4499 | @group | |
4500 | (message "We are %d characters into this buffer." | |
4501 | (- (point) | |
4502 | (save-excursion | |
4503 | (goto-char (point-min)) (point)))) | |
4504 | @end group | |
4505 | @end smallexample | |
4506 | ||
4507 | @item if | |
4508 | Evaluate the first argument to the function; if it is true, evaluate | |
4509 | the second argument; else evaluate the third argument, if there is one. | |
4510 | ||
4511 | The @code{if} special form is called a @dfn{conditional}. There are | |
4512 | other conditionals in Emacs Lisp, but @code{if} is perhaps the most | |
4513 | commonly used. | |
4514 | ||
4515 | @need 1250 | |
4516 | For example, | |
4517 | ||
4518 | @smallexample | |
4519 | @group | |
4520 | (if (= 22 emacs-major-version) | |
4521 | (message "This is version 22 Emacs") | |
4522 | (message "This is not version 22 Emacs")) | |
4523 | @end group | |
4524 | @end smallexample | |
4525 | ||
4526 | @need 1250 | |
4527 | @item < | |
4528 | @itemx > | |
4529 | @itemx <= | |
4530 | @itemx >= | |
4531 | The @code{<} function tests whether its first argument is smaller than | |
4532 | its second argument. A corresponding function, @code{>}, tests whether | |
4533 | the first argument is greater than the second. Likewise, @code{<=} | |
4534 | tests whether the first argument is less than or equal to the second and | |
4535 | @code{>=} tests whether the first argument is greater than or equal to | |
4536 | the second. In all cases, both arguments must be numbers or markers | |
4537 | (markers indicate positions in buffers). | |
4538 | ||
4539 | @need 800 | |
4540 | @item = | |
4541 | The @code{=} function tests whether two arguments, both numbers or | |
4542 | markers, are equal. | |
4543 | ||
4544 | @need 1250 | |
4545 | @item equal | |
4546 | @itemx eq | |
4547 | Test whether two objects are the same. @code{equal} uses one meaning | |
4548 | of the word `same' and @code{eq} uses another: @code{equal} returns | |
4549 | true if the two objects have a similar structure and contents, such as | |
4550 | two copies of the same book. On the other hand, @code{eq}, returns | |
4551 | true if both arguments are actually the same object. | |
4552 | @findex equal | |
4553 | @findex eq | |
4554 | ||
4555 | @need 1250 | |
4556 | @item string< | |
4557 | @itemx string-lessp | |
4558 | @itemx string= | |
4559 | @itemx string-equal | |
4560 | The @code{string-lessp} function tests whether its first argument is | |
4561 | smaller than the second argument. A shorter, alternative name for the | |
4562 | same function (a @code{defalias}) is @code{string<}. | |
4563 | ||
4564 | The arguments to @code{string-lessp} must be strings or symbols; the | |
4565 | ordering is lexicographic, so case is significant. The print names of | |
4566 | symbols are used instead of the symbols themselves. | |
4567 | ||
4568 | @cindex @samp{empty string} defined | |
4569 | An empty string, @samp{""}, a string with no characters in it, is | |
4570 | smaller than any string of characters. | |
4571 | ||
4572 | @code{string-equal} provides the corresponding test for equality. Its | |
4573 | shorter, alternative name is @code{string=}. There are no string test | |
4574 | functions that correspond to @var{>}, @code{>=}, or @code{<=}. | |
4575 | ||
4576 | @item message | |
4577 | Print a message in the echo area. The first argument is a string that | |
4578 | can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of | |
4579 | arguments that follow the string. The argument used by @samp{%s} must | |
4580 | be a string or a symbol; the argument used by @samp{%d} must be a | |
4581 | number. The argument used by @samp{%c} must be an @sc{ascii} code | |
4582 | number; it will be printed as the character with that @sc{ascii} code. | |
4583 | (Various other %-sequences have not been mentioned.) | |
4584 | ||
4585 | @item setq | |
4586 | @itemx set | |
4587 | The @code{setq} function sets the value of its first argument to the | |
4588 | value of the second argument. The first argument is automatically | |
4589 | quoted by @code{setq}. It does the same for succeeding pairs of | |
4590 | arguments. Another function, @code{set}, takes only two arguments and | |
4591 | evaluates both of them before setting the value returned by its first | |
4592 | argument to the value returned by its second argument. | |
4593 | ||
4594 | @item buffer-name | |
4595 | Without an argument, return the name of the buffer, as a string. | |
4596 | ||
2fce4cd8 | 4597 | @item buffer-file-name |
8cda6f8f GM |
4598 | Without an argument, return the name of the file the buffer is |
4599 | visiting. | |
4600 | ||
4601 | @item current-buffer | |
4602 | Return the buffer in which Emacs is active; it may not be | |
4603 | the buffer that is visible on the screen. | |
4604 | ||
4605 | @item other-buffer | |
4606 | Return the most recently selected buffer (other than the buffer passed | |
4607 | to @code{other-buffer} as an argument and other than the current | |
4608 | buffer). | |
4609 | ||
4610 | @item switch-to-buffer | |
4611 | Select a buffer for Emacs to be active in and display it in the current | |
4612 | window so users can look at it. Usually bound to @kbd{C-x b}. | |
4613 | ||
4614 | @item set-buffer | |
44e97401 | 4615 | Switch Emacs's attention to a buffer on which programs will run. Don't |
8cda6f8f GM |
4616 | alter what the window is showing. |
4617 | ||
4618 | @item buffer-size | |
4619 | Return the number of characters in the current buffer. | |
4620 | ||
4621 | @item point | |
4622 | Return the value of the current position of the cursor, as an | |
4623 | integer counting the number of characters from the beginning of the | |
4624 | buffer. | |
4625 | ||
4626 | @item point-min | |
4627 | Return the minimum permissible value of point in | |
4628 | the current buffer. This is 1, unless narrowing is in effect. | |
4629 | ||
4630 | @item point-max | |
4631 | Return the value of the maximum permissible value of point in the | |
4632 | current buffer. This is the end of the buffer, unless narrowing is in | |
4633 | effect. | |
4634 | @end table | |
4635 | ||
4636 | @need 1500 | |
d6adf7e7 | 4637 | @node defun Exercises |
8cda6f8f GM |
4638 | @section Exercises |
4639 | ||
4640 | @itemize @bullet | |
4641 | @item | |
4642 | Write a non-interactive function that doubles the value of its | |
4643 | argument, a number. Make that function interactive. | |
4644 | ||
4645 | @item | |
4646 | Write a function that tests whether the current value of | |
4647 | @code{fill-column} is greater than the argument passed to the function, | |
4648 | and if so, prints an appropriate message. | |
4649 | @end itemize | |
4650 | ||
d6adf7e7 | 4651 | @node Buffer Walk Through |
8cda6f8f GM |
4652 | @chapter A Few Buffer--Related Functions |
4653 | ||
4654 | In this chapter we study in detail several of the functions used in GNU | |
4655 | Emacs. This is called a ``walk-through''. These functions are used as | |
4656 | examples of Lisp code, but are not imaginary examples; with the | |
4657 | exception of the first, simplified function definition, these functions | |
4658 | show the actual code used in GNU Emacs. You can learn a great deal from | |
4659 | these definitions. The functions described here are all related to | |
4660 | buffers. Later, we will study other functions. | |
4661 | ||
4662 | @menu | |
4663 | * Finding More:: How to find more information. | |
4664 | * simplified-beginning-of-buffer:: Shows @code{goto-char}, | |
4665 | @code{point-min}, and @code{push-mark}. | |
4666 | * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. | |
4667 | * append-to-buffer:: Uses @code{save-excursion} and | |
4668 | @code{insert-buffer-substring}. | |
4669 | * Buffer Related Review:: Review. | |
4670 | * Buffer Exercises:: | |
4671 | @end menu | |
4672 | ||
d6adf7e7 | 4673 | @node Finding More |
8cda6f8f GM |
4674 | @section Finding More Information |
4675 | ||
4676 | @findex describe-function, @r{introduced} | |
4677 | @cindex Find function documentation | |
4678 | In this walk-through, I will describe each new function as we come to | |
4679 | it, sometimes in detail and sometimes briefly. If you are interested, | |
4680 | you can get the full documentation of any Emacs Lisp function at any | |
4681 | time by typing @kbd{C-h f} and then the name of the function (and then | |
4682 | @key{RET}). Similarly, you can get the full documentation for a | |
4683 | variable by typing @kbd{C-h v} and then the name of the variable (and | |
4684 | then @key{RET}). | |
4685 | ||
4686 | @cindex Find source of function | |
4687 | @c In version 22, tells location both of C and of Emacs Lisp | |
4688 | Also, @code{describe-function} will tell you the location of the | |
4689 | function definition. | |
4690 | ||
4691 | Put point into the name of the file that contains the function and | |
4692 | press the @key{RET} key. In this case, @key{RET} means | |
4693 | @code{push-button} rather than `return' or `enter'. Emacs will take | |
4694 | you directly to the function definition. | |
4695 | ||
4696 | @ignore | |
4697 | Not In version 22 | |
4698 | ||
4699 | If you move point over the file name and press | |
4700 | the @key{RET} key, which in this case means @code{help-follow} rather | |
4701 | than `return' or `enter', Emacs will take you directly to the function | |
4702 | definition. | |
4703 | @end ignore | |
4704 | ||
4705 | More generally, if you want to see a function in its original source | |
88c26f5c GM |
4706 | file, you can use the @code{find-tag} function to jump to it. |
4707 | @code{find-tag} works with a wide variety of languages, not just | |
8cda6f8f | 4708 | Lisp, and C, and it works with non-programming text as well. For |
88c26f5c | 4709 | example, @code{find-tag} will jump to the various nodes in the |
8cda6f8f | 4710 | Texinfo source file of this document. |
88c26f5c | 4711 | The @code{find-tag} function depends on `tags tables' that record |
8cda6f8f | 4712 | the locations of the functions, variables, and other items to which |
88c26f5c | 4713 | @code{find-tag} jumps. |
8cda6f8f | 4714 | |
88c26f5c | 4715 | To use the @code{find-tag} command, type @kbd{M-.} (i.e., press the |
8cda6f8f GM |
4716 | period key while holding down the @key{META} key, or else type the |
4717 | @key{ESC} key and then type the period key), and then, at the prompt, | |
4718 | type in the name of the function whose source code you want to see, | |
4719 | such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will | |
4720 | switch buffers and display the source code for the function on your | |
4721 | screen. To switch back to your current buffer, type @kbd{C-x b | |
09e80d9f | 4722 | @key{RET}}. (On some keyboards, the @key{META} key is labeled |
8cda6f8f GM |
4723 | @key{ALT}.) |
4724 | ||
4725 | @c !!! 22.1.1 tags table location in this paragraph | |
4726 | @cindex TAGS table, specifying | |
88c26f5c | 4727 | @findex find-tag |
8cda6f8f GM |
4728 | Depending on how the initial default values of your copy of Emacs are |
4729 | set, you may also need to specify the location of your `tags table', | |
4730 | which is a file called @file{TAGS}. For example, if you are | |
4731 | interested in Emacs sources, the tags table you will most likely want, | |
4732 | if it has already been created for you, will be in a subdirectory of | |
4733 | the @file{/usr/local/share/emacs/} directory; thus you would use the | |
4734 | @code{M-x visit-tags-table} command and specify a pathname such as | |
4735 | @file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table | |
4736 | has not already been created, you will have to create it yourself. It | |
0ca10bb7 | 4737 | will be in a file such as @file{/usr/local/src/emacs/src/TAGS}. |
8cda6f8f GM |
4738 | |
4739 | @need 1250 | |
4740 | To create a @file{TAGS} file in a specific directory, switch to that | |
4741 | directory in Emacs using @kbd{M-x cd} command, or list the directory | |
4742 | with @kbd{C-x d} (@code{dired}). Then run the compile command, with | |
4743 | @w{@code{etags *.el}} as the command to execute: | |
4744 | ||
4745 | @smallexample | |
4746 | M-x compile RET etags *.el RET | |
4747 | @end smallexample | |
4748 | ||
4749 | For more information, see @ref{etags, , Create Your Own @file{TAGS} File}. | |
4750 | ||
4751 | After you become more familiar with Emacs Lisp, you will find that you will | |
88c26f5c | 4752 | frequently use @code{find-tag} to navigate your way around source code; |
8cda6f8f GM |
4753 | and you will create your own @file{TAGS} tables. |
4754 | ||
4755 | @cindex Library, as term for `file' | |
4756 | Incidentally, the files that contain Lisp code are conventionally | |
4757 | called @dfn{libraries}. The metaphor is derived from that of a | |
4758 | specialized library, such as a law library or an engineering library, | |
4759 | rather than a general library. Each library, or file, contains | |
4760 | functions that relate to a particular topic or activity, such as | |
4761 | @file{abbrev.el} for handling abbreviations and other typing | |
4762 | shortcuts, and @file{help.el} for on-line help. (Sometimes several | |
4763 | libraries provide code for a single activity, as the various | |
4764 | @file{rmail@dots{}} files provide code for reading electronic mail.) | |
4765 | In @cite{The GNU Emacs Manual}, you will see sentences such as ``The | |
4766 | @kbd{C-h p} command lets you search the standard Emacs Lisp libraries | |
4767 | by topic keywords.'' | |
4768 | ||
d6adf7e7 | 4769 | @node simplified-beginning-of-buffer |
8cda6f8f GM |
4770 | @section A Simplified @code{beginning-of-buffer} Definition |
4771 | @findex simplified-beginning-of-buffer | |
4772 | ||
4773 | The @code{beginning-of-buffer} command is a good function to start with | |
4774 | since you are likely to be familiar with it and it is easy to | |
4775 | understand. Used as an interactive command, @code{beginning-of-buffer} | |
4776 | moves the cursor to the beginning of the buffer, leaving the mark at the | |
4777 | previous position. It is generally bound to @kbd{M-<}. | |
4778 | ||
4779 | In this section, we will discuss a shortened version of the function | |
4780 | that shows how it is most frequently used. This shortened function | |
4781 | works as written, but it does not contain the code for a complex option. | |
4782 | In another section, we will describe the entire function. | |
4783 | (@xref{beginning-of-buffer, , Complete Definition of | |
4784 | @code{beginning-of-buffer}}.) | |
4785 | ||
4786 | Before looking at the code, let's consider what the function | |
4787 | definition has to contain: it must include an expression that makes | |
4788 | the function interactive so it can be called by typing @kbd{M-x | |
4789 | beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it | |
4790 | must include code to leave a mark at the original position in the | |
4791 | buffer; and it must include code to move the cursor to the beginning | |
4792 | of the buffer. | |
4793 | ||
4794 | @need 1250 | |
4795 | Here is the complete text of the shortened version of the function: | |
4796 | ||
4797 | @smallexample | |
4798 | @group | |
4799 | (defun simplified-beginning-of-buffer () | |
4800 | "Move point to the beginning of the buffer; | |
4801 | leave mark at previous position." | |
4802 | (interactive) | |
4803 | (push-mark) | |
4804 | (goto-char (point-min))) | |
4805 | @end group | |
4806 | @end smallexample | |
4807 | ||
4808 | Like all function definitions, this definition has five parts following | |
767b8eae | 4809 | the macro @code{defun}: |
8cda6f8f GM |
4810 | |
4811 | @enumerate | |
4812 | @item | |
4813 | The name: in this example, @code{simplified-beginning-of-buffer}. | |
4814 | ||
4815 | @item | |
4816 | A list of the arguments: in this example, an empty list, @code{()}, | |
4817 | ||
4818 | @item | |
4819 | The documentation string. | |
4820 | ||
4821 | @item | |
4822 | The interactive expression. | |
4823 | ||
4824 | @item | |
4825 | The body. | |
4826 | @end enumerate | |
4827 | ||
4828 | @noindent | |
4829 | In this function definition, the argument list is empty; this means that | |
4830 | this function does not require any arguments. (When we look at the | |
4831 | definition for the complete function, we will see that it may be passed | |
4832 | an optional argument.) | |
4833 | ||
4834 | The interactive expression tells Emacs that the function is intended to | |
4835 | be used interactively. In this example, @code{interactive} does not have | |
4836 | an argument because @code{simplified-beginning-of-buffer} does not | |
4837 | require one. | |
4838 | ||
4839 | @need 800 | |
4840 | The body of the function consists of the two lines: | |
4841 | ||
4842 | @smallexample | |
4843 | @group | |
4844 | (push-mark) | |
4845 | (goto-char (point-min)) | |
4846 | @end group | |
4847 | @end smallexample | |
4848 | ||
4849 | The first of these lines is the expression, @code{(push-mark)}. When | |
4850 | this expression is evaluated by the Lisp interpreter, it sets a mark at | |
4851 | the current position of the cursor, wherever that may be. The position | |
4852 | of this mark is saved in the mark ring. | |
4853 | ||
4854 | The next line is @code{(goto-char (point-min))}. This expression | |
4855 | jumps the cursor to the minimum point in the buffer, that is, to the | |
4856 | beginning of the buffer (or to the beginning of the accessible portion | |
4857 | of the buffer if it is narrowed. @xref{Narrowing & Widening, , | |
4858 | Narrowing and Widening}.) | |
4859 | ||
4860 | The @code{push-mark} command sets a mark at the place where the cursor | |
4861 | was located before it was moved to the beginning of the buffer by the | |
4862 | @code{(goto-char (point-min))} expression. Consequently, you can, if | |
4863 | you wish, go back to where you were originally by typing @kbd{C-x C-x}. | |
4864 | ||
4865 | That is all there is to the function definition! | |
4866 | ||
4867 | @findex describe-function | |
4868 | When you are reading code such as this and come upon an unfamiliar | |
4869 | function, such as @code{goto-char}, you can find out what it does by | |
4870 | using the @code{describe-function} command. To use this command, type | |
4871 | @kbd{C-h f} and then type in the name of the function and press | |
4872 | @key{RET}. The @code{describe-function} command will print the | |
4873 | function's documentation string in a @file{*Help*} window. For | |
4874 | example, the documentation for @code{goto-char} is: | |
4875 | ||
4876 | @smallexample | |
4877 | @group | |
4878 | Set point to POSITION, a number or marker. | |
4879 | Beginning of buffer is position (point-min), end is (point-max). | |
4880 | @end group | |
4881 | @end smallexample | |
4882 | ||
4883 | @noindent | |
4884 | The function's one argument is the desired position. | |
4885 | ||
4886 | @noindent | |
4887 | (The prompt for @code{describe-function} will offer you the symbol | |
4888 | under or preceding the cursor, so you can save typing by positioning | |
4889 | the cursor right over or after the function and then typing @kbd{C-h f | |
4890 | @key{RET}}.) | |
4891 | ||
4892 | The @code{end-of-buffer} function definition is written in the same way as | |
4893 | the @code{beginning-of-buffer} definition except that the body of the | |
4894 | function contains the expression @code{(goto-char (point-max))} in place | |
4895 | of @code{(goto-char (point-min))}. | |
4896 | ||
d6adf7e7 | 4897 | @node mark-whole-buffer |
8cda6f8f GM |
4898 | @section The Definition of @code{mark-whole-buffer} |
4899 | @findex mark-whole-buffer | |
4900 | ||
4901 | The @code{mark-whole-buffer} function is no harder to understand than the | |
4902 | @code{simplified-beginning-of-buffer} function. In this case, however, | |
4903 | we will look at the complete function, not a shortened version. | |
4904 | ||
4905 | The @code{mark-whole-buffer} function is not as commonly used as the | |
4906 | @code{beginning-of-buffer} function, but is useful nonetheless: it | |
4907 | marks a whole buffer as a region by putting point at the beginning and | |
4908 | a mark at the end of the buffer. It is generally bound to @kbd{C-x | |
4909 | h}. | |
4910 | ||
4911 | @menu | |
4912 | * mark-whole-buffer overview:: | |
4913 | * Body of mark-whole-buffer:: Only three lines of code. | |
4914 | @end menu | |
4915 | ||
8cda6f8f | 4916 | @ifnottex |
d6adf7e7 | 4917 | @node mark-whole-buffer overview |
8cda6f8f GM |
4918 | @unnumberedsubsec An overview of @code{mark-whole-buffer} |
4919 | @end ifnottex | |
4920 | ||
4921 | @need 1250 | |
4922 | In GNU Emacs 22, the code for the complete function looks like this: | |
4923 | ||
4924 | @smallexample | |
4925 | @group | |
4926 | (defun mark-whole-buffer () | |
4927 | "Put point at beginning and mark at end of buffer. | |
4928 | You probably should not use this function in Lisp programs; | |
4929 | it is usually a mistake for a Lisp function to use any subroutine | |
4930 | that uses or sets the mark." | |
4931 | (interactive) | |
4932 | (push-mark (point)) | |
4933 | (push-mark (point-max) nil t) | |
4934 | (goto-char (point-min))) | |
4935 | @end group | |
4936 | @end smallexample | |
4937 | ||
4938 | @need 1250 | |
4939 | Like all other functions, the @code{mark-whole-buffer} function fits | |
4940 | into the template for a function definition. The template looks like | |
4941 | this: | |
4942 | ||
4943 | @smallexample | |
4944 | @group | |
4945 | (defun @var{name-of-function} (@var{argument-list}) | |
4946 | "@var{documentation}@dots{}" | |
4947 | (@var{interactive-expression}@dots{}) | |
4948 | @var{body}@dots{}) | |
4949 | @end group | |
4950 | @end smallexample | |
4951 | ||
4952 | Here is how the function works: the name of the function is | |
4953 | @code{mark-whole-buffer}; it is followed by an empty argument list, | |
4954 | @samp{()}, which means that the function does not require arguments. | |
4955 | The documentation comes next. | |
4956 | ||
4957 | The next line is an @code{(interactive)} expression that tells Emacs | |
4958 | that the function will be used interactively. These details are similar | |
4959 | to the @code{simplified-beginning-of-buffer} function described in the | |
4960 | previous section. | |
4961 | ||
4962 | @need 1250 | |
d6adf7e7 | 4963 | @node Body of mark-whole-buffer |
8cda6f8f GM |
4964 | @subsection Body of @code{mark-whole-buffer} |
4965 | ||
4966 | The body of the @code{mark-whole-buffer} function consists of three | |
4967 | lines of code: | |
4968 | ||
4969 | @c GNU Emacs 22 | |
4970 | @smallexample | |
4971 | @group | |
4972 | (push-mark (point)) | |
4973 | (push-mark (point-max) nil t) | |
4974 | (goto-char (point-min)) | |
4975 | @end group | |
4976 | @end smallexample | |
4977 | ||
4978 | The first of these lines is the expression, @code{(push-mark (point))}. | |
4979 | ||
4980 | This line does exactly the same job as the first line of the body of | |
4981 | the @code{simplified-beginning-of-buffer} function, which is written | |
4982 | @code{(push-mark)}. In both cases, the Lisp interpreter sets a mark | |
4983 | at the current position of the cursor. | |
4984 | ||
4985 | I don't know why the expression in @code{mark-whole-buffer} is written | |
4986 | @code{(push-mark (point))} and the expression in | |
4987 | @code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps | |
4988 | whoever wrote the code did not know that the arguments for | |
4989 | @code{push-mark} are optional and that if @code{push-mark} is not | |
4990 | passed an argument, the function automatically sets mark at the | |
4991 | location of point by default. Or perhaps the expression was written | |
4992 | so as to parallel the structure of the next line. In any case, the | |
4993 | line causes Emacs to determine the position of point and set a mark | |
4994 | there. | |
4995 | ||
4996 | In earlier versions of GNU Emacs, the next line of | |
4997 | @code{mark-whole-buffer} was @code{(push-mark (point-max))}. This | |
4998 | expression sets a mark at the point in the buffer that has the highest | |
4999 | number. This will be the end of the buffer (or, if the buffer is | |
5000 | narrowed, the end of the accessible portion of the buffer. | |
5001 | @xref{Narrowing & Widening, , Narrowing and Widening}, for more about | |
5002 | narrowing.) After this mark has been set, the previous mark, the one | |
5003 | set at point, is no longer set, but Emacs remembers its position, just | |
5004 | as all other recent marks are always remembered. This means that you | |
5005 | can, if you wish, go back to that position by typing @kbd{C-u | |
5006 | C-@key{SPC}} twice. | |
5007 | ||
5008 | @need 1250 | |
5009 | In GNU Emacs 22, the @code{(point-max)} is slightly more complicated. | |
5010 | The line reads | |
5011 | ||
5012 | @smallexample | |
5013 | (push-mark (point-max) nil t) | |
5014 | @end smallexample | |
5015 | ||
5016 | @noindent | |
5017 | The expression works nearly the same as before. It sets a mark at the | |
5018 | highest numbered place in the buffer that it can. However, in this | |
5019 | version, @code{push-mark} has two additional arguments. The second | |
5020 | argument to @code{push-mark} is @code{nil}. This tells the function | |
5021 | it @emph{should} display a message that says `Mark set' when it pushes | |
5022 | the mark. The third argument is @code{t}. This tells | |
5023 | @code{push-mark} to activate the mark when Transient Mark mode is | |
5024 | turned on. Transient Mark mode highlights the currently active | |
5025 | region. It is often turned off. | |
5026 | ||
5027 | Finally, the last line of the function is @code{(goto-char | |
5028 | (point-min)))}. This is written exactly the same way as it is written | |
5029 | in @code{beginning-of-buffer}. The expression moves the cursor to | |
5030 | the minimum point in the buffer, that is, to the beginning of the buffer | |
5031 | (or to the beginning of the accessible portion of the buffer). As a | |
5032 | result of this, point is placed at the beginning of the buffer and mark | |
5033 | is set at the end of the buffer. The whole buffer is, therefore, the | |
5034 | region. | |
5035 | ||
d6adf7e7 | 5036 | @node append-to-buffer |
8cda6f8f GM |
5037 | @section The Definition of @code{append-to-buffer} |
5038 | @findex append-to-buffer | |
5039 | ||
5040 | The @code{append-to-buffer} command is more complex than the | |
5041 | @code{mark-whole-buffer} command. What it does is copy the region | |
5042 | (that is, the part of the buffer between point and mark) from the | |
5043 | current buffer to a specified buffer. | |
5044 | ||
5045 | @menu | |
5046 | * append-to-buffer overview:: | |
5047 | * append interactive:: A two part interactive expression. | |
5048 | * append-to-buffer body:: Incorporates a @code{let} expression. | |
5049 | * append save-excursion:: How the @code{save-excursion} works. | |
5050 | @end menu | |
5051 | ||
8cda6f8f | 5052 | @ifnottex |
d6adf7e7 | 5053 | @node append-to-buffer overview |
8cda6f8f GM |
5054 | @unnumberedsubsec An Overview of @code{append-to-buffer} |
5055 | @end ifnottex | |
5056 | ||
5057 | @findex insert-buffer-substring | |
5058 | The @code{append-to-buffer} command uses the | |
5059 | @code{insert-buffer-substring} function to copy the region. | |
5060 | @code{insert-buffer-substring} is described by its name: it takes a | |
5061 | string of characters from part of a buffer, a ``substring'', and | |
5062 | inserts them into another buffer. | |
5063 | ||
5064 | Most of @code{append-to-buffer} is | |
5065 | concerned with setting up the conditions for | |
5066 | @code{insert-buffer-substring} to work: the code must specify both the | |
5067 | buffer to which the text will go, the window it comes from and goes | |
5068 | to, and the region that will be copied. | |
5069 | ||
5070 | @need 1250 | |
5071 | Here is the complete text of the function: | |
5072 | ||
5073 | @smallexample | |
5074 | @group | |
5075 | (defun append-to-buffer (buffer start end) | |
5076 | "Append to specified buffer the text of the region. | |
5077 | It is inserted into that buffer before its point. | |
5078 | @end group | |
5079 | ||
5080 | @group | |
5081 | When calling from a program, give three arguments: | |
5082 | BUFFER (or buffer name), START and END. | |
5083 | START and END specify the portion of the current buffer to be copied." | |
5084 | (interactive | |
5085 | (list (read-buffer "Append to buffer: " (other-buffer | |
5086 | (current-buffer) t)) | |
5087 | (region-beginning) (region-end))) | |
5088 | @end group | |
5089 | @group | |
5090 | (let ((oldbuf (current-buffer))) | |
5091 | (save-excursion | |
5092 | (let* ((append-to (get-buffer-create buffer)) | |
5093 | (windows (get-buffer-window-list append-to t t)) | |
5094 | point) | |
5095 | (set-buffer append-to) | |
5096 | (setq point (point)) | |
5097 | (barf-if-buffer-read-only) | |
5098 | (insert-buffer-substring oldbuf start end) | |
5099 | (dolist (window windows) | |
5100 | (when (= (window-point window) point) | |
5101 | (set-window-point window (point)))))))) | |
5102 | @end group | |
5103 | @end smallexample | |
5104 | ||
5105 | The function can be understood by looking at it as a series of | |
5106 | filled-in templates. | |
5107 | ||
5108 | The outermost template is for the function definition. In this | |
5109 | function, it looks like this (with several slots filled in): | |
5110 | ||
5111 | @smallexample | |
5112 | @group | |
5113 | (defun append-to-buffer (buffer start end) | |
5114 | "@var{documentation}@dots{}" | |
5115 | (interactive @dots{}) | |
5116 | @var{body}@dots{}) | |
5117 | @end group | |
5118 | @end smallexample | |
5119 | ||
5120 | The first line of the function includes its name and three arguments. | |
5121 | The arguments are the @code{buffer} to which the text will be copied, and | |
5122 | the @code{start} and @code{end} of the region in the current buffer that | |
5123 | will be copied. | |
5124 | ||
5125 | The next part of the function is the documentation, which is clear and | |
5126 | complete. As is conventional, the three arguments are written in | |
5127 | upper case so you will notice them easily. Even better, they are | |
5128 | described in the same order as in the argument list. | |
5129 | ||
5130 | Note that the documentation distinguishes between a buffer and its | |
5131 | name. (The function can handle either.) | |
5132 | ||
d6adf7e7 | 5133 | @node append interactive |
8cda6f8f GM |
5134 | @subsection The @code{append-to-buffer} Interactive Expression |
5135 | ||
5136 | Since the @code{append-to-buffer} function will be used interactively, | |
5137 | the function must have an @code{interactive} expression. (For a | |
5138 | review of @code{interactive}, see @ref{Interactive, , Making a | |
5139 | Function Interactive}.) The expression reads as follows: | |
5140 | ||
5141 | @smallexample | |
5142 | @group | |
5143 | (interactive | |
5144 | (list (read-buffer | |
5145 | "Append to buffer: " | |
5146 | (other-buffer (current-buffer) t)) | |
5147 | (region-beginning) | |
5148 | (region-end))) | |
5149 | @end group | |
5150 | @end smallexample | |
5151 | ||
5152 | @noindent | |
5153 | This expression is not one with letters standing for parts, as | |
5154 | described earlier. Instead, it starts a list with these parts: | |
5155 | ||
5156 | The first part of the list is an expression to read the name of a | |
5157 | buffer and return it as a string. That is @code{read-buffer}. The | |
5158 | function requires a prompt as its first argument, @samp{"Append to | |
5159 | buffer: "}. Its second argument tells the command what value to | |
5160 | provide if you don't specify anything. | |
5161 | ||
5162 | In this case that second argument is an expression containing the | |
5163 | function @code{other-buffer}, an exception, and a @samp{t}, standing | |
5164 | for true. | |
5165 | ||
5166 | The first argument to @code{other-buffer}, the exception, is yet | |
5167 | another function, @code{current-buffer}. That is not going to be | |
5168 | returned. The second argument is the symbol for true, @code{t}. that | |
5169 | tells @code{other-buffer} that it may show visible buffers (except in | |
5170 | this case, it will not show the current buffer, which makes sense). | |
5171 | ||
5172 | @need 1250 | |
5173 | The expression looks like this: | |
5174 | ||
5175 | @smallexample | |
5176 | (other-buffer (current-buffer) t) | |
5177 | @end smallexample | |
5178 | ||
5179 | The second and third arguments to the @code{list} expression are | |
5180 | @code{(region-beginning)} and @code{(region-end)}. These two | |
5181 | functions specify the beginning and end of the text to be appended. | |
5182 | ||
5183 | @need 1250 | |
5184 | Originally, the command used the letters @samp{B} and @samp{r}. | |
5185 | The whole @code{interactive} expression looked like this: | |
5186 | ||
5187 | @smallexample | |
5188 | (interactive "BAppend to buffer:@: \nr") | |
5189 | @end smallexample | |
5190 | ||
5191 | @noindent | |
5192 | But when that was done, the default value of the buffer switched to | |
5193 | was invisible. That was not wanted. | |
5194 | ||
5195 | (The prompt was separated from the second argument with a newline, | |
5196 | @samp{\n}. It was followed by an @samp{r} that told Emacs to bind the | |
5197 | two arguments that follow the symbol @code{buffer} in the function's | |
5198 | argument list (that is, @code{start} and @code{end}) to the values of | |
5199 | point and mark. That argument worked fine.) | |
5200 | ||
d6adf7e7 | 5201 | @node append-to-buffer body |
8cda6f8f GM |
5202 | @subsection The Body of @code{append-to-buffer} |
5203 | ||
5204 | @ignore | |
5205 | in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el | |
5206 | ||
5207 | (defun append-to-buffer (buffer start end) | |
5208 | "Append to specified buffer the text of the region. | |
5209 | It is inserted into that buffer before its point. | |
5210 | ||
5211 | When calling from a program, give three arguments: | |
5212 | BUFFER (or buffer name), START and END. | |
5213 | START and END specify the portion of the current buffer to be copied." | |
5214 | (interactive | |
5215 | (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) | |
5216 | (region-beginning) (region-end))) | |
5217 | (let ((oldbuf (current-buffer))) | |
5218 | (save-excursion | |
5219 | (let* ((append-to (get-buffer-create buffer)) | |
5220 | (windows (get-buffer-window-list append-to t t)) | |
5221 | point) | |
5222 | (set-buffer append-to) | |
5223 | (setq point (point)) | |
5224 | (barf-if-buffer-read-only) | |
5225 | (insert-buffer-substring oldbuf start end) | |
5226 | (dolist (window windows) | |
5227 | (when (= (window-point window) point) | |
5228 | (set-window-point window (point)))))))) | |
5229 | @end ignore | |
5230 | ||
5231 | The body of the @code{append-to-buffer} function begins with @code{let}. | |
5232 | ||
5233 | As we have seen before (@pxref{let, , @code{let}}), the purpose of a | |
5234 | @code{let} expression is to create and give initial values to one or | |
5235 | more variables that will only be used within the body of the | |
5236 | @code{let}. This means that such a variable will not be confused with | |
5237 | any variable of the same name outside the @code{let} expression. | |
5238 | ||
5239 | We can see how the @code{let} expression fits into the function as a | |
5240 | whole by showing a template for @code{append-to-buffer} with the | |
5241 | @code{let} expression in outline: | |
5242 | ||
5243 | @smallexample | |
5244 | @group | |
5245 | (defun append-to-buffer (buffer start end) | |
5246 | "@var{documentation}@dots{}" | |
5247 | (interactive @dots{}) | |
5248 | (let ((@var{variable} @var{value})) | |
5249 | @var{body}@dots{}) | |
5250 | @end group | |
5251 | @end smallexample | |
5252 | ||
5253 | The @code{let} expression has three elements: | |
5254 | ||
5255 | @enumerate | |
5256 | @item | |
5257 | The symbol @code{let}; | |
5258 | ||
5259 | @item | |
5260 | A varlist containing, in this case, a single two-element list, | |
5261 | @code{(@var{variable} @var{value})}; | |
5262 | ||
5263 | @item | |
5264 | The body of the @code{let} expression. | |
5265 | @end enumerate | |
5266 | ||
5267 | @need 800 | |
5268 | In the @code{append-to-buffer} function, the varlist looks like this: | |
5269 | ||
5270 | @smallexample | |
5271 | (oldbuf (current-buffer)) | |
5272 | @end smallexample | |
5273 | ||
5274 | @noindent | |
5275 | In this part of the @code{let} expression, the one variable, | |
5276 | @code{oldbuf}, is bound to the value returned by the | |
5277 | @code{(current-buffer)} expression. The variable, @code{oldbuf}, is | |
5278 | used to keep track of the buffer in which you are working and from | |
5279 | which you will copy. | |
5280 | ||
5281 | The element or elements of a varlist are surrounded by a set of | |
5282 | parentheses so the Lisp interpreter can distinguish the varlist from | |
5283 | the body of the @code{let}. As a consequence, the two-element list | |
5284 | within the varlist is surrounded by a circumscribing set of parentheses. | |
5285 | The line looks like this: | |
5286 | ||
5287 | @smallexample | |
5288 | @group | |
5289 | (let ((oldbuf (current-buffer))) | |
5290 | @dots{} ) | |
5291 | @end group | |
5292 | @end smallexample | |
5293 | ||
5294 | @noindent | |
5295 | The two parentheses before @code{oldbuf} might surprise you if you did | |
5296 | not realize that the first parenthesis before @code{oldbuf} marks the | |
5297 | boundary of the varlist and the second parenthesis marks the beginning | |
5298 | of the two-element list, @code{(oldbuf (current-buffer))}. | |
5299 | ||
d6adf7e7 | 5300 | @node append save-excursion |
8cda6f8f GM |
5301 | @subsection @code{save-excursion} in @code{append-to-buffer} |
5302 | ||
5303 | The body of the @code{let} expression in @code{append-to-buffer} | |
5304 | consists of a @code{save-excursion} expression. | |
5305 | ||
5306 | The @code{save-excursion} function saves the locations of point and | |
5307 | mark, and restores them to those positions after the expressions in the | |
5308 | body of the @code{save-excursion} complete execution. In addition, | |
5309 | @code{save-excursion} keeps track of the original buffer, and | |
5310 | restores it. This is how @code{save-excursion} is used in | |
5311 | @code{append-to-buffer}. | |
5312 | ||
5313 | @need 1500 | |
5314 | @cindex Indentation for formatting | |
5315 | @cindex Formatting convention | |
5316 | Incidentally, it is worth noting here that a Lisp function is normally | |
5317 | formatted so that everything that is enclosed in a multi-line spread is | |
5318 | indented more to the right than the first symbol. In this function | |
5319 | definition, the @code{let} is indented more than the @code{defun}, and | |
5320 | the @code{save-excursion} is indented more than the @code{let}, like | |
5321 | this: | |
5322 | ||
5323 | @smallexample | |
5324 | @group | |
5325 | (defun @dots{} | |
5326 | @dots{} | |
5327 | @dots{} | |
5328 | (let@dots{} | |
5329 | (save-excursion | |
5330 | @dots{} | |
5331 | @end group | |
5332 | @end smallexample | |
5333 | ||
5334 | @need 1500 | |
5335 | @noindent | |
5336 | This formatting convention makes it easy to see that the lines in | |
5337 | the body of the @code{save-excursion} are enclosed by the parentheses | |
5338 | associated with @code{save-excursion}, just as the | |
5339 | @code{save-excursion} itself is enclosed by the parentheses associated | |
5340 | with the @code{let}: | |
5341 | ||
5342 | @smallexample | |
5343 | @group | |
5344 | (let ((oldbuf (current-buffer))) | |
5345 | (save-excursion | |
5346 | @dots{} | |
5347 | (set-buffer @dots{}) | |
5348 | (insert-buffer-substring oldbuf start end) | |
5349 | @dots{})) | |
5350 | @end group | |
5351 | @end smallexample | |
5352 | ||
5353 | @need 1200 | |
5354 | The use of the @code{save-excursion} function can be viewed as a process | |
5355 | of filling in the slots of a template: | |
5356 | ||
5357 | @smallexample | |
5358 | @group | |
5359 | (save-excursion | |
5360 | @var{first-expression-in-body} | |
5361 | @var{second-expression-in-body} | |
5362 | @dots{} | |
5363 | @var{last-expression-in-body}) | |
5364 | @end group | |
5365 | @end smallexample | |
5366 | ||
5367 | @need 1200 | |
5368 | @noindent | |
5369 | In this function, the body of the @code{save-excursion} contains only | |
5370 | one expression, the @code{let*} expression. You know about a | |
5371 | @code{let} function. The @code{let*} function is different. It has a | |
5372 | @samp{*} in its name. It enables Emacs to set each variable in its | |
5373 | varlist in sequence, one after another. | |
5374 | ||
5375 | Its critical feature is that variables later in the varlist can make | |
5376 | use of the values to which Emacs set variables earlier in the varlist. | |
5377 | @xref{fwd-para let, , The @code{let*} expression}. | |
5378 | ||
5379 | We will skip functions like @code{let*} and focus on two: the | |
5380 | @code{set-buffer} function and the @code{insert-buffer-substring} | |
5381 | function. | |
5382 | ||
5383 | @need 1250 | |
5384 | In the old days, the @code{set-buffer} expression was simply | |
5385 | ||
5386 | @smallexample | |
5387 | (set-buffer (get-buffer-create buffer)) | |
5388 | @end smallexample | |
5389 | ||
5390 | @need 1250 | |
5391 | @noindent | |
5392 | but now it is | |
5393 | ||
5394 | @smallexample | |
5395 | (set-buffer append-to) | |
5396 | @end smallexample | |
5397 | ||
5398 | @noindent | |
5399 | @code{append-to} is bound to @code{(get-buffer-create buffer)} earlier | |
5400 | on in the @code{let*} expression. That extra binding would not be | |
5401 | necessary except for that @code{append-to} is used later in the | |
5402 | varlist as an argument to @code{get-buffer-window-list}. | |
5403 | ||
5404 | @ignore | |
5405 | in GNU Emacs 22 | |
5406 | ||
5407 | (let ((oldbuf (current-buffer))) | |
5408 | (save-excursion | |
5409 | (let* ((append-to (get-buffer-create buffer)) | |
5410 | (windows (get-buffer-window-list append-to t t)) | |
5411 | point) | |
5412 | (set-buffer append-to) | |
5413 | (setq point (point)) | |
5414 | (barf-if-buffer-read-only) | |
5415 | (insert-buffer-substring oldbuf start end) | |
5416 | (dolist (window windows) | |
5417 | (when (= (window-point window) point) | |
5418 | (set-window-point window (point)))))))) | |
5419 | @end ignore | |
5420 | ||
5421 | The @code{append-to-buffer} function definition inserts text from the | |
5422 | buffer in which you are currently to a named buffer. It happens that | |
5423 | @code{insert-buffer-substring} copies text from another buffer to the | |
5424 | current buffer, just the reverse---that is why the | |
5425 | @code{append-to-buffer} definition starts out with a @code{let} that | |
5426 | binds the local symbol @code{oldbuf} to the value returned by | |
5427 | @code{current-buffer}. | |
5428 | ||
5429 | @need 1250 | |
5430 | The @code{insert-buffer-substring} expression looks like this: | |
5431 | ||
5432 | @smallexample | |
5433 | (insert-buffer-substring oldbuf start end) | |
5434 | @end smallexample | |
5435 | ||
5436 | @noindent | |
5437 | The @code{insert-buffer-substring} function copies a string | |
5438 | @emph{from} the buffer specified as its first argument and inserts the | |
5439 | string into the present buffer. In this case, the argument to | |
5440 | @code{insert-buffer-substring} is the value of the variable created | |
5441 | and bound by the @code{let}, namely the value of @code{oldbuf}, which | |
5442 | was the current buffer when you gave the @code{append-to-buffer} | |
5443 | command. | |
5444 | ||
5445 | After @code{insert-buffer-substring} has done its work, | |
5446 | @code{save-excursion} will restore the action to the original buffer | |
5447 | and @code{append-to-buffer} will have done its job. | |
5448 | ||
5449 | @need 800 | |
5450 | Written in skeletal form, the workings of the body look like this: | |
5451 | ||
5452 | @smallexample | |
5453 | @group | |
5454 | (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) | |
5455 | (save-excursion ; @r{Keep track of buffer.} | |
5456 | @var{change-buffer} | |
5457 | @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}) | |
5458 | ||
5459 | @var{change-back-to-original-buffer-when-finished} | |
5460 | @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished} | |
5461 | @end group | |
5462 | @end smallexample | |
5463 | ||
5464 | In summary, @code{append-to-buffer} works as follows: it saves the | |
5465 | value of the current buffer in the variable called @code{oldbuf}. It | |
44e97401 | 5466 | gets the new buffer (creating one if need be) and switches Emacs's |
8cda6f8f GM |
5467 | attention to it. Using the value of @code{oldbuf}, it inserts the |
5468 | region of text from the old buffer into the new buffer; and then using | |
5469 | @code{save-excursion}, it brings you back to your original buffer. | |
5470 | ||
5471 | In looking at @code{append-to-buffer}, you have explored a fairly | |
5472 | complex function. It shows how to use @code{let} and | |
5473 | @code{save-excursion}, and how to change to and come back from another | |
5474 | buffer. Many function definitions use @code{let}, | |
5475 | @code{save-excursion}, and @code{set-buffer} this way. | |
5476 | ||
d6adf7e7 | 5477 | @node Buffer Related Review |
8cda6f8f GM |
5478 | @section Review |
5479 | ||
5480 | Here is a brief summary of the various functions discussed in this chapter. | |
5481 | ||
5482 | @table @code | |
5483 | @item describe-function | |
5484 | @itemx describe-variable | |
5485 | Print the documentation for a function or variable. | |
5486 | Conventionally bound to @kbd{C-h f} and @kbd{C-h v}. | |
5487 | ||
5488 | @item find-tag | |
5489 | Find the file containing the source for a function or variable and | |
5490 | switch buffers to it, positioning point at the beginning of the item. | |
5491 | Conventionally bound to @kbd{M-.} (that's a period following the | |
5492 | @key{META} key). | |
5493 | ||
5494 | @item save-excursion | |
5495 | Save the location of point and mark and restore their values after the | |
5496 | arguments to @code{save-excursion} have been evaluated. Also, remember | |
5497 | the current buffer and return to it. | |
5498 | ||
5499 | @item push-mark | |
5500 | Set mark at a location and record the value of the previous mark on the | |
5501 | mark ring. The mark is a location in the buffer that will keep its | |
5502 | relative position even if text is added to or removed from the buffer. | |
5503 | ||
5504 | @item goto-char | |
5505 | Set point to the location specified by the value of the argument, which | |
5506 | can be a number, a marker, or an expression that returns the number of | |
5507 | a position, such as @code{(point-min)}. | |
5508 | ||
5509 | @item insert-buffer-substring | |
5510 | Copy a region of text from a buffer that is passed to the function as | |
5511 | an argument and insert the region into the current buffer. | |
5512 | ||
5513 | @item mark-whole-buffer | |
5514 | Mark the whole buffer as a region. Normally bound to @kbd{C-x h}. | |
5515 | ||
5516 | @item set-buffer | |
5517 | Switch the attention of Emacs to another buffer, but do not change the | |
5518 | window being displayed. Used when the program rather than a human is | |
5519 | to work on a different buffer. | |
5520 | ||
5521 | @item get-buffer-create | |
5522 | @itemx get-buffer | |
5523 | Find a named buffer or create one if a buffer of that name does not | |
5524 | exist. The @code{get-buffer} function returns @code{nil} if the named | |
5525 | buffer does not exist. | |
5526 | @end table | |
5527 | ||
5528 | @need 1500 | |
d6adf7e7 | 5529 | @node Buffer Exercises |
8cda6f8f GM |
5530 | @section Exercises |
5531 | ||
5532 | @itemize @bullet | |
5533 | @item | |
5534 | Write your own @code{simplified-end-of-buffer} function definition; | |
5535 | then test it to see whether it works. | |
5536 | ||
5537 | @item | |
5538 | Use @code{if} and @code{get-buffer} to write a function that prints a | |
5539 | message telling you whether a buffer exists. | |
5540 | ||
5541 | @item | |
5542 | Using @code{find-tag}, find the source for the @code{copy-to-buffer} | |
5543 | function. | |
5544 | @end itemize | |
5545 | ||
d6adf7e7 | 5546 | @node More Complex |
8cda6f8f GM |
5547 | @chapter A Few More Complex Functions |
5548 | ||
5549 | In this chapter, we build on what we have learned in previous chapters | |
5550 | by looking at more complex functions. The @code{copy-to-buffer} | |
5551 | function illustrates use of two @code{save-excursion} expressions in | |
5552 | one definition, while the @code{insert-buffer} function illustrates | |
5553 | use of an asterisk in an @code{interactive} expression, use of | |
5554 | @code{or}, and the important distinction between a name and the object | |
5555 | to which the name refers. | |
5556 | ||
5557 | @menu | |
5558 | * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. | |
5559 | * insert-buffer:: Read-only, and with @code{or}. | |
5560 | * beginning-of-buffer:: Shows @code{goto-char}, | |
5561 | @code{point-min}, and @code{push-mark}. | |
5562 | * Second Buffer Related Review:: | |
5563 | * optional Exercise:: | |
5564 | @end menu | |
5565 | ||
d6adf7e7 | 5566 | @node copy-to-buffer |
8cda6f8f GM |
5567 | @section The Definition of @code{copy-to-buffer} |
5568 | @findex copy-to-buffer | |
5569 | ||
5570 | After understanding how @code{append-to-buffer} works, it is easy to | |
5571 | understand @code{copy-to-buffer}. This function copies text into a | |
5572 | buffer, but instead of adding to the second buffer, it replaces all the | |
5573 | previous text in the second buffer. | |
5574 | ||
5575 | @need 800 | |
5576 | The body of @code{copy-to-buffer} looks like this, | |
5577 | ||
5578 | @smallexample | |
5579 | @group | |
5580 | @dots{} | |
5581 | (interactive "BCopy to buffer: \nr") | |
5582 | (let ((oldbuf (current-buffer))) | |
5583 | (with-current-buffer (get-buffer-create buffer) | |
5584 | (barf-if-buffer-read-only) | |
5585 | (erase-buffer) | |
5586 | (save-excursion | |
5587 | (insert-buffer-substring oldbuf start end))))) | |
5588 | @end group | |
5589 | @end smallexample | |
5590 | ||
5591 | The @code{copy-to-buffer} function has a simpler @code{interactive} | |
5592 | expression than @code{append-to-buffer}. | |
5593 | ||
5594 | @need 800 | |
5595 | The definition then says | |
5596 | ||
5597 | @smallexample | |
5598 | (with-current-buffer (get-buffer-create buffer) @dots{} | |
5599 | @end smallexample | |
5600 | ||
5601 | First, look at the earliest inner expression; that is evaluated first. | |
5602 | That expression starts with @code{get-buffer-create buffer}. The | |
5603 | function tells the computer to use the buffer with the name specified | |
5604 | as the one to which you are copying, or if such a buffer does not | |
5605 | exist, to create it. Then, the @code{with-current-buffer} function | |
5606 | evaluates its body with that buffer temporarily current. | |
5607 | ||
5608 | (This demonstrates another way to shift the computer's attention but | |
5609 | not the user's. The @code{append-to-buffer} function showed how to do | |
5610 | the same with @code{save-excursion} and @code{set-buffer}. | |
5611 | @code{with-current-buffer} is a newer, and arguably easier, | |
5612 | mechanism.) | |
5613 | ||
5614 | The @code{barf-if-buffer-read-only} function sends you an error | |
5615 | message saying the buffer is read-only if you cannot modify it. | |
5616 | ||
5617 | The next line has the @code{erase-buffer} function as its sole | |
5618 | contents. That function erases the buffer. | |
5619 | ||
5620 | Finally, the last two lines contain the @code{save-excursion} | |
5621 | expression with @code{insert-buffer-substring} as its body. | |
5622 | The @code{insert-buffer-substring} expression copies the text from | |
5623 | the buffer you are in (and you have not seen the computer shift its | |
5624 | attention, so you don't know that that buffer is now called | |
5625 | @code{oldbuf}). | |
5626 | ||
5627 | Incidentally, this is what is meant by `replacement'. To replace text, | |
5628 | Emacs erases the previous text and then inserts new text. | |
5629 | ||
5630 | @need 1250 | |
5631 | In outline, the body of @code{copy-to-buffer} looks like this: | |
5632 | ||
5633 | @smallexample | |
5634 | @group | |
5635 | (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) | |
5636 | (@var{with-the-buffer-you-are-copying-to} | |
5637 | (@var{but-do-not-erase-or-copy-to-a-read-only-buffer}) | |
5638 | (erase-buffer) | |
5639 | (save-excursion | |
5640 | @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}))) | |
5641 | @end group | |
5642 | @end smallexample | |
5643 | ||
d6adf7e7 | 5644 | @node insert-buffer |
8cda6f8f GM |
5645 | @section The Definition of @code{insert-buffer} |
5646 | @findex insert-buffer | |
5647 | ||
5648 | @code{insert-buffer} is yet another buffer-related function. This | |
5649 | command copies another buffer @emph{into} the current buffer. It is the | |
5650 | reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they | |
5651 | copy a region of text @emph{from} the current buffer to another buffer. | |
5652 | ||
5653 | Here is a discussion based on the original code. The code was | |
5654 | simplified in 2003 and is harder to understand. | |
5655 | ||
5656 | (@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see | |
5657 | a discussion of the new body.) | |
5658 | ||
5659 | In addition, this code illustrates the use of @code{interactive} with a | |
5660 | buffer that might be @dfn{read-only} and the important distinction | |
5661 | between the name of an object and the object actually referred to. | |
5662 | ||
5663 | @menu | |
5664 | * insert-buffer code:: | |
5665 | * insert-buffer interactive:: When you can read, but not write. | |
5666 | * insert-buffer body:: The body has an @code{or} and a @code{let}. | |
5667 | * if & or:: Using an @code{if} instead of an @code{or}. | |
5668 | * Insert or:: How the @code{or} expression works. | |
5669 | * Insert let:: Two @code{save-excursion} expressions. | |
5670 | * New insert-buffer:: | |
5671 | @end menu | |
5672 | ||
8cda6f8f | 5673 | @ifnottex |
d6adf7e7 | 5674 | @node insert-buffer code |
8cda6f8f GM |
5675 | @unnumberedsubsec The Code for @code{insert-buffer} |
5676 | @end ifnottex | |
5677 | ||
5678 | @need 800 | |
5679 | Here is the earlier code: | |
5680 | ||
5681 | @smallexample | |
5682 | @group | |
5683 | (defun insert-buffer (buffer) | |
5684 | "Insert after point the contents of BUFFER. | |
5685 | Puts mark after the inserted text. | |
5686 | BUFFER may be a buffer or a buffer name." | |
5687 | (interactive "*bInsert buffer:@: ") | |
5688 | @end group | |
5689 | @group | |
5690 | (or (bufferp buffer) | |
5691 | (setq buffer (get-buffer buffer))) | |
5692 | (let (start end newmark) | |
5693 | (save-excursion | |
5694 | (save-excursion | |
5695 | (set-buffer buffer) | |
5696 | (setq start (point-min) end (point-max))) | |
5697 | @end group | |
5698 | @group | |
5699 | (insert-buffer-substring buffer start end) | |
5700 | (setq newmark (point))) | |
5701 | (push-mark newmark))) | |
5702 | @end group | |
5703 | @end smallexample | |
5704 | ||
5705 | @need 1200 | |
5706 | As with other function definitions, you can use a template to see an | |
5707 | outline of the function: | |
5708 | ||
5709 | @smallexample | |
5710 | @group | |
5711 | (defun insert-buffer (buffer) | |
5712 | "@var{documentation}@dots{}" | |
5713 | (interactive "*bInsert buffer:@: ") | |
5714 | @var{body}@dots{}) | |
5715 | @end group | |
5716 | @end smallexample | |
5717 | ||
d6adf7e7 | 5718 | @node insert-buffer interactive |
8cda6f8f GM |
5719 | @subsection The Interactive Expression in @code{insert-buffer} |
5720 | @findex interactive, @r{example use of} | |
5721 | ||
5722 | In @code{insert-buffer}, the argument to the @code{interactive} | |
5723 | declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert | |
5724 | buffer:@: }. | |
5725 | ||
5726 | @menu | |
5727 | * Read-only buffer:: When a buffer cannot be modified. | |
5728 | * b for interactive:: An existing buffer or else its name. | |
5729 | @end menu | |
5730 | ||
d6adf7e7 | 5731 | @node Read-only buffer |
8cda6f8f GM |
5732 | @unnumberedsubsubsec A Read-only Buffer |
5733 | @cindex Read-only buffer | |
5734 | @cindex Asterisk for read-only buffer | |
5735 | @findex * @r{for read-only buffer} | |
5736 | ||
5737 | The asterisk is for the situation when the current buffer is a | |
5738 | read-only buffer---a buffer that cannot be modified. If | |
5739 | @code{insert-buffer} is called when the current buffer is read-only, a | |
5740 | message to this effect is printed in the echo area and the terminal | |
5741 | may beep or blink at you; you will not be permitted to insert anything | |
5742 | into current buffer. The asterisk does not need to be followed by a | |
5743 | newline to separate it from the next argument. | |
5744 | ||
d6adf7e7 | 5745 | @node b for interactive |
8cda6f8f GM |
5746 | @unnumberedsubsubsec @samp{b} in an Interactive Expression |
5747 | ||
5748 | The next argument in the interactive expression starts with a lower | |
5749 | case @samp{b}. (This is different from the code for | |
5750 | @code{append-to-buffer}, which uses an upper-case @samp{B}. | |
5751 | @xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) | |
5752 | The lower-case @samp{b} tells the Lisp interpreter that the argument | |
5753 | for @code{insert-buffer} should be an existing buffer or else its | |
5754 | name. (The upper-case @samp{B} option provides for the possibility | |
5755 | that the buffer does not exist.) Emacs will prompt you for the name | |
5756 | of the buffer, offering you a default buffer, with name completion | |
5757 | enabled. If the buffer does not exist, you receive a message that | |
5758 | says ``No match''; your terminal may beep at you as well. | |
5759 | ||
5760 | The new and simplified code generates a list for @code{interactive}. | |
5761 | It uses the @code{barf-if-buffer-read-only} and @code{read-buffer} | |
5762 | functions with which we are already familiar and the @code{progn} | |
5763 | special form with which we are not. (It will be described later.) | |
5764 | ||
d6adf7e7 | 5765 | @node insert-buffer body |
8cda6f8f GM |
5766 | @subsection The Body of the @code{insert-buffer} Function |
5767 | ||
5768 | The body of the @code{insert-buffer} function has two major parts: an | |
5769 | @code{or} expression and a @code{let} expression. The purpose of the | |
5770 | @code{or} expression is to ensure that the argument @code{buffer} is | |
5771 | bound to a buffer and not just the name of a buffer. The body of the | |
5772 | @code{let} expression contains the code which copies the other buffer | |
5773 | into the current buffer. | |
5774 | ||
5775 | @need 1250 | |
5776 | In outline, the two expressions fit into the @code{insert-buffer} | |
5777 | function like this: | |
5778 | ||
5779 | @smallexample | |
5780 | @group | |
5781 | (defun insert-buffer (buffer) | |
5782 | "@var{documentation}@dots{}" | |
5783 | (interactive "*bInsert buffer:@: ") | |
5784 | (or @dots{} | |
5785 | @dots{} | |
5786 | @end group | |
5787 | @group | |
5788 | (let (@var{varlist}) | |
5789 | @var{body-of-}@code{let}@dots{} ) | |
5790 | @end group | |
5791 | @end smallexample | |
5792 | ||
5793 | To understand how the @code{or} expression ensures that the argument | |
5794 | @code{buffer} is bound to a buffer and not to the name of a buffer, it | |
5795 | is first necessary to understand the @code{or} function. | |
5796 | ||
5797 | Before doing this, let me rewrite this part of the function using | |
5798 | @code{if} so that you can see what is done in a manner that will be familiar. | |
5799 | ||
d6adf7e7 | 5800 | @node if & or |
8cda6f8f GM |
5801 | @subsection @code{insert-buffer} With an @code{if} Instead of an @code{or} |
5802 | ||
5803 | The job to be done is to make sure the value of @code{buffer} is a | |
5804 | buffer itself and not the name of a buffer. If the value is the name, | |
5805 | then the buffer itself must be got. | |
5806 | ||
5807 | You can imagine yourself at a conference where an usher is wandering | |
5808 | around holding a list with your name on it and looking for you: the | |
5809 | usher is ``bound'' to your name, not to you; but when the usher finds | |
5810 | you and takes your arm, the usher becomes ``bound'' to you. | |
5811 | ||
5812 | @need 800 | |
5813 | In Lisp, you might describe this situation like this: | |
5814 | ||
5815 | @smallexample | |
5816 | @group | |
5817 | (if (not (holding-on-to-guest)) | |
5818 | (find-and-take-arm-of-guest)) | |
5819 | @end group | |
5820 | @end smallexample | |
5821 | ||
5822 | We want to do the same thing with a buffer---if we do not have the | |
5823 | buffer itself, we want to get it. | |
5824 | ||
5825 | @need 1200 | |
5826 | Using a predicate called @code{bufferp} that tells us whether we have a | |
5827 | buffer (rather than its name), we can write the code like this: | |
5828 | ||
5829 | @smallexample | |
5830 | @group | |
5831 | (if (not (bufferp buffer)) ; @r{if-part} | |
5832 | (setq buffer (get-buffer buffer))) ; @r{then-part} | |
5833 | @end group | |
5834 | @end smallexample | |
5835 | ||
5836 | @noindent | |
5837 | Here, the true-or-false-test of the @code{if} expression is | |
5838 | @w{@code{(not (bufferp buffer))}}; and the then-part is the expression | |
5839 | @w{@code{(setq buffer (get-buffer buffer))}}. | |
5840 | ||
5841 | In the test, the function @code{bufferp} returns true if its argument is | |
5842 | a buffer---but false if its argument is the name of the buffer. (The | |
5843 | last character of the function name @code{bufferp} is the character | |
5844 | @samp{p}; as we saw earlier, such use of @samp{p} is a convention that | |
5845 | indicates that the function is a predicate, which is a term that means | |
5846 | that the function will determine whether some property is true or false. | |
5847 | @xref{Wrong Type of Argument, , Using the Wrong Type Object as an | |
5848 | Argument}.) | |
5849 | ||
5850 | @need 1200 | |
5851 | The function @code{not} precedes the expression @code{(bufferp buffer)}, | |
5852 | so the true-or-false-test looks like this: | |
5853 | ||
5854 | @smallexample | |
5855 | (not (bufferp buffer)) | |
5856 | @end smallexample | |
5857 | ||
5858 | @noindent | |
5859 | @code{not} is a function that returns true if its argument is false | |
5860 | and false if its argument is true. So if @code{(bufferp buffer)} | |
5861 | returns true, the @code{not} expression returns false and vice-verse: | |
5862 | what is ``not true'' is false and what is ``not false'' is true. | |
5863 | ||
5864 | Using this test, the @code{if} expression works as follows: when the | |
5865 | value of the variable @code{buffer} is actually a buffer rather than | |
5866 | its name, the true-or-false-test returns false and the @code{if} | |
5867 | expression does not evaluate the then-part. This is fine, since we do | |
5868 | not need to do anything to the variable @code{buffer} if it really is | |
5869 | a buffer. | |
5870 | ||
5871 | On the other hand, when the value of @code{buffer} is not a buffer | |
5872 | itself, but the name of a buffer, the true-or-false-test returns true | |
5873 | and the then-part of the expression is evaluated. In this case, the | |
5874 | then-part is @code{(setq buffer (get-buffer buffer))}. This | |
5875 | expression uses the @code{get-buffer} function to return an actual | |
5876 | buffer itself, given its name. The @code{setq} then sets the variable | |
5877 | @code{buffer} to the value of the buffer itself, replacing its previous | |
5878 | value (which was the name of the buffer). | |
5879 | ||
d6adf7e7 | 5880 | @node Insert or |
8cda6f8f GM |
5881 | @subsection The @code{or} in the Body |
5882 | ||
5883 | The purpose of the @code{or} expression in the @code{insert-buffer} | |
5884 | function is to ensure that the argument @code{buffer} is bound to a | |
5885 | buffer and not just to the name of a buffer. The previous section shows | |
5886 | how the job could have been done using an @code{if} expression. | |
5887 | However, the @code{insert-buffer} function actually uses @code{or}. | |
5888 | To understand this, it is necessary to understand how @code{or} works. | |
5889 | ||
5890 | @findex or | |
5891 | An @code{or} function can have any number of arguments. It evaluates | |
5892 | each argument in turn and returns the value of the first of its | |
5893 | arguments that is not @code{nil}. Also, and this is a crucial feature | |
5894 | of @code{or}, it does not evaluate any subsequent arguments after | |
5895 | returning the first non-@code{nil} value. | |
5896 | ||
5897 | @need 800 | |
5898 | The @code{or} expression looks like this: | |
5899 | ||
5900 | @smallexample | |
5901 | @group | |
5902 | (or (bufferp buffer) | |
5903 | (setq buffer (get-buffer buffer))) | |
5904 | @end group | |
5905 | @end smallexample | |
5906 | ||
5907 | @noindent | |
5908 | The first argument to @code{or} is the expression @code{(bufferp buffer)}. | |
5909 | This expression returns true (a non-@code{nil} value) if the buffer is | |
5910 | actually a buffer, and not just the name of a buffer. In the @code{or} | |
5911 | expression, if this is the case, the @code{or} expression returns this | |
5912 | true value and does not evaluate the next expression---and this is fine | |
5913 | with us, since we do not want to do anything to the value of | |
5914 | @code{buffer} if it really is a buffer. | |
5915 | ||
5916 | On the other hand, if the value of @code{(bufferp buffer)} is @code{nil}, | |
5917 | which it will be if the value of @code{buffer} is the name of a buffer, | |
5918 | the Lisp interpreter evaluates the next element of the @code{or} | |
5919 | expression. This is the expression @code{(setq buffer (get-buffer | |
5920 | buffer))}. This expression returns a non-@code{nil} value, which | |
5921 | is the value to which it sets the variable @code{buffer}---and this | |
5922 | value is a buffer itself, not the name of a buffer. | |
5923 | ||
5924 | The result of all this is that the symbol @code{buffer} is always | |
5925 | bound to a buffer itself rather than to the name of a buffer. All | |
5926 | this is necessary because the @code{set-buffer} function in a | |
5927 | following line only works with a buffer itself, not with the name to a | |
5928 | buffer. | |
5929 | ||
5930 | @need 1250 | |
5931 | Incidentally, using @code{or}, the situation with the usher would be | |
5932 | written like this: | |
5933 | ||
5934 | @smallexample | |
5935 | (or (holding-on-to-guest) (find-and-take-arm-of-guest)) | |
5936 | @end smallexample | |
5937 | ||
d6adf7e7 | 5938 | @node Insert let |
8cda6f8f GM |
5939 | @subsection The @code{let} Expression in @code{insert-buffer} |
5940 | ||
5941 | After ensuring that the variable @code{buffer} refers to a buffer itself | |
5942 | and not just to the name of a buffer, the @code{insert-buffer function} | |
5943 | continues with a @code{let} expression. This specifies three local | |
5944 | variables, @code{start}, @code{end}, and @code{newmark} and binds them | |
5945 | to the initial value @code{nil}. These variables are used inside the | |
5946 | remainder of the @code{let} and temporarily hide any other occurrence of | |
5947 | variables of the same name in Emacs until the end of the @code{let}. | |
5948 | ||
5949 | @need 1200 | |
5950 | The body of the @code{let} contains two @code{save-excursion} | |
5951 | expressions. First, we will look at the inner @code{save-excursion} | |
5952 | expression in detail. The expression looks like this: | |
5953 | ||
5954 | @smallexample | |
5955 | @group | |
5956 | (save-excursion | |
5957 | (set-buffer buffer) | |
5958 | (setq start (point-min) end (point-max))) | |
5959 | @end group | |
5960 | @end smallexample | |
5961 | ||
5962 | @noindent | |
44e97401 | 5963 | The expression @code{(set-buffer buffer)} changes Emacs's attention |
8cda6f8f GM |
5964 | from the current buffer to the one from which the text will copied. |
5965 | In that buffer, the variables @code{start} and @code{end} are set to | |
5966 | the beginning and end of the buffer, using the commands | |
5967 | @code{point-min} and @code{point-max}. Note that we have here an | |
5968 | illustration of how @code{setq} is able to set two variables in the | |
5969 | same expression. The first argument of @code{setq} is set to the | |
5970 | value of its second, and its third argument is set to the value of its | |
5971 | fourth. | |
5972 | ||
5973 | After the body of the inner @code{save-excursion} is evaluated, the | |
5974 | @code{save-excursion} restores the original buffer, but @code{start} and | |
5975 | @code{end} remain set to the values of the beginning and end of the | |
5976 | buffer from which the text will be copied. | |
5977 | ||
5978 | @need 1250 | |
5979 | The outer @code{save-excursion} expression looks like this: | |
5980 | ||
5981 | @smallexample | |
5982 | @group | |
5983 | (save-excursion | |
5984 | (@var{inner-}@code{save-excursion}@var{-expression} | |
5985 | (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end}) | |
5986 | (insert-buffer-substring buffer start end) | |
5987 | (setq newmark (point))) | |
5988 | @end group | |
5989 | @end smallexample | |
5990 | ||
5991 | @noindent | |
5992 | The @code{insert-buffer-substring} function copies the text | |
5993 | @emph{into} the current buffer @emph{from} the region indicated by | |
5994 | @code{start} and @code{end} in @code{buffer}. Since the whole of the | |
5995 | second buffer lies between @code{start} and @code{end}, the whole of | |
5996 | the second buffer is copied into the buffer you are editing. Next, | |
5997 | the value of point, which will be at the end of the inserted text, is | |
5998 | recorded in the variable @code{newmark}. | |
5999 | ||
6000 | After the body of the outer @code{save-excursion} is evaluated, point | |
6001 | and mark are relocated to their original places. | |
6002 | ||
6003 | However, it is convenient to locate a mark at the end of the newly | |
6004 | inserted text and locate point at its beginning. The @code{newmark} | |
6005 | variable records the end of the inserted text. In the last line of | |
6006 | the @code{let} expression, the @code{(push-mark newmark)} expression | |
6007 | function sets a mark to this location. (The previous location of the | |
6008 | mark is still accessible; it is recorded on the mark ring and you can | |
6009 | go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is | |
6010 | located at the beginning of the inserted text, which is where it was | |
6011 | before you called the insert function, the position of which was saved | |
6012 | by the first @code{save-excursion}. | |
6013 | ||
6014 | @need 1250 | |
6015 | The whole @code{let} expression looks like this: | |
6016 | ||
6017 | @smallexample | |
6018 | @group | |
6019 | (let (start end newmark) | |
6020 | (save-excursion | |
6021 | (save-excursion | |
6022 | (set-buffer buffer) | |
6023 | (setq start (point-min) end (point-max))) | |
6024 | (insert-buffer-substring buffer start end) | |
6025 | (setq newmark (point))) | |
6026 | (push-mark newmark)) | |
6027 | @end group | |
6028 | @end smallexample | |
6029 | ||
6030 | Like the @code{append-to-buffer} function, the @code{insert-buffer} | |
6031 | function uses @code{let}, @code{save-excursion}, and | |
6032 | @code{set-buffer}. In addition, the function illustrates one way to | |
6033 | use @code{or}. All these functions are building blocks that we will | |
6034 | find and use again and again. | |
6035 | ||
d6adf7e7 | 6036 | @node New insert-buffer |
8cda6f8f GM |
6037 | @subsection New Body for @code{insert-buffer} |
6038 | @findex insert-buffer, new version body | |
6039 | @findex new version body for insert-buffer | |
6040 | ||
6041 | The body in the GNU Emacs 22 version is more confusing than the original. | |
6042 | ||
6043 | @need 1250 | |
6044 | It consists of two expressions, | |
6045 | ||
6046 | @smallexample | |
6047 | @group | |
6048 | (push-mark | |
6049 | (save-excursion | |
6050 | (insert-buffer-substring (get-buffer buffer)) | |
6051 | (point))) | |
6052 | ||
6053 | nil | |
6054 | @end group | |
6055 | @end smallexample | |
6056 | ||
6057 | @noindent | |
6058 | except, and this is what confuses novices, very important work is done | |
6059 | inside the @code{push-mark} expression. | |
6060 | ||
6061 | The @code{get-buffer} function returns a buffer with the name | |
6062 | provided. You will note that the function is @emph{not} called | |
6063 | @code{get-buffer-create}; it does not create a buffer if one does not | |
6064 | already exist. The buffer returned by @code{get-buffer}, an existing | |
6065 | buffer, is passed to @code{insert-buffer-substring}, which inserts the | |
6066 | whole of the buffer (since you did not specify anything else). | |
6067 | ||
6068 | The location into which the buffer is inserted is recorded by | |
6069 | @code{push-mark}. Then the function returns @code{nil}, the value of | |
6070 | its last command. Put another way, the @code{insert-buffer} function | |
6071 | exists only to produce a side effect, inserting another buffer, not to | |
6072 | return any value. | |
6073 | ||
d6adf7e7 | 6074 | @node beginning-of-buffer |
8cda6f8f GM |
6075 | @section Complete Definition of @code{beginning-of-buffer} |
6076 | @findex beginning-of-buffer | |
6077 | ||
6078 | The basic structure of the @code{beginning-of-buffer} function has | |
6079 | already been discussed. (@xref{simplified-beginning-of-buffer, , A | |
6080 | Simplified @code{beginning-of-buffer} Definition}.) | |
6081 | This section describes the complex part of the definition. | |
6082 | ||
6083 | As previously described, when invoked without an argument, | |
6084 | @code{beginning-of-buffer} moves the cursor to the beginning of the | |
6085 | buffer (in truth, the beginning of the accessible portion of the | |
6086 | buffer), leaving the mark at the previous position. However, when the | |
6087 | command is invoked with a number between one and ten, the function | |
6088 | considers that number to be a fraction of the length of the buffer, | |
6089 | measured in tenths, and Emacs moves the cursor that fraction of the | |
6090 | way from the beginning of the buffer. Thus, you can either call this | |
6091 | function with the key command @kbd{M-<}, which will move the cursor to | |
6092 | the beginning of the buffer, or with a key command such as @kbd{C-u 7 | |
6093 | M-<} which will move the cursor to a point 70% of the way through the | |
6094 | buffer. If a number bigger than ten is used for the argument, it | |
6095 | moves to the end of the buffer. | |
6096 | ||
6097 | The @code{beginning-of-buffer} function can be called with or without an | |
6098 | argument. The use of the argument is optional. | |
6099 | ||
6100 | @menu | |
6101 | * Optional Arguments:: | |
6102 | * beginning-of-buffer opt arg:: Example with optional argument. | |
6103 | * beginning-of-buffer complete:: | |
6104 | @end menu | |
6105 | ||
d6adf7e7 | 6106 | @node Optional Arguments |
8cda6f8f GM |
6107 | @subsection Optional Arguments |
6108 | ||
6109 | Unless told otherwise, Lisp expects that a function with an argument in | |
6110 | its function definition will be called with a value for that argument. | |
6111 | If that does not happen, you get an error and a message that says | |
6112 | @samp{Wrong number of arguments}. | |
6113 | ||
6114 | @cindex Optional arguments | |
6115 | @cindex Keyword | |
6116 | @findex optional | |
6117 | However, optional arguments are a feature of Lisp: a particular | |
6118 | @dfn{keyword} is used to tell the Lisp interpreter that an argument is | |
6119 | optional. The keyword is @code{&optional}. (The @samp{&} in front of | |
6120 | @samp{optional} is part of the keyword.) In a function definition, if | |
6121 | an argument follows the keyword @code{&optional}, no value need be | |
6122 | passed to that argument when the function is called. | |
6123 | ||
6124 | @need 1200 | |
6125 | The first line of the function definition of @code{beginning-of-buffer} | |
6126 | therefore looks like this: | |
6127 | ||
6128 | @smallexample | |
6129 | (defun beginning-of-buffer (&optional arg) | |
6130 | @end smallexample | |
6131 | ||
6132 | @need 1250 | |
6133 | In outline, the whole function looks like this: | |
6134 | ||
6135 | @smallexample | |
6136 | @group | |
6137 | (defun beginning-of-buffer (&optional arg) | |
6138 | "@var{documentation}@dots{}" | |
6139 | (interactive "P") | |
6140 | (or (@var{is-the-argument-a-cons-cell} arg) | |
6141 | (and @var{are-both-transient-mark-mode-and-mark-active-true}) | |
6142 | (push-mark)) | |
6143 | (let (@var{determine-size-and-set-it}) | |
6144 | (goto-char | |
6145 | (@var{if-there-is-an-argument} | |
6146 | @var{figure-out-where-to-go} | |
6147 | @var{else-go-to} | |
6148 | (point-min)))) | |
6149 | @var{do-nicety} | |
6150 | @end group | |
6151 | @end smallexample | |
6152 | ||
6153 | The function is similar to the @code{simplified-beginning-of-buffer} | |
6154 | function except that the @code{interactive} expression has @code{"P"} | |
6155 | as an argument and the @code{goto-char} function is followed by an | |
6156 | if-then-else expression that figures out where to put the cursor if | |
6157 | there is an argument that is not a cons cell. | |
6158 | ||
6159 | (Since I do not explain a cons cell for many more chapters, please | |
6160 | consider ignoring the function @code{consp}. @xref{List | |
6161 | Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type, | |
6162 | , Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference | |
6163 | Manual}.) | |
6164 | ||
6165 | The @code{"P"} in the @code{interactive} expression tells Emacs to | |
6166 | pass a prefix argument, if there is one, to the function in raw form. | |
6167 | A prefix argument is made by typing the @key{META} key followed by a | |
6168 | number, or by typing @kbd{C-u} and then a number. (If you don't type | |
6169 | a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase | |
6170 | @code{"p"} in the @code{interactive} expression causes the function to | |
6171 | convert a prefix arg to a number.) | |
6172 | ||
6173 | The true-or-false-test of the @code{if} expression looks complex, but | |
6174 | it is not: it checks whether @code{arg} has a value that is not | |
6175 | @code{nil} and whether it is a cons cell. (That is what @code{consp} | |
6176 | does; it checks whether its argument is a cons cell.) If @code{arg} | |
6177 | has a value that is not @code{nil} (and is not a cons cell), which | |
6178 | will be the case if @code{beginning-of-buffer} is called with a | |
6179 | numeric argument, then this true-or-false-test will return true and | |
6180 | the then-part of the @code{if} expression will be evaluated. On the | |
6181 | other hand, if @code{beginning-of-buffer} is not called with an | |
6182 | argument, the value of @code{arg} will be @code{nil} and the else-part | |
6183 | of the @code{if} expression will be evaluated. The else-part is | |
6184 | simply @code{point-min}, and when this is the outcome, the whole | |
6185 | @code{goto-char} expression is @code{(goto-char (point-min))}, which | |
6186 | is how we saw the @code{beginning-of-buffer} function in its | |
6187 | simplified form. | |
6188 | ||
d6adf7e7 | 6189 | @node beginning-of-buffer opt arg |
8cda6f8f GM |
6190 | @subsection @code{beginning-of-buffer} with an Argument |
6191 | ||
6192 | When @code{beginning-of-buffer} is called with an argument, an | |
6193 | expression is evaluated which calculates what value to pass to | |
6194 | @code{goto-char}. This expression is rather complicated at first sight. | |
6195 | It includes an inner @code{if} expression and much arithmetic. It looks | |
6196 | like this: | |
6197 | ||
6198 | @smallexample | |
6199 | @group | |
6200 | (if (> (buffer-size) 10000) | |
6201 | ;; @r{Avoid overflow for large buffer sizes!} | |
6202 | (* (prefix-numeric-value arg) | |
6203 | (/ size 10)) | |
6204 | (/ | |
6205 | (+ 10 | |
6206 | (* | |
6207 | size (prefix-numeric-value arg))) 10))) | |
6208 | @end group | |
6209 | @end smallexample | |
6210 | ||
6211 | @menu | |
6212 | * Disentangle beginning-of-buffer:: | |
6213 | * Large buffer case:: | |
6214 | * Small buffer case:: | |
6215 | @end menu | |
6216 | ||
8cda6f8f | 6217 | @ifnottex |
d6adf7e7 | 6218 | @node Disentangle beginning-of-buffer |
8cda6f8f GM |
6219 | @unnumberedsubsubsec Disentangle @code{beginning-of-buffer} |
6220 | @end ifnottex | |
6221 | ||
6222 | Like other complex-looking expressions, the conditional expression | |
6223 | within @code{beginning-of-buffer} can be disentangled by looking at it | |
6224 | as parts of a template, in this case, the template for an if-then-else | |
6225 | expression. In skeletal form, the expression looks like this: | |
6226 | ||
6227 | @smallexample | |
6228 | @group | |
6229 | (if (@var{buffer-is-large} | |
6230 | @var{divide-buffer-size-by-10-and-multiply-by-arg} | |
6231 | @var{else-use-alternate-calculation} | |
6232 | @end group | |
6233 | @end smallexample | |
6234 | ||
6235 | The true-or-false-test of this inner @code{if} expression checks the | |
6236 | size of the buffer. The reason for this is that the old version 18 | |
6237 | Emacs used numbers that are no bigger than eight million or so and in | |
6238 | the computation that followed, the programmer feared that Emacs might | |
6239 | try to use over-large numbers if the buffer were large. The term | |
6240 | `overflow', mentioned in the comment, means numbers that are over | |
6241 | large. More recent versions of Emacs use larger numbers, but this | |
6242 | code has not been touched, if only because people now look at buffers | |
6243 | that are far, far larger than ever before. | |
6244 | ||
6245 | There are two cases: if the buffer is large and if it is not. | |
6246 | ||
d6adf7e7 | 6247 | @node Large buffer case |
8cda6f8f GM |
6248 | @unnumberedsubsubsec What happens in a large buffer |
6249 | ||
6250 | In @code{beginning-of-buffer}, the inner @code{if} expression tests | |
6251 | whether the size of the buffer is greater than 10,000 characters. To do | |
6252 | this, it uses the @code{>} function and the computation of @code{size} | |
6253 | that comes from the let expression. | |
6254 | ||
6255 | In the old days, the function @code{buffer-size} was used. Not only | |
6256 | was that function called several times, it gave the size of the whole | |
6257 | buffer, not the accessible part. The computation makes much more | |
6258 | sense when it handles just the accessible part. (@xref{Narrowing & | |
6259 | Widening, , Narrowing and Widening}, for more information on focusing | |
6260 | attention to an `accessible' part.) | |
6261 | ||
6262 | @need 800 | |
6263 | The line looks like this: | |
6264 | ||
6265 | @smallexample | |
6266 | (if (> size 10000) | |
6267 | @end smallexample | |
6268 | ||
6269 | @need 1200 | |
6270 | @noindent | |
6271 | When the buffer is large, the then-part of the @code{if} expression is | |
6272 | evaluated. It reads like this (after formatting for easy reading): | |
6273 | ||
6274 | @smallexample | |
6275 | @group | |
6276 | (* | |
6277 | (prefix-numeric-value arg) | |
6278 | (/ size 10)) | |
6279 | @end group | |
6280 | @end smallexample | |
6281 | ||
6282 | @noindent | |
6283 | This expression is a multiplication, with two arguments to the function | |
6284 | @code{*}. | |
6285 | ||
6286 | The first argument is @code{(prefix-numeric-value arg)}. When | |
6287 | @code{"P"} is used as the argument for @code{interactive}, the value | |
6288 | passed to the function as its argument is passed a ``raw prefix | |
6289 | argument'', and not a number. (It is a number in a list.) To perform | |
6290 | the arithmetic, a conversion is necessary, and | |
6291 | @code{prefix-numeric-value} does the job. | |
6292 | ||
6293 | @findex / @r{(division)} | |
6294 | @cindex Division | |
6295 | The second argument is @code{(/ size 10)}. This expression divides | |
f99f1641 | 6296 | the numeric value by ten---the numeric value of the size of the |
8cda6f8f GM |
6297 | accessible portion of the buffer. This produces a number that tells |
6298 | how many characters make up one tenth of the buffer size. (In Lisp, | |
6299 | @code{/} is used for division, just as @code{*} is used for | |
6300 | multiplication.) | |
6301 | ||
6302 | @need 1200 | |
6303 | In the multiplication expression as a whole, this amount is multiplied | |
6304 | by the value of the prefix argument---the multiplication looks like this: | |
6305 | ||
6306 | @smallexample | |
6307 | @group | |
6308 | (* @var{numeric-value-of-prefix-arg} | |
6309 | @var{number-of-characters-in-one-tenth-of-the-accessible-buffer}) | |
6310 | @end group | |
6311 | @end smallexample | |
6312 | ||
6313 | @noindent | |
6314 | If, for example, the prefix argument is @samp{7}, the one-tenth value | |
6315 | will be multiplied by 7 to give a position 70% of the way through. | |
6316 | ||
6317 | @need 1200 | |
6318 | The result of all this is that if the accessible portion of the buffer | |
6319 | is large, the @code{goto-char} expression reads like this: | |
6320 | ||
6321 | @smallexample | |
6322 | @group | |
6323 | (goto-char (* (prefix-numeric-value arg) | |
6324 | (/ size 10))) | |
6325 | @end group | |
6326 | @end smallexample | |
6327 | ||
6328 | This puts the cursor where we want it. | |
6329 | ||
d6adf7e7 | 6330 | @node Small buffer case |
8cda6f8f GM |
6331 | @unnumberedsubsubsec What happens in a small buffer |
6332 | ||
6333 | If the buffer contains fewer than 10,000 characters, a slightly | |
6334 | different computation is performed. You might think this is not | |
6335 | necessary, since the first computation could do the job. However, in | |
6336 | a small buffer, the first method may not put the cursor on exactly the | |
6337 | desired line; the second method does a better job. | |
6338 | ||
6339 | @need 800 | |
6340 | The code looks like this: | |
6341 | ||
6342 | @c Keep this on one line. | |
6343 | @smallexample | |
6344 | (/ (+ 10 (* size (prefix-numeric-value arg))) 10)) | |
6345 | @end smallexample | |
6346 | ||
6347 | @need 1200 | |
6348 | @noindent | |
6349 | This is code in which you figure out what happens by discovering how the | |
6350 | functions are embedded in parentheses. It is easier to read if you | |
6351 | reformat it with each expression indented more deeply than its | |
6352 | enclosing expression: | |
6353 | ||
6354 | @smallexample | |
6355 | @group | |
6356 | (/ | |
6357 | (+ 10 | |
6358 | (* | |
6359 | size | |
6360 | (prefix-numeric-value arg))) | |
6361 | 10)) | |
6362 | @end group | |
6363 | @end smallexample | |
6364 | ||
6365 | @need 1200 | |
6366 | @noindent | |
6367 | Looking at parentheses, we see that the innermost operation is | |
6368 | @code{(prefix-numeric-value arg)}, which converts the raw argument to | |
6369 | a number. In the following expression, this number is multiplied by | |
6370 | the size of the accessible portion of the buffer: | |
6371 | ||
6372 | @smallexample | |
6373 | (* size (prefix-numeric-value arg)) | |
6374 | @end smallexample | |
6375 | ||
6376 | @noindent | |
6377 | This multiplication creates a number that may be larger than the size of | |
6378 | the buffer---seven times larger if the argument is 7, for example. Ten | |
6379 | is then added to this number and finally the large number is divided by | |
6380 | ten to provide a value that is one character larger than the percentage | |
6381 | position in the buffer. | |
6382 | ||
6383 | The number that results from all this is passed to @code{goto-char} and | |
6384 | the cursor is moved to that point. | |
6385 | ||
6386 | @need 1500 | |
d6adf7e7 | 6387 | @node beginning-of-buffer complete |
8cda6f8f GM |
6388 | @subsection The Complete @code{beginning-of-buffer} |
6389 | ||
6390 | @need 1000 | |
6391 | Here is the complete text of the @code{beginning-of-buffer} function: | |
6392 | @sp 1 | |
6393 | ||
6394 | @c In GNU Emacs 22 | |
6395 | @smallexample | |
6396 | @group | |
6397 | (defun beginning-of-buffer (&optional arg) | |
6398 | "Move point to the beginning of the buffer; | |
6399 | leave mark at previous position. | |
6400 | With \\[universal-argument] prefix, | |
6401 | do not set mark at previous position. | |
6402 | With numeric arg N, | |
6403 | put point N/10 of the way from the beginning. | |
6404 | ||
6405 | If the buffer is narrowed, | |
6406 | this command uses the beginning and size | |
6407 | of the accessible part of the buffer. | |
6408 | @end group | |
6409 | ||
6410 | @group | |
6411 | Don't use this command in Lisp programs! | |
6412 | \(goto-char (point-min)) is faster | |
6413 | and avoids clobbering the mark." | |
6414 | (interactive "P") | |
6415 | (or (consp arg) | |
6416 | (and transient-mark-mode mark-active) | |
6417 | (push-mark)) | |
6418 | @end group | |
6419 | @group | |
6420 | (let ((size (- (point-max) (point-min)))) | |
6421 | (goto-char (if (and arg (not (consp arg))) | |
6422 | (+ (point-min) | |
6423 | (if (> size 10000) | |
6424 | ;; Avoid overflow for large buffer sizes! | |
6425 | (* (prefix-numeric-value arg) | |
6426 | (/ size 10)) | |
a9097c6d KB |
6427 | (/ (+ 10 (* size (prefix-numeric-value arg))) |
6428 | 10))) | |
8cda6f8f GM |
6429 | (point-min)))) |
6430 | (if arg (forward-line 1))) | |
6431 | @end group | |
6432 | @end smallexample | |
6433 | ||
6434 | @ignore | |
6435 | From before GNU Emacs 22 | |
6436 | @smallexample | |
6437 | @group | |
6438 | (defun beginning-of-buffer (&optional arg) | |
6439 | "Move point to the beginning of the buffer; | |
6440 | leave mark at previous position. | |
6441 | With arg N, put point N/10 of the way | |
6442 | from the true beginning. | |
6443 | @end group | |
6444 | @group | |
6445 | Don't use this in Lisp programs! | |
6446 | \(goto-char (point-min)) is faster | |
6447 | and does not set the mark." | |
6448 | (interactive "P") | |
6449 | (push-mark) | |
6450 | @end group | |
6451 | @group | |
6452 | (goto-char | |
6453 | (if arg | |
6454 | (if (> (buffer-size) 10000) | |
6455 | ;; @r{Avoid overflow for large buffer sizes!} | |
6456 | (* (prefix-numeric-value arg) | |
6457 | (/ (buffer-size) 10)) | |
6458 | @end group | |
6459 | @group | |
6460 | (/ (+ 10 (* (buffer-size) | |
6461 | (prefix-numeric-value arg))) | |
6462 | 10)) | |
6463 | (point-min))) | |
6464 | (if arg (forward-line 1))) | |
6465 | @end group | |
6466 | @end smallexample | |
6467 | @end ignore | |
6468 | ||
6469 | @noindent | |
6470 | Except for two small points, the previous discussion shows how this | |
6471 | function works. The first point deals with a detail in the | |
6472 | documentation string, and the second point concerns the last line of | |
6473 | the function. | |
6474 | ||
6475 | @need 800 | |
6476 | In the documentation string, there is reference to an expression: | |
6477 | ||
6478 | @smallexample | |
6479 | \\[universal-argument] | |
6480 | @end smallexample | |
6481 | ||
6482 | @noindent | |
6483 | A @samp{\\} is used before the first square bracket of this | |
6484 | expression. This @samp{\\} tells the Lisp interpreter to substitute | |
6485 | whatever key is currently bound to the @samp{[@dots{}]}. In the case | |
6486 | of @code{universal-argument}, that is usually @kbd{C-u}, but it might | |
6487 | be different. (@xref{Documentation Tips, , Tips for Documentation | |
6488 | Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more | |
6489 | information.) | |
6490 | ||
6491 | @need 1200 | |
6492 | Finally, the last line of the @code{beginning-of-buffer} command says | |
6493 | to move point to the beginning of the next line if the command is | |
6494 | invoked with an argument: | |
6495 | ||
6496 | @smallexample | |
6497 | (if arg (forward-line 1))) | |
6498 | @end smallexample | |
6499 | ||
6500 | @noindent | |
6501 | This puts the cursor at the beginning of the first line after the | |
6502 | appropriate tenths position in the buffer. This is a flourish that | |
6503 | means that the cursor is always located @emph{at least} the requested | |
6504 | tenths of the way through the buffer, which is a nicety that is, | |
6505 | perhaps, not necessary, but which, if it did not occur, would be sure | |
6506 | to draw complaints. | |
6507 | ||
6508 | On the other hand, it also means that if you specify the command with | |
6509 | a @kbd{C-u}, but without a number, that is to say, if the `raw prefix | |
6510 | argument' is simply a cons cell, then the command puts you at the | |
6511 | beginning of the second line @dots{} I don't know whether this is | |
6512 | intended or whether no one has dealt with the code to avoid this | |
6513 | happening. | |
6514 | ||
d6adf7e7 | 6515 | @node Second Buffer Related Review |
8cda6f8f GM |
6516 | @section Review |
6517 | ||
6518 | Here is a brief summary of some of the topics covered in this chapter. | |
6519 | ||
6520 | @table @code | |
6521 | @item or | |
6522 | Evaluate each argument in sequence, and return the value of the first | |
6523 | argument that is not @code{nil}; if none return a value that is not | |
6524 | @code{nil}, return @code{nil}. In brief, return the first true value | |
6525 | of the arguments; return a true value if one @emph{or} any of the | |
6526 | others are true. | |
6527 | ||
6528 | @item and | |
6529 | Evaluate each argument in sequence, and if any are @code{nil}, return | |
6530 | @code{nil}; if none are @code{nil}, return the value of the last | |
6531 | argument. In brief, return a true value only if all the arguments are | |
6532 | true; return a true value if one @emph{and} each of the others is | |
6533 | true. | |
6534 | ||
6535 | @item &optional | |
6536 | A keyword used to indicate that an argument to a function definition | |
6537 | is optional; this means that the function can be evaluated without the | |
6538 | argument, if desired. | |
6539 | ||
6540 | @item prefix-numeric-value | |
6541 | Convert the `raw prefix argument' produced by @code{(interactive | |
6542 | "P")} to a numeric value. | |
6543 | ||
6544 | @item forward-line | |
6545 | Move point forward to the beginning of the next line, or if the argument | |
6546 | is greater than one, forward that many lines. If it can't move as far | |
6547 | forward as it is supposed to, @code{forward-line} goes forward as far as | |
6548 | it can and then returns a count of the number of additional lines it was | |
6549 | supposed to move but couldn't. | |
6550 | ||
6551 | @item erase-buffer | |
6552 | Delete the entire contents of the current buffer. | |
6553 | ||
6554 | @item bufferp | |
6555 | Return @code{t} if its argument is a buffer; otherwise return @code{nil}. | |
6556 | @end table | |
6557 | ||
d6adf7e7 | 6558 | @node optional Exercise |
8cda6f8f GM |
6559 | @section @code{optional} Argument Exercise |
6560 | ||
6561 | Write an interactive function with an optional argument that tests | |
6562 | whether its argument, a number, is greater than or equal to, or else, | |
6563 | less than the value of @code{fill-column}, and tells you which, in a | |
6564 | message. However, if you do not pass an argument to the function, use | |
6565 | 56 as a default value. | |
6566 | ||
d6adf7e7 | 6567 | @node Narrowing & Widening |
8cda6f8f GM |
6568 | @chapter Narrowing and Widening |
6569 | @cindex Focusing attention (narrowing) | |
6570 | @cindex Narrowing | |
6571 | @cindex Widening | |
6572 | ||
6573 | Narrowing is a feature of Emacs that makes it possible for you to focus | |
6574 | on a specific part of a buffer, and work without accidentally changing | |
6575 | other parts. Narrowing is normally disabled since it can confuse | |
6576 | novices. | |
6577 | ||
6578 | @menu | |
6579 | * Narrowing advantages:: The advantages of narrowing | |
6580 | * save-restriction:: The @code{save-restriction} special form. | |
6581 | * what-line:: The number of the line that point is on. | |
6582 | * narrow Exercise:: | |
6583 | @end menu | |
6584 | ||
8cda6f8f | 6585 | @ifnottex |
d6adf7e7 | 6586 | @node Narrowing advantages |
8cda6f8f GM |
6587 | @unnumberedsec The Advantages of Narrowing |
6588 | @end ifnottex | |
6589 | ||
6590 | With narrowing, the rest of a buffer is made invisible, as if it weren't | |
6591 | there. This is an advantage if, for example, you want to replace a word | |
6592 | in one part of a buffer but not in another: you narrow to the part you want | |
6593 | and the replacement is carried out only in that section, not in the rest | |
6594 | of the buffer. Searches will only work within a narrowed region, not | |
6595 | outside of one, so if you are fixing a part of a document, you can keep | |
6596 | yourself from accidentally finding parts you do not need to fix by | |
6597 | narrowing just to the region you want. | |
6598 | (The key binding for @code{narrow-to-region} is @kbd{C-x n n}.) | |
6599 | ||
6600 | However, narrowing does make the rest of the buffer invisible, which | |
6601 | can scare people who inadvertently invoke narrowing and think they | |
6602 | have deleted a part of their file. Moreover, the @code{undo} command | |
6603 | (which is usually bound to @kbd{C-x u}) does not turn off narrowing | |
6604 | (nor should it), so people can become quite desperate if they do not | |
6605 | know that they can return the rest of a buffer to visibility with the | |
6606 | @code{widen} command. | |
6607 | (The key binding for @code{widen} is @kbd{C-x n w}.) | |
6608 | ||
6609 | Narrowing is just as useful to the Lisp interpreter as to a human. | |
6610 | Often, an Emacs Lisp function is designed to work on just part of a | |
6611 | buffer; or conversely, an Emacs Lisp function needs to work on all of a | |
6612 | buffer that has been narrowed. The @code{what-line} function, for | |
6613 | example, removes the narrowing from a buffer, if it has any narrowing | |
6614 | and when it has finished its job, restores the narrowing to what it was. | |
7001d579 GZ |
6615 | On the other hand, the @code{count-lines} function |
6616 | uses narrowing to restrict itself to just that portion | |
8cda6f8f GM |
6617 | of the buffer in which it is interested and then restores the previous |
6618 | situation. | |
6619 | ||
d6adf7e7 | 6620 | @node save-restriction |
8cda6f8f GM |
6621 | @section The @code{save-restriction} Special Form |
6622 | @findex save-restriction | |
6623 | ||
6624 | In Emacs Lisp, you can use the @code{save-restriction} special form to | |
6625 | keep track of whatever narrowing is in effect, if any. When the Lisp | |
6626 | interpreter meets with @code{save-restriction}, it executes the code | |
6627 | in the body of the @code{save-restriction} expression, and then undoes | |
6628 | any changes to narrowing that the code caused. If, for example, the | |
6629 | buffer is narrowed and the code that follows @code{save-restriction} | |
6630 | gets rid of the narrowing, @code{save-restriction} returns the buffer | |
6631 | to its narrowed region afterwards. In the @code{what-line} command, | |
6632 | any narrowing the buffer may have is undone by the @code{widen} | |
6633 | command that immediately follows the @code{save-restriction} command. | |
6634 | Any original narrowing is restored just before the completion of the | |
6635 | function. | |
6636 | ||
6637 | @need 1250 | |
6638 | The template for a @code{save-restriction} expression is simple: | |
6639 | ||
6640 | @smallexample | |
6641 | @group | |
6642 | (save-restriction | |
6643 | @var{body}@dots{} ) | |
6644 | @end group | |
6645 | @end smallexample | |
6646 | ||
6647 | @noindent | |
6648 | The body of the @code{save-restriction} is one or more expressions that | |
6649 | will be evaluated in sequence by the Lisp interpreter. | |
6650 | ||
6651 | Finally, a point to note: when you use both @code{save-excursion} and | |
6652 | @code{save-restriction}, one right after the other, you should use | |
6653 | @code{save-excursion} outermost. If you write them in reverse order, | |
6654 | you may fail to record narrowing in the buffer to which Emacs switches | |
6655 | after calling @code{save-excursion}. Thus, when written together, | |
6656 | @code{save-excursion} and @code{save-restriction} should be written | |
6657 | like this: | |
6658 | ||
6659 | @smallexample | |
6660 | @group | |
6661 | (save-excursion | |
6662 | (save-restriction | |
6663 | @var{body}@dots{})) | |
6664 | @end group | |
6665 | @end smallexample | |
6666 | ||
6667 | In other circumstances, when not written together, the | |
6668 | @code{save-excursion} and @code{save-restriction} special forms must | |
6669 | be written in the order appropriate to the function. | |
6670 | ||
6671 | @need 1250 | |
6672 | For example, | |
6673 | ||
6674 | @smallexample | |
6675 | @group | |
6676 | (save-restriction | |
6677 | (widen) | |
6678 | (save-excursion | |
6679 | @var{body}@dots{})) | |
6680 | @end group | |
6681 | @end smallexample | |
6682 | ||
6683 | @ignore | |
6684 | Emacs 22 | |
6685 | /usr/local/src/emacs/lisp/simple.el | |
6686 | ||
6687 | (defun what-line () | |
6688 | "Print the current buffer line number and narrowed line number of point." | |
6689 | (interactive) | |
6690 | (let ((start (point-min)) | |
6691 | (n (line-number-at-pos))) | |
6692 | (if (= start 1) | |
6693 | (message "Line %d" n) | |
6694 | (save-excursion | |
6695 | (save-restriction | |
6696 | (widen) | |
6697 | (message "line %d (narrowed line %d)" | |
6698 | (+ n (line-number-at-pos start) -1) n)))))) | |
6699 | ||
6700 | (defun line-number-at-pos (&optional pos) | |
6701 | "Return (narrowed) buffer line number at position POS. | |
6702 | If POS is nil, use current buffer location. | |
6703 | Counting starts at (point-min), so the value refers | |
6704 | to the contents of the accessible portion of the buffer." | |
6705 | (let ((opoint (or pos (point))) start) | |
6706 | (save-excursion | |
6707 | (goto-char (point-min)) | |
6708 | (setq start (point)) | |
6709 | (goto-char opoint) | |
6710 | (forward-line 0) | |
6711 | (1+ (count-lines start (point)))))) | |
6712 | ||
6713 | (defun count-lines (start end) | |
6714 | "Return number of lines between START and END. | |
6715 | This is usually the number of newlines between them, | |
6716 | but can be one more if START is not equal to END | |
6717 | and the greater of them is not at the start of a line." | |
6718 | (save-excursion | |
6719 | (save-restriction | |
6720 | (narrow-to-region start end) | |
6721 | (goto-char (point-min)) | |
6722 | (if (eq selective-display t) | |
6723 | (save-match-data | |
6724 | (let ((done 0)) | |
6725 | (while (re-search-forward "[\n\C-m]" nil t 40) | |
6726 | (setq done (+ 40 done))) | |
6727 | (while (re-search-forward "[\n\C-m]" nil t 1) | |
6728 | (setq done (+ 1 done))) | |
6729 | (goto-char (point-max)) | |
6730 | (if (and (/= start end) | |
6731 | (not (bolp))) | |
6732 | (1+ done) | |
6733 | done))) | |
6734 | (- (buffer-size) (forward-line (buffer-size))))))) | |
6735 | @end ignore | |
6736 | ||
d6adf7e7 | 6737 | @node what-line |
8cda6f8f GM |
6738 | @section @code{what-line} |
6739 | @findex what-line | |
6740 | @cindex Widening, example of | |
6741 | ||
6742 | The @code{what-line} command tells you the number of the line in which | |
6743 | the cursor is located. The function illustrates the use of the | |
6744 | @code{save-restriction} and @code{save-excursion} commands. Here is the | |
6745 | original text of the function: | |
6746 | ||
6747 | @smallexample | |
6748 | @group | |
6749 | (defun what-line () | |
6750 | "Print the current line number (in the buffer) of point." | |
6751 | (interactive) | |
6752 | (save-restriction | |
6753 | (widen) | |
6754 | (save-excursion | |
6755 | (beginning-of-line) | |
6756 | (message "Line %d" | |
6757 | (1+ (count-lines 1 (point))))))) | |
6758 | @end group | |
6759 | @end smallexample | |
6760 | ||
6761 | (In recent versions of GNU Emacs, the @code{what-line} function has | |
6762 | been expanded to tell you your line number in a narrowed buffer as | |
6763 | well as your line number in a widened buffer. The recent version is | |
6764 | more complex than the version shown here. If you feel adventurous, | |
6765 | you might want to look at it after figuring out how this version | |
6766 | works. You will probably need to use @kbd{C-h f} | |
6767 | (@code{describe-function}). The newer version uses a conditional to | |
6768 | determine whether the buffer has been narrowed. | |
6769 | ||
6770 | (Also, it uses @code{line-number-at-pos}, which among other simple | |
6771 | expressions, such as @code{(goto-char (point-min))}, moves point to | |
6772 | the beginning of the current line with @code{(forward-line 0)} rather | |
6773 | than @code{beginning-of-line}.) | |
6774 | ||
6775 | The @code{what-line} function as shown here has a documentation line | |
6776 | and is interactive, as you would expect. The next two lines use the | |
6777 | functions @code{save-restriction} and @code{widen}. | |
6778 | ||
6779 | The @code{save-restriction} special form notes whatever narrowing is in | |
6780 | effect, if any, in the current buffer and restores that narrowing after | |
6781 | the code in the body of the @code{save-restriction} has been evaluated. | |
6782 | ||
6783 | The @code{save-restriction} special form is followed by @code{widen}. | |
6784 | This function undoes any narrowing the current buffer may have had | |
6785 | when @code{what-line} was called. (The narrowing that was there is | |
6786 | the narrowing that @code{save-restriction} remembers.) This widening | |
6787 | makes it possible for the line counting commands to count from the | |
6788 | beginning of the buffer. Otherwise, they would have been limited to | |
6789 | counting within the accessible region. Any original narrowing is | |
6790 | restored just before the completion of the function by the | |
6791 | @code{save-restriction} special form. | |
6792 | ||
6793 | The call to @code{widen} is followed by @code{save-excursion}, which | |
6794 | saves the location of the cursor (i.e., of point) and of the mark, and | |
6795 | restores them after the code in the body of the @code{save-excursion} | |
6796 | uses the @code{beginning-of-line} function to move point. | |
6797 | ||
6798 | (Note that the @code{(widen)} expression comes between the | |
6799 | @code{save-restriction} and @code{save-excursion} special forms. When | |
6800 | you write the two @code{save- @dots{}} expressions in sequence, write | |
6801 | @code{save-excursion} outermost.) | |
6802 | ||
6803 | @need 1200 | |
6804 | The last two lines of the @code{what-line} function are functions to | |
6805 | count the number of lines in the buffer and then print the number in the | |
6806 | echo area. | |
6807 | ||
6808 | @smallexample | |
6809 | @group | |
6810 | (message "Line %d" | |
6811 | (1+ (count-lines 1 (point))))))) | |
6812 | @end group | |
6813 | @end smallexample | |
6814 | ||
6815 | The @code{message} function prints a one-line message at the bottom of | |
6816 | the Emacs screen. The first argument is inside of quotation marks and | |
6817 | is printed as a string of characters. However, it may contain a | |
6818 | @samp{%d} expression to print a following argument. @samp{%d} prints | |
6819 | the argument as a decimal, so the message will say something such as | |
6820 | @samp{Line 243}. | |
6821 | ||
6822 | @need 1200 | |
6823 | The number that is printed in place of the @samp{%d} is computed by the | |
6824 | last line of the function: | |
6825 | ||
6826 | @smallexample | |
6827 | (1+ (count-lines 1 (point))) | |
6828 | @end smallexample | |
6829 | ||
6830 | @ignore | |
6831 | GNU Emacs 22 | |
6832 | ||
6833 | (defun count-lines (start end) | |
6834 | "Return number of lines between START and END. | |
6835 | This is usually the number of newlines between them, | |
6836 | but can be one more if START is not equal to END | |
6837 | and the greater of them is not at the start of a line." | |
6838 | (save-excursion | |
6839 | (save-restriction | |
6840 | (narrow-to-region start end) | |
6841 | (goto-char (point-min)) | |
6842 | (if (eq selective-display t) | |
6843 | (save-match-data | |
6844 | (let ((done 0)) | |
6845 | (while (re-search-forward "[\n\C-m]" nil t 40) | |
6846 | (setq done (+ 40 done))) | |
6847 | (while (re-search-forward "[\n\C-m]" nil t 1) | |
6848 | (setq done (+ 1 done))) | |
6849 | (goto-char (point-max)) | |
6850 | (if (and (/= start end) | |
6851 | (not (bolp))) | |
6852 | (1+ done) | |
6853 | done))) | |
6854 | (- (buffer-size) (forward-line (buffer-size))))))) | |
6855 | @end ignore | |
6856 | ||
6857 | @noindent | |
6858 | What this does is count the lines from the first position of the | |
6859 | buffer, indicated by the @code{1}, up to @code{(point)}, and then add | |
6860 | one to that number. (The @code{1+} function adds one to its | |
6861 | argument.) We add one to it because line 2 has only one line before | |
6862 | it, and @code{count-lines} counts only the lines @emph{before} the | |
6863 | current line. | |
6864 | ||
6865 | After @code{count-lines} has done its job, and the message has been | |
6866 | printed in the echo area, the @code{save-excursion} restores point and | |
6867 | mark to their original positions; and @code{save-restriction} restores | |
6868 | the original narrowing, if any. | |
6869 | ||
d6adf7e7 | 6870 | @node narrow Exercise |
8cda6f8f GM |
6871 | @section Exercise with Narrowing |
6872 | ||
6873 | Write a function that will display the first 60 characters of the | |
6874 | current buffer, even if you have narrowed the buffer to its latter | |
6875 | half so that the first line is inaccessible. Restore point, mark, and | |
6876 | narrowing. For this exercise, you need to use a whole potpourri of | |
6877 | functions, including @code{save-restriction}, @code{widen}, | |
6878 | @code{goto-char}, @code{point-min}, @code{message}, and | |
6879 | @code{buffer-substring}. | |
6880 | ||
6881 | @cindex Properties, mention of @code{buffer-substring-no-properties} | |
6882 | (@code{buffer-substring} is a previously unmentioned function you will | |
6883 | have to investigate yourself; or perhaps you will have to use | |
6884 | @code{buffer-substring-no-properties} or | |
6885 | @code{filter-buffer-substring} @dots{}, yet other functions. Text | |
6886 | properties are a feature otherwise not discussed here. @xref{Text | |
6887 | Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference | |
6888 | Manual}.) | |
6889 | ||
6890 | Additionally, do you really need @code{goto-char} or @code{point-min}? | |
6891 | Or can you write the function without them? | |
6892 | ||
d6adf7e7 | 6893 | @node car cdr & cons |
8cda6f8f GM |
6894 | @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions |
6895 | @findex car, @r{introduced} | |
6896 | @findex cdr, @r{introduced} | |
6897 | ||
6898 | In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental | |
6899 | functions. The @code{cons} function is used to construct lists, and | |
6900 | the @code{car} and @code{cdr} functions are used to take them apart. | |
6901 | ||
6902 | In the walk through of the @code{copy-region-as-kill} function, we | |
6903 | will see @code{cons} as well as two variants on @code{cdr}, | |
6904 | namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.) | |
6905 | ||
6906 | @menu | |
6907 | * Strange Names:: An historical aside: why the strange names? | |
6908 | * car & cdr:: Functions for extracting part of a list. | |
6909 | * cons:: Constructing a list. | |
6910 | * nthcdr:: Calling @code{cdr} repeatedly. | |
6911 | * nth:: | |
6912 | * setcar:: Changing the first element of a list. | |
6913 | * setcdr:: Changing the rest of a list. | |
6914 | * cons Exercise:: | |
6915 | @end menu | |
6916 | ||
8cda6f8f | 6917 | @ifnottex |
d6adf7e7 | 6918 | @node Strange Names |
8cda6f8f GM |
6919 | @unnumberedsec Strange Names |
6920 | @end ifnottex | |
6921 | ||
6922 | The name of the @code{cons} function is not unreasonable: it is an | |
6923 | abbreviation of the word `construct'. The origins of the names for | |
6924 | @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car} | |
6925 | is an acronym from the phrase `Contents of the Address part of the | |
6926 | Register'; and @code{cdr} (pronounced `could-er') is an acronym from | |
6927 | the phrase `Contents of the Decrement part of the Register'. These | |
6928 | phrases refer to specific pieces of hardware on the very early | |
6929 | computer on which the original Lisp was developed. Besides being | |
6930 | obsolete, the phrases have been completely irrelevant for more than 25 | |
6931 | years to anyone thinking about Lisp. Nonetheless, although a few | |
6932 | brave scholars have begun to use more reasonable names for these | |
6933 | functions, the old terms are still in use. In particular, since the | |
6934 | terms are used in the Emacs Lisp source code, we will use them in this | |
6935 | introduction. | |
6936 | ||
d6adf7e7 | 6937 | @node car & cdr |
8cda6f8f GM |
6938 | @section @code{car} and @code{cdr} |
6939 | ||
6940 | The @sc{car} of a list is, quite simply, the first item in the list. | |
6941 | Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is | |
6942 | @code{rose}. | |
6943 | ||
6944 | @need 1200 | |
6945 | If you are reading this in Info in GNU Emacs, you can see this by | |
6946 | evaluating the following: | |
6947 | ||
6948 | @smallexample | |
6949 | (car '(rose violet daisy buttercup)) | |
6950 | @end smallexample | |
6951 | ||
6952 | @noindent | |
6953 | After evaluating the expression, @code{rose} will appear in the echo | |
6954 | area. | |
6955 | ||
6956 | Clearly, a more reasonable name for the @code{car} function would be | |
6957 | @code{first} and this is often suggested. | |
6958 | ||
6959 | @code{car} does not remove the first item from the list; it only reports | |
6960 | what it is. After @code{car} has been applied to a list, the list is | |
6961 | still the same as it was. In the jargon, @code{car} is | |
6962 | `non-destructive'. This feature turns out to be important. | |
6963 | ||
6964 | The @sc{cdr} of a list is the rest of the list, that is, the | |
6965 | @code{cdr} function returns the part of the list that follows the | |
6966 | first item. Thus, while the @sc{car} of the list @code{'(rose violet | |
6967 | daisy buttercup)} is @code{rose}, the rest of the list, the value | |
6968 | returned by the @code{cdr} function, is @code{(violet daisy | |
6969 | buttercup)}. | |
6970 | ||
6971 | @need 800 | |
6972 | You can see this by evaluating the following in the usual way: | |
6973 | ||
6974 | @smallexample | |
6975 | (cdr '(rose violet daisy buttercup)) | |
6976 | @end smallexample | |
6977 | ||
6978 | @noindent | |
6979 | When you evaluate this, @code{(violet daisy buttercup)} will appear in | |
6980 | the echo area. | |
6981 | ||
6982 | Like @code{car}, @code{cdr} does not remove any elements from the | |
6983 | list---it just returns a report of what the second and subsequent | |
6984 | elements are. | |
6985 | ||
6986 | Incidentally, in the example, the list of flowers is quoted. If it were | |
6987 | not, the Lisp interpreter would try to evaluate the list by calling | |
6988 | @code{rose} as a function. In this example, we do not want to do that. | |
6989 | ||
6990 | Clearly, a more reasonable name for @code{cdr} would be @code{rest}. | |
6991 | ||
6992 | (There is a lesson here: when you name new functions, consider very | |
6993 | carefully what you are doing, since you may be stuck with the names | |
6994 | for far longer than you expect. The reason this document perpetuates | |
6995 | these names is that the Emacs Lisp source code uses them, and if I did | |
6996 | not use them, you would have a hard time reading the code; but do, | |
6997 | please, try to avoid using these terms yourself. The people who come | |
6998 | after you will be grateful to you.) | |
6999 | ||
7000 | When @code{car} and @code{cdr} are applied to a list made up of symbols, | |
7001 | such as the list @code{(pine fir oak maple)}, the element of the list | |
7002 | returned by the function @code{car} is the symbol @code{pine} without | |
7003 | any parentheses around it. @code{pine} is the first element in the | |
7004 | list. However, the @sc{cdr} of the list is a list itself, @code{(fir | |
7005 | oak maple)}, as you can see by evaluating the following expressions in | |
7006 | the usual way: | |
7007 | ||
7008 | @smallexample | |
7009 | @group | |
7010 | (car '(pine fir oak maple)) | |
7011 | ||
7012 | (cdr '(pine fir oak maple)) | |
7013 | @end group | |
7014 | @end smallexample | |
7015 | ||
7016 | On the other hand, in a list of lists, the first element is itself a | |
7017 | list. @code{car} returns this first element as a list. For example, | |
7018 | the following list contains three sub-lists, a list of carnivores, a | |
7019 | list of herbivores and a list of sea mammals: | |
7020 | ||
7021 | @smallexample | |
7022 | @group | |
7023 | (car '((lion tiger cheetah) | |
7024 | (gazelle antelope zebra) | |
7025 | (whale dolphin seal))) | |
7026 | @end group | |
7027 | @end smallexample | |
7028 | ||
7029 | @noindent | |
7030 | In this example, the first element or @sc{car} of the list is the list of | |
7031 | carnivores, @code{(lion tiger cheetah)}, and the rest of the list is | |
7032 | @code{((gazelle antelope zebra) (whale dolphin seal))}. | |
7033 | ||
7034 | @smallexample | |
7035 | @group | |
7036 | (cdr '((lion tiger cheetah) | |
7037 | (gazelle antelope zebra) | |
7038 | (whale dolphin seal))) | |
7039 | @end group | |
7040 | @end smallexample | |
7041 | ||
7042 | It is worth saying again that @code{car} and @code{cdr} are | |
7043 | non-destructive---that is, they do not modify or change lists to which | |
7044 | they are applied. This is very important for how they are used. | |
7045 | ||
7046 | Also, in the first chapter, in the discussion about atoms, I said that | |
7047 | in Lisp, ``certain kinds of atom, such as an array, can be separated | |
7048 | into parts; but the mechanism for doing this is different from the | |
7049 | mechanism for splitting a list. As far as Lisp is concerned, the | |
7050 | atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The | |
7051 | @code{car} and @code{cdr} functions are used for splitting lists and | |
7052 | are considered fundamental to Lisp. Since they cannot split or gain | |
7053 | access to the parts of an array, an array is considered an atom. | |
7054 | Conversely, the other fundamental function, @code{cons}, can put | |
7055 | together or construct a list, but not an array. (Arrays are handled | |
7056 | by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU | |
7057 | Emacs Lisp Reference Manual}.) | |
7058 | ||
d6adf7e7 | 7059 | @node cons |
8cda6f8f GM |
7060 | @section @code{cons} |
7061 | @findex cons, @r{introduced} | |
7062 | ||
7063 | The @code{cons} function constructs lists; it is the inverse of | |
7064 | @code{car} and @code{cdr}. For example, @code{cons} can be used to make | |
7065 | a four element list from the three element list, @code{(fir oak maple)}: | |
7066 | ||
7067 | @smallexample | |
7068 | (cons 'pine '(fir oak maple)) | |
7069 | @end smallexample | |
7070 | ||
7071 | @need 800 | |
7072 | @noindent | |
7073 | After evaluating this list, you will see | |
7074 | ||
7075 | @smallexample | |
7076 | (pine fir oak maple) | |
7077 | @end smallexample | |
7078 | ||
7079 | @noindent | |
7080 | appear in the echo area. @code{cons} causes the creation of a new | |
7081 | list in which the element is followed by the elements of the original | |
7082 | list. | |
7083 | ||
7084 | We often say that `@code{cons} puts a new element at the beginning of | |
7085 | a list; it attaches or pushes elements onto the list', but this | |
7086 | phrasing can be misleading, since @code{cons} does not change an | |
7087 | existing list, but creates a new one. | |
7088 | ||
7089 | Like @code{car} and @code{cdr}, @code{cons} is non-destructive. | |
7090 | ||
7091 | @menu | |
7092 | * Build a list:: | |
7093 | * length:: How to find the length of a list. | |
7094 | @end menu | |
7095 | ||
8cda6f8f | 7096 | @ifnottex |
d6adf7e7 | 7097 | @node Build a list |
8cda6f8f GM |
7098 | @unnumberedsubsec Build a list |
7099 | @end ifnottex | |
7100 | ||
7101 | @code{cons} must have a list to attach to.@footnote{Actually, you can | |
7102 | @code{cons} an element to an atom to produce a dotted pair. Dotted | |
7103 | pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted | |
7104 | Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You | |
7105 | cannot start from absolutely nothing. If you are building a list, you | |
7106 | need to provide at least an empty list at the beginning. Here is a | |
7107 | series of @code{cons} expressions that build up a list of flowers. If | |
7108 | you are reading this in Info in GNU Emacs, you can evaluate each of | |
7109 | the expressions in the usual way; the value is printed in this text | |
7110 | after @samp{@result{}}, which you may read as `evaluates to'. | |
7111 | ||
7112 | @smallexample | |
7113 | @group | |
7114 | (cons 'buttercup ()) | |
7115 | @result{} (buttercup) | |
7116 | @end group | |
7117 | ||
7118 | @group | |
7119 | (cons 'daisy '(buttercup)) | |
7120 | @result{} (daisy buttercup) | |
7121 | @end group | |
7122 | ||
7123 | @group | |
7124 | (cons 'violet '(daisy buttercup)) | |
7125 | @result{} (violet daisy buttercup) | |
7126 | @end group | |
7127 | ||
7128 | @group | |
7129 | (cons 'rose '(violet daisy buttercup)) | |
7130 | @result{} (rose violet daisy buttercup) | |
7131 | @end group | |
7132 | @end smallexample | |
7133 | ||
7134 | @noindent | |
7135 | In the first example, the empty list is shown as @code{()} and a list | |
7136 | made up of @code{buttercup} followed by the empty list is constructed. | |
7137 | As you can see, the empty list is not shown in the list that was | |
7138 | constructed. All that you see is @code{(buttercup)}. The empty list is | |
7139 | not counted as an element of a list because there is nothing in an empty | |
7140 | list. Generally speaking, an empty list is invisible. | |
7141 | ||
7142 | The second example, @code{(cons 'daisy '(buttercup))} constructs a new, | |
7143 | two element list by putting @code{daisy} in front of @code{buttercup}; | |
7144 | and the third example constructs a three element list by putting | |
7145 | @code{violet} in front of @code{daisy} and @code{buttercup}. | |
7146 | ||
d6adf7e7 | 7147 | @node length |
8cda6f8f GM |
7148 | @subsection Find the Length of a List: @code{length} |
7149 | @findex length | |
7150 | ||
7151 | You can find out how many elements there are in a list by using the Lisp | |
7152 | function @code{length}, as in the following examples: | |
7153 | ||
7154 | @smallexample | |
7155 | @group | |
7156 | (length '(buttercup)) | |
7157 | @result{} 1 | |
7158 | @end group | |
7159 | ||
7160 | @group | |
7161 | (length '(daisy buttercup)) | |
7162 | @result{} 2 | |
7163 | @end group | |
7164 | ||
7165 | @group | |
7166 | (length (cons 'violet '(daisy buttercup))) | |
7167 | @result{} 3 | |
7168 | @end group | |
7169 | @end smallexample | |
7170 | ||
7171 | @noindent | |
7172 | In the third example, the @code{cons} function is used to construct a | |
7173 | three element list which is then passed to the @code{length} function as | |
7174 | its argument. | |
7175 | ||
7176 | @need 1200 | |
7177 | We can also use @code{length} to count the number of elements in an | |
7178 | empty list: | |
7179 | ||
7180 | @smallexample | |
7181 | @group | |
7182 | (length ()) | |
7183 | @result{} 0 | |
7184 | @end group | |
7185 | @end smallexample | |
7186 | ||
7187 | @noindent | |
7188 | As you would expect, the number of elements in an empty list is zero. | |
7189 | ||
7190 | An interesting experiment is to find out what happens if you try to find | |
7191 | the length of no list at all; that is, if you try to call @code{length} | |
7192 | without giving it an argument, not even an empty list: | |
7193 | ||
7194 | @smallexample | |
7195 | (length ) | |
7196 | @end smallexample | |
7197 | ||
7198 | @need 800 | |
7199 | @noindent | |
7200 | What you see, if you evaluate this, is the error message | |
7201 | ||
7202 | @smallexample | |
7203 | Lisp error: (wrong-number-of-arguments length 0) | |
7204 | @end smallexample | |
7205 | ||
7206 | @noindent | |
7207 | This means that the function receives the wrong number of | |
7208 | arguments, zero, when it expects some other number of arguments. In | |
7209 | this case, one argument is expected, the argument being a list whose | |
7210 | length the function is measuring. (Note that @emph{one} list is | |
7211 | @emph{one} argument, even if the list has many elements inside it.) | |
7212 | ||
7213 | The part of the error message that says @samp{length} is the name of | |
7214 | the function. | |
7215 | ||
7216 | @ignore | |
7217 | @code{length} is still a subroutine, but you need C-h f to discover that. | |
7218 | ||
7219 | In an earlier version: | |
7220 | This is written with a special notation, @samp{#<subr}, | |
7221 | that indicates that the function @code{length} is one of the primitive | |
7222 | functions written in C rather than in Emacs Lisp. (@samp{subr} is an | |
7223 | abbreviation for `subroutine'.) @xref{What Is a Function, , What Is a | |
7224 | Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more | |
7225 | about subroutines. | |
7226 | @end ignore | |
7227 | ||
d6adf7e7 | 7228 | @node nthcdr |
8cda6f8f GM |
7229 | @section @code{nthcdr} |
7230 | @findex nthcdr | |
7231 | ||
7232 | The @code{nthcdr} function is associated with the @code{cdr} function. | |
7233 | What it does is take the @sc{cdr} of a list repeatedly. | |
7234 | ||
7235 | If you take the @sc{cdr} of the list @code{(pine fir | |
7236 | oak maple)}, you will be returned the list @code{(fir oak maple)}. If you | |
7237 | repeat this on what was returned, you will be returned the list | |
7238 | @code{(oak maple)}. (Of course, repeated @sc{cdr}ing on the original | |
7239 | list will just give you the original @sc{cdr} since the function does | |
7240 | not change the list. You need to evaluate the @sc{cdr} of the | |
7241 | @sc{cdr} and so on.) If you continue this, eventually you will be | |
7242 | returned an empty list, which in this case, instead of being shown as | |
7243 | @code{()} is shown as @code{nil}. | |
7244 | ||
7245 | @need 1200 | |
7246 | For review, here is a series of repeated @sc{cdr}s, the text following | |
7247 | the @samp{@result{}} shows what is returned. | |
7248 | ||
7249 | @smallexample | |
7250 | @group | |
7251 | (cdr '(pine fir oak maple)) | |
7252 | @result{}(fir oak maple) | |
7253 | @end group | |
7254 | ||
7255 | @group | |
7256 | (cdr '(fir oak maple)) | |
7257 | @result{} (oak maple) | |
7258 | @end group | |
7259 | ||
7260 | @group | |
7261 | (cdr '(oak maple)) | |
7262 | @result{}(maple) | |
7263 | @end group | |
7264 | ||
7265 | @group | |
7266 | (cdr '(maple)) | |
7267 | @result{} nil | |
7268 | @end group | |
7269 | ||
7270 | @group | |
7271 | (cdr 'nil) | |
7272 | @result{} nil | |
7273 | @end group | |
7274 | ||
7275 | @group | |
7276 | (cdr ()) | |
7277 | @result{} nil | |
7278 | @end group | |
7279 | @end smallexample | |
7280 | ||
7281 | @need 1200 | |
7282 | You can also do several @sc{cdr}s without printing the values in | |
7283 | between, like this: | |
7284 | ||
7285 | @smallexample | |
7286 | @group | |
7287 | (cdr (cdr '(pine fir oak maple))) | |
7288 | @result{} (oak maple) | |
7289 | @end group | |
7290 | @end smallexample | |
7291 | ||
7292 | @noindent | |
7293 | In this example, the Lisp interpreter evaluates the innermost list first. | |
7294 | The innermost list is quoted, so it just passes the list as it is to the | |
7295 | innermost @code{cdr}. This @code{cdr} passes a list made up of the | |
7296 | second and subsequent elements of the list to the outermost @code{cdr}, | |
7297 | which produces a list composed of the third and subsequent elements of | |
7298 | the original list. In this example, the @code{cdr} function is repeated | |
7299 | and returns a list that consists of the original list without its | |
7300 | first two elements. | |
7301 | ||
7302 | The @code{nthcdr} function does the same as repeating the call to | |
7303 | @code{cdr}. In the following example, the argument 2 is passed to the | |
7304 | function @code{nthcdr}, along with the list, and the value returned is | |
7305 | the list without its first two items, which is exactly the same | |
7306 | as repeating @code{cdr} twice on the list: | |
7307 | ||
7308 | @smallexample | |
7309 | @group | |
7310 | (nthcdr 2 '(pine fir oak maple)) | |
7311 | @result{} (oak maple) | |
7312 | @end group | |
7313 | @end smallexample | |
7314 | ||
7315 | @need 1200 | |
7316 | Using the original four element list, we can see what happens when | |
7317 | various numeric arguments are passed to @code{nthcdr}, including 0, 1, | |
7318 | and 5: | |
7319 | ||
7320 | @smallexample | |
7321 | @group | |
7322 | ;; @r{Leave the list as it was.} | |
7323 | (nthcdr 0 '(pine fir oak maple)) | |
7324 | @result{} (pine fir oak maple) | |
7325 | @end group | |
7326 | ||
7327 | @group | |
7328 | ;; @r{Return a copy without the first element.} | |
7329 | (nthcdr 1 '(pine fir oak maple)) | |
7330 | @result{} (fir oak maple) | |
7331 | @end group | |
7332 | ||
7333 | @group | |
7334 | ;; @r{Return a copy of the list without three elements.} | |
7335 | (nthcdr 3 '(pine fir oak maple)) | |
7336 | @result{} (maple) | |
7337 | @end group | |
7338 | ||
7339 | @group | |
7340 | ;; @r{Return a copy lacking all four elements.} | |
7341 | (nthcdr 4 '(pine fir oak maple)) | |
7342 | @result{} nil | |
7343 | @end group | |
7344 | ||
7345 | @group | |
7346 | ;; @r{Return a copy lacking all elements.} | |
7347 | (nthcdr 5 '(pine fir oak maple)) | |
7348 | @result{} nil | |
7349 | @end group | |
7350 | @end smallexample | |
7351 | ||
d6adf7e7 | 7352 | @node nth |
8cda6f8f GM |
7353 | @section @code{nth} |
7354 | @findex nth | |
7355 | ||
7356 | The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly. | |
7357 | The @code{nth} function takes the @sc{car} of the result returned by | |
7358 | @code{nthcdr}. It returns the Nth element of the list. | |
7359 | ||
7360 | @need 1500 | |
7361 | Thus, if it were not defined in C for speed, the definition of | |
7362 | @code{nth} would be: | |
7363 | ||
7364 | @smallexample | |
7365 | @group | |
7366 | (defun nth (n list) | |
7367 | "Returns the Nth element of LIST. | |
7368 | N counts from zero. If LIST is not that long, nil is returned." | |
7369 | (car (nthcdr n list))) | |
7370 | @end group | |
7371 | @end smallexample | |
7372 | ||
7373 | @noindent | |
7374 | (Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el}, | |
7375 | but its definition was redone in C in the 1980s.) | |
7376 | ||
7377 | The @code{nth} function returns a single element of a list. | |
7378 | This can be very convenient. | |
7379 | ||
7380 | Note that the elements are numbered from zero, not one. That is to | |
7381 | say, the first element of a list, its @sc{car} is the zeroth element. | |
7382 | This is called `zero-based' counting and often bothers people who | |
7383 | are accustomed to the first element in a list being number one, which | |
7384 | is `one-based'. | |
7385 | ||
7386 | @need 1250 | |
7387 | For example: | |
7388 | ||
7389 | @smallexample | |
7390 | @group | |
7391 | (nth 0 '("one" "two" "three")) | |
7392 | @result{} "one" | |
7393 | ||
7394 | (nth 1 '("one" "two" "three")) | |
7395 | @result{} "two" | |
7396 | @end group | |
7397 | @end smallexample | |
7398 | ||
7399 | It is worth mentioning that @code{nth}, like @code{nthcdr} and | |
7400 | @code{cdr}, does not change the original list---the function is | |
7401 | non-destructive. This is in sharp contrast to the @code{setcar} and | |
7402 | @code{setcdr} functions. | |
7403 | ||
d6adf7e7 | 7404 | @node setcar |
8cda6f8f GM |
7405 | @section @code{setcar} |
7406 | @findex setcar | |
7407 | ||
7408 | As you might guess from their names, the @code{setcar} and @code{setcdr} | |
7409 | functions set the @sc{car} or the @sc{cdr} of a list to a new value. | |
7410 | They actually change the original list, unlike @code{car} and @code{cdr} | |
7411 | which leave the original list as it was. One way to find out how this | |
7412 | works is to experiment. We will start with the @code{setcar} function. | |
7413 | ||
7414 | @need 1200 | |
7415 | First, we can make a list and then set the value of a variable to the | |
7416 | list, using the @code{setq} function. Here is a list of animals: | |
7417 | ||
7418 | @smallexample | |
7419 | (setq animals '(antelope giraffe lion tiger)) | |
7420 | @end smallexample | |
7421 | ||
7422 | @noindent | |
7423 | If you are reading this in Info inside of GNU Emacs, you can evaluate | |
7424 | this expression in the usual fashion, by positioning the cursor after | |
7425 | the expression and typing @kbd{C-x C-e}. (I'm doing this right here | |
7426 | as I write this. This is one of the advantages of having the | |
7427 | interpreter built into the computing environment. Incidentally, when | |
7428 | there is nothing on the line after the final parentheses, such as a | |
7429 | comment, point can be on the next line. Thus, if your cursor is in | |
7430 | the first column of the next line, you do not need to move it. | |
7431 | Indeed, Emacs permits any amount of white space after the final | |
7432 | parenthesis.) | |
7433 | ||
7434 | @need 1200 | |
7435 | When we evaluate the variable @code{animals}, we see that it is bound to | |
7436 | the list @code{(antelope giraffe lion tiger)}: | |
7437 | ||
7438 | @smallexample | |
7439 | @group | |
7440 | animals | |
7441 | @result{} (antelope giraffe lion tiger) | |
7442 | @end group | |
7443 | @end smallexample | |
7444 | ||
7445 | @noindent | |
7446 | Put another way, the variable @code{animals} points to the list | |
7447 | @code{(antelope giraffe lion tiger)}. | |
7448 | ||
7449 | Next, evaluate the function @code{setcar} while passing it two | |
7450 | arguments, the variable @code{animals} and the quoted symbol | |
7451 | @code{hippopotamus}; this is done by writing the three element list | |
7452 | @code{(setcar animals 'hippopotamus)} and then evaluating it in the | |
7453 | usual fashion: | |
7454 | ||
7455 | @smallexample | |
7456 | (setcar animals 'hippopotamus) | |
7457 | @end smallexample | |
7458 | ||
7459 | @need 1200 | |
7460 | @noindent | |
7461 | After evaluating this expression, evaluate the variable @code{animals} | |
7462 | again. You will see that the list of animals has changed: | |
7463 | ||
7464 | @smallexample | |
7465 | @group | |
7466 | animals | |
7467 | @result{} (hippopotamus giraffe lion tiger) | |
7468 | @end group | |
7469 | @end smallexample | |
7470 | ||
7471 | @noindent | |
7472 | The first element on the list, @code{antelope} is replaced by | |
7473 | @code{hippopotamus}. | |
7474 | ||
7475 | So we can see that @code{setcar} did not add a new element to the list | |
7476 | as @code{cons} would have; it replaced @code{antelope} with | |
7477 | @code{hippopotamus}; it @emph{changed} the list. | |
7478 | ||
d6adf7e7 | 7479 | @node setcdr |
8cda6f8f GM |
7480 | @section @code{setcdr} |
7481 | @findex setcdr | |
7482 | ||
7483 | The @code{setcdr} function is similar to the @code{setcar} function, | |
7484 | except that the function replaces the second and subsequent elements of | |
7485 | a list rather than the first element. | |
7486 | ||
7487 | (To see how to change the last element of a list, look ahead to | |
7488 | @ref{kill-new function, , The @code{kill-new} function}, which uses | |
7489 | the @code{nthcdr} and @code{setcdr} functions.) | |
7490 | ||
7491 | @need 1200 | |
7492 | To see how this works, set the value of the variable to a list of | |
7493 | domesticated animals by evaluating the following expression: | |
7494 | ||
7495 | @smallexample | |
7496 | (setq domesticated-animals '(horse cow sheep goat)) | |
7497 | @end smallexample | |
7498 | ||
7499 | @need 1200 | |
7500 | @noindent | |
7501 | If you now evaluate the list, you will be returned the list | |
7502 | @code{(horse cow sheep goat)}: | |
7503 | ||
7504 | @smallexample | |
7505 | @group | |
7506 | domesticated-animals | |
7507 | @result{} (horse cow sheep goat) | |
7508 | @end group | |
7509 | @end smallexample | |
7510 | ||
7511 | @need 1200 | |
7512 | Next, evaluate @code{setcdr} with two arguments, the name of the | |
7513 | variable which has a list as its value, and the list to which the | |
7514 | @sc{cdr} of the first list will be set; | |
7515 | ||
7516 | @smallexample | |
7517 | (setcdr domesticated-animals '(cat dog)) | |
7518 | @end smallexample | |
7519 | ||
7520 | @noindent | |
7521 | If you evaluate this expression, the list @code{(cat dog)} will appear | |
7522 | in the echo area. This is the value returned by the function. The | |
7523 | result we are interested in is the ``side effect'', which we can see by | |
7524 | evaluating the variable @code{domesticated-animals}: | |
7525 | ||
7526 | @smallexample | |
7527 | @group | |
7528 | domesticated-animals | |
7529 | @result{} (horse cat dog) | |
7530 | @end group | |
7531 | @end smallexample | |
7532 | ||
7533 | @noindent | |
7534 | Indeed, the list is changed from @code{(horse cow sheep goat)} to | |
7535 | @code{(horse cat dog)}. The @sc{cdr} of the list is changed from | |
7536 | @code{(cow sheep goat)} to @code{(cat dog)}. | |
7537 | ||
d6adf7e7 | 7538 | @node cons Exercise |
8cda6f8f GM |
7539 | @section Exercise |
7540 | ||
7541 | Construct a list of four birds by evaluating several expressions with | |
7542 | @code{cons}. Find out what happens when you @code{cons} a list onto | |
7543 | itself. Replace the first element of the list of four birds with a | |
7544 | fish. Replace the rest of that list with a list of other fish. | |
7545 | ||
d6adf7e7 | 7546 | @node Cutting & Storing Text |
8cda6f8f GM |
7547 | @chapter Cutting and Storing Text |
7548 | @cindex Cutting and storing text | |
7549 | @cindex Storing and cutting text | |
7550 | @cindex Killing text | |
7551 | @cindex Clipping text | |
7552 | @cindex Erasing text | |
7553 | @cindex Deleting text | |
7554 | ||
7555 | Whenever you cut or clip text out of a buffer with a `kill' command in | |
7556 | GNU Emacs, it is stored in a list and you can bring it back with a | |
7557 | `yank' command. | |
7558 | ||
7559 | (The use of the word `kill' in Emacs for processes which specifically | |
7560 | @emph{do not} destroy the values of the entities is an unfortunate | |
7561 | historical accident. A much more appropriate word would be `clip' since | |
7562 | that is what the kill commands do; they clip text out of a buffer and | |
7563 | put it into storage from which it can be brought back. I have often | |
7564 | been tempted to replace globally all occurrences of `kill' in the Emacs | |
7565 | sources with `clip' and all occurrences of `killed' with `clipped'.) | |
7566 | ||
7567 | @menu | |
7568 | * Storing Text:: Text is stored in a list. | |
7569 | * zap-to-char:: Cutting out text up to a character. | |
7570 | * kill-region:: Cutting text out of a region. | |
7571 | * copy-region-as-kill:: A definition for copying text. | |
7572 | * Digression into C:: Minor note on C programming language macros. | |
7573 | * defvar:: How to give a variable an initial value. | |
7574 | * cons & search-fwd Review:: | |
7575 | * search Exercises:: | |
7576 | @end menu | |
7577 | ||
8cda6f8f | 7578 | @ifnottex |
d6adf7e7 | 7579 | @node Storing Text |
8cda6f8f GM |
7580 | @unnumberedsec Storing Text in a List |
7581 | @end ifnottex | |
7582 | ||
7583 | When text is cut out of a buffer, it is stored on a list. Successive | |
7584 | pieces of text are stored on the list successively, so the list might | |
7585 | look like this: | |
7586 | ||
7587 | @smallexample | |
7588 | ("a piece of text" "previous piece") | |
7589 | @end smallexample | |
7590 | ||
7591 | @need 1200 | |
7592 | @noindent | |
7593 | The function @code{cons} can be used to create a new list from a piece | |
7594 | of text (an `atom', to use the jargon) and an existing list, like | |
7595 | this: | |
7596 | ||
7597 | @smallexample | |
7598 | @group | |
7599 | (cons "another piece" | |
7600 | '("a piece of text" "previous piece")) | |
7601 | @end group | |
7602 | @end smallexample | |
7603 | ||
7604 | @need 1200 | |
7605 | @noindent | |
7606 | If you evaluate this expression, a list of three elements will appear in | |
7607 | the echo area: | |
7608 | ||
7609 | @smallexample | |
7610 | ("another piece" "a piece of text" "previous piece") | |
7611 | @end smallexample | |
7612 | ||
7613 | With the @code{car} and @code{nthcdr} functions, you can retrieve | |
7614 | whichever piece of text you want. For example, in the following code, | |
7615 | @code{nthcdr 1 @dots{}} returns the list with the first item removed; | |
7616 | and the @code{car} returns the first element of that remainder---the | |
7617 | second element of the original list: | |
7618 | ||
7619 | @smallexample | |
7620 | @group | |
7621 | (car (nthcdr 1 '("another piece" | |
7622 | "a piece of text" | |
7623 | "previous piece"))) | |
7624 | @result{} "a piece of text" | |
7625 | @end group | |
7626 | @end smallexample | |
7627 | ||
7628 | The actual functions in Emacs are more complex than this, of course. | |
7629 | The code for cutting and retrieving text has to be written so that | |
7630 | Emacs can figure out which element in the list you want---the first, | |
7631 | second, third, or whatever. In addition, when you get to the end of | |
7632 | the list, Emacs should give you the first element of the list, rather | |
7633 | than nothing at all. | |
7634 | ||
7635 | The list that holds the pieces of text is called the @dfn{kill ring}. | |
7636 | This chapter leads up to a description of the kill ring and how it is | |
7637 | used by first tracing how the @code{zap-to-char} function works. This | |
7638 | function uses (or `calls') a function that invokes a function that | |
7639 | manipulates the kill ring. Thus, before reaching the mountains, we | |
7640 | climb the foothills. | |
7641 | ||
7642 | A subsequent chapter describes how text that is cut from the buffer is | |
7643 | retrieved. @xref{Yanking, , Yanking Text Back}. | |
7644 | ||
d6adf7e7 | 7645 | @node zap-to-char |
8cda6f8f GM |
7646 | @section @code{zap-to-char} |
7647 | @findex zap-to-char | |
7648 | ||
8f4ea8e0 | 7649 | @c FIXME remove obsolete stuff |
8cda6f8f GM |
7650 | The @code{zap-to-char} function changed little between GNU Emacs |
7651 | version 19 and GNU Emacs version 22. However, @code{zap-to-char} | |
7652 | calls another function, @code{kill-region}, which enjoyed a major | |
7653 | rewrite. | |
7654 | ||
7655 | The @code{kill-region} function in Emacs 19 is complex, but does not | |
7656 | use code that is important at this time. We will skip it. | |
7657 | ||
7658 | The @code{kill-region} function in Emacs 22 is easier to read than the | |
7659 | same function in Emacs 19 and introduces a very important concept, | |
7660 | that of error handling. We will walk through the function. | |
7661 | ||
7662 | But first, let us look at the interactive @code{zap-to-char} function. | |
7663 | ||
7664 | @menu | |
7665 | * Complete zap-to-char:: The complete implementation. | |
7666 | * zap-to-char interactive:: A three part interactive expression. | |
7667 | * zap-to-char body:: A short overview. | |
7668 | * search-forward:: How to search for a string. | |
7669 | * progn:: The @code{progn} special form. | |
7670 | * Summing up zap-to-char:: Using @code{point} and @code{search-forward}. | |
7671 | @end menu | |
7672 | ||
8cda6f8f | 7673 | @ifnottex |
d6adf7e7 | 7674 | @node Complete zap-to-char |
8cda6f8f GM |
7675 | @unnumberedsubsec The Complete @code{zap-to-char} Implementation |
7676 | @end ifnottex | |
7677 | ||
7678 | The @code{zap-to-char} function removes the text in the region between | |
7679 | the location of the cursor (i.e., of point) up to and including the | |
7680 | next occurrence of a specified character. The text that | |
7681 | @code{zap-to-char} removes is put in the kill ring; and it can be | |
7682 | retrieved from the kill ring by typing @kbd{C-y} (@code{yank}). If | |
7683 | the command is given an argument, it removes text through that number | |
7684 | of occurrences. Thus, if the cursor were at the beginning of this | |
7685 | sentence and the character were @samp{s}, @samp{Thus} would be | |
7686 | removed. If the argument were two, @samp{Thus, if the curs} would be | |
7687 | removed, up to and including the @samp{s} in @samp{cursor}. | |
7688 | ||
7689 | If the specified character is not found, @code{zap-to-char} will say | |
7690 | ``Search failed'', tell you the character you typed, and not remove | |
7691 | any text. | |
7692 | ||
7693 | In order to determine how much text to remove, @code{zap-to-char} uses | |
7694 | a search function. Searches are used extensively in code that | |
7695 | manipulates text, and we will focus attention on them as well as on the | |
7696 | deletion command. | |
7697 | ||
7698 | @ignore | |
7699 | @c GNU Emacs version 19 | |
7700 | (defun zap-to-char (arg char) ; version 19 implementation | |
7701 | "Kill up to and including ARG'th occurrence of CHAR. | |
7702 | Goes backward if ARG is negative; error if CHAR not found." | |
7703 | (interactive "*p\ncZap to char: ") | |
7704 | (kill-region (point) | |
7705 | (progn | |
7706 | (search-forward | |
7707 | (char-to-string char) nil nil arg) | |
7708 | (point)))) | |
7709 | @end ignore | |
7710 | ||
7711 | @need 1250 | |
7712 | Here is the complete text of the version 22 implementation of the function: | |
7713 | ||
7714 | @c GNU Emacs 22 | |
7715 | @smallexample | |
7716 | @group | |
7717 | (defun zap-to-char (arg char) | |
7718 | "Kill up to and including ARG'th occurrence of CHAR. | |
7719 | Case is ignored if `case-fold-search' is non-nil in the current buffer. | |
7720 | Goes backward if ARG is negative; error if CHAR not found." | |
7721 | (interactive "p\ncZap to char: ") | |
7722 | (if (char-table-p translation-table-for-input) | |
7723 | (setq char (or (aref translation-table-for-input char) char))) | |
7724 | (kill-region (point) (progn | |
a9097c6d KB |
7725 | (search-forward (char-to-string char) |
7726 | nil nil arg) | |
8cda6f8f GM |
7727 | (point)))) |
7728 | @end group | |
7729 | @end smallexample | |
7730 | ||
7731 | The documentation is thorough. You do need to know the jargon meaning | |
7732 | of the word `kill'. | |
7733 | ||
d6adf7e7 | 7734 | @node zap-to-char interactive |
8cda6f8f GM |
7735 | @subsection The @code{interactive} Expression |
7736 | ||
7737 | @need 800 | |
7738 | The interactive expression in the @code{zap-to-char} command looks like | |
7739 | this: | |
7740 | ||
7741 | @smallexample | |
7742 | (interactive "p\ncZap to char: ") | |
7743 | @end smallexample | |
7744 | ||
7745 | The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies | |
7746 | two different things. First, and most simply, is the @samp{p}. | |
7747 | This part is separated from the next part by a newline, @samp{\n}. | |
7748 | The @samp{p} means that the first argument to the function will be | |
7749 | passed the value of a `processed prefix'. The prefix argument is | |
7750 | passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If | |
7751 | the function is called interactively without a prefix, 1 is passed to | |
7752 | this argument. | |
7753 | ||
7754 | The second part of @code{"p\ncZap to char:@: "} is | |
7755 | @samp{cZap to char:@: }. In this part, the lower case @samp{c} | |
7756 | indicates that @code{interactive} expects a prompt and that the | |
7757 | argument will be a character. The prompt follows the @samp{c} and is | |
7758 | the string @samp{Zap to char:@: } (with a space after the colon to | |
7759 | make it look good). | |
7760 | ||
7761 | What all this does is prepare the arguments to @code{zap-to-char} so they | |
7762 | are of the right type, and give the user a prompt. | |
7763 | ||
7764 | In a read-only buffer, the @code{zap-to-char} function copies the text | |
7765 | to the kill ring, but does not remove it. The echo area displays a | |
7766 | message saying that the buffer is read-only. Also, the terminal may | |
7767 | beep or blink at you. | |
7768 | ||
d6adf7e7 | 7769 | @node zap-to-char body |
8cda6f8f GM |
7770 | @subsection The Body of @code{zap-to-char} |
7771 | ||
7772 | The body of the @code{zap-to-char} function contains the code that | |
7773 | kills (that is, removes) the text in the region from the current | |
7774 | position of the cursor up to and including the specified character. | |
7775 | ||
7776 | The first part of the code looks like this: | |
7777 | ||
7778 | @smallexample | |
7779 | (if (char-table-p translation-table-for-input) | |
7780 | (setq char (or (aref translation-table-for-input char) char))) | |
7781 | (kill-region (point) (progn | |
7782 | (search-forward (char-to-string char) nil nil arg) | |
7783 | (point))) | |
7784 | @end smallexample | |
7785 | ||
7786 | @noindent | |
7787 | @code{char-table-p} is an hitherto unseen function. It determines | |
7788 | whether its argument is a character table. When it is, it sets the | |
7789 | character passed to @code{zap-to-char} to one of them, if that | |
7790 | character exists, or to the character itself. (This becomes important | |
7791 | for certain characters in non-European languages. The @code{aref} | |
7792 | function extracts an element from an array. It is an array-specific | |
7793 | function that is not described in this document. @xref{Arrays, , | |
7794 | Arrays, elisp, The GNU Emacs Lisp Reference Manual}.) | |
7795 | ||
7796 | @noindent | |
7797 | @code{(point)} is the current position of the cursor. | |
7798 | ||
7799 | The next part of the code is an expression using @code{progn}. The body | |
7800 | of the @code{progn} consists of calls to @code{search-forward} and | |
7801 | @code{point}. | |
7802 | ||
7803 | It is easier to understand how @code{progn} works after learning about | |
7804 | @code{search-forward}, so we will look at @code{search-forward} and | |
7805 | then at @code{progn}. | |
7806 | ||
d6adf7e7 | 7807 | @node search-forward |
8cda6f8f GM |
7808 | @subsection The @code{search-forward} Function |
7809 | @findex search-forward | |
7810 | ||
7811 | The @code{search-forward} function is used to locate the | |
7812 | zapped-for-character in @code{zap-to-char}. If the search is | |
7813 | successful, @code{search-forward} leaves point immediately after the | |
7814 | last character in the target string. (In @code{zap-to-char}, the | |
7815 | target string is just one character long. @code{zap-to-char} uses the | |
7816 | function @code{char-to-string} to ensure that the computer treats that | |
7817 | character as a string.) If the search is backwards, | |
7818 | @code{search-forward} leaves point just before the first character in | |
7819 | the target. Also, @code{search-forward} returns @code{t} for true. | |
7820 | (Moving point is therefore a `side effect'.) | |
7821 | ||
7822 | @need 1250 | |
7823 | In @code{zap-to-char}, the @code{search-forward} function looks like this: | |
7824 | ||
7825 | @smallexample | |
7826 | (search-forward (char-to-string char) nil nil arg) | |
7827 | @end smallexample | |
7828 | ||
7829 | The @code{search-forward} function takes four arguments: | |
7830 | ||
7831 | @enumerate | |
7832 | @item | |
7833 | The first argument is the target, what is searched for. This must be a | |
7834 | string, such as @samp{"z"}. | |
7835 | ||
7836 | As it happens, the argument passed to @code{zap-to-char} is a single | |
7837 | character. Because of the way computers are built, the Lisp | |
7838 | interpreter may treat a single character as being different from a | |
7839 | string of characters. Inside the computer, a single character has a | |
7840 | different electronic format than a string of one character. (A single | |
7841 | character can often be recorded in the computer using exactly one | |
7842 | byte; but a string may be longer, and the computer needs to be ready | |
7843 | for this.) Since the @code{search-forward} function searches for a | |
7844 | string, the character that the @code{zap-to-char} function receives as | |
7845 | its argument must be converted inside the computer from one format to | |
7846 | the other; otherwise the @code{search-forward} function will fail. | |
7847 | The @code{char-to-string} function is used to make this conversion. | |
7848 | ||
7849 | @item | |
7850 | The second argument bounds the search; it is specified as a position in | |
7851 | the buffer. In this case, the search can go to the end of the buffer, | |
7852 | so no bound is set and the second argument is @code{nil}. | |
7853 | ||
7854 | @item | |
7855 | The third argument tells the function what it should do if the search | |
7856 | fails---it can signal an error (and print a message) or it can return | |
7857 | @code{nil}. A @code{nil} as the third argument causes the function to | |
7858 | signal an error when the search fails. | |
7859 | ||
7860 | @item | |
7861 | The fourth argument to @code{search-forward} is the repeat count---how | |
7862 | many occurrences of the string to look for. This argument is optional | |
7863 | and if the function is called without a repeat count, this argument is | |
7864 | passed the value 1. If this argument is negative, the search goes | |
7865 | backwards. | |
7866 | @end enumerate | |
7867 | ||
7868 | @need 800 | |
7869 | In template form, a @code{search-forward} expression looks like this: | |
7870 | ||
7871 | @smallexample | |
7872 | @group | |
7873 | (search-forward "@var{target-string}" | |
7874 | @var{limit-of-search} | |
7875 | @var{what-to-do-if-search-fails} | |
7876 | @var{repeat-count}) | |
7877 | @end group | |
7878 | @end smallexample | |
7879 | ||
7880 | We will look at @code{progn} next. | |
7881 | ||
d6adf7e7 | 7882 | @node progn |
8cda6f8f GM |
7883 | @subsection The @code{progn} Special Form |
7884 | @findex progn | |
7885 | ||
7886 | @code{progn} is a special form that causes each of its arguments to be | |
7887 | evaluated in sequence and then returns the value of the last one. The | |
7888 | preceding expressions are evaluated only for the side effects they | |
7889 | perform. The values produced by them are discarded. | |
7890 | ||
7891 | @need 800 | |
7892 | The template for a @code{progn} expression is very simple: | |
7893 | ||
7894 | @smallexample | |
7895 | @group | |
7896 | (progn | |
7897 | @var{body}@dots{}) | |
7898 | @end group | |
7899 | @end smallexample | |
7900 | ||
7901 | In @code{zap-to-char}, the @code{progn} expression has to do two things: | |
7902 | put point in exactly the right position; and return the location of | |
7903 | point so that @code{kill-region} will know how far to kill to. | |
7904 | ||
7905 | The first argument to the @code{progn} is @code{search-forward}. When | |
7906 | @code{search-forward} finds the string, the function leaves point | |
7907 | immediately after the last character in the target string. (In this | |
7908 | case the target string is just one character long.) If the search is | |
7909 | backwards, @code{search-forward} leaves point just before the first | |
7910 | character in the target. The movement of point is a side effect. | |
7911 | ||
7912 | The second and last argument to @code{progn} is the expression | |
7913 | @code{(point)}. This expression returns the value of point, which in | |
7914 | this case will be the location to which it has been moved by | |
7915 | @code{search-forward}. (In the source, a line that tells the function | |
7916 | to go to the previous character, if it is going forward, was commented | |
7917 | out in 1999; I don't remember whether that feature or mis-feature was | |
7918 | ever a part of the distributed source.) The value of @code{point} is | |
7919 | returned by the @code{progn} expression and is passed to | |
7920 | @code{kill-region} as @code{kill-region}'s second argument. | |
7921 | ||
d6adf7e7 | 7922 | @node Summing up zap-to-char |
8cda6f8f GM |
7923 | @subsection Summing up @code{zap-to-char} |
7924 | ||
7925 | Now that we have seen how @code{search-forward} and @code{progn} work, | |
7926 | we can see how the @code{zap-to-char} function works as a whole. | |
7927 | ||
7928 | The first argument to @code{kill-region} is the position of the cursor | |
7929 | when the @code{zap-to-char} command is given---the value of point at | |
7930 | that time. Within the @code{progn}, the search function then moves | |
7931 | point to just after the zapped-to-character and @code{point} returns the | |
7932 | value of this location. The @code{kill-region} function puts together | |
7933 | these two values of point, the first one as the beginning of the region | |
7934 | and the second one as the end of the region, and removes the region. | |
7935 | ||
7936 | The @code{progn} special form is necessary because the | |
7937 | @code{kill-region} command takes two arguments; and it would fail if | |
7938 | @code{search-forward} and @code{point} expressions were written in | |
7939 | sequence as two additional arguments. The @code{progn} expression is | |
7940 | a single argument to @code{kill-region} and returns the one value that | |
7941 | @code{kill-region} needs for its second argument. | |
7942 | ||
d6adf7e7 | 7943 | @node kill-region |
8cda6f8f GM |
7944 | @section @code{kill-region} |
7945 | @findex kill-region | |
7946 | ||
7947 | The @code{zap-to-char} function uses the @code{kill-region} function. | |
7948 | This function clips text from a region and copies that text to | |
7949 | the kill ring, from which it may be retrieved. | |
7950 | ||
7951 | @ignore | |
7952 | GNU Emacs 22: | |
7953 | ||
7954 | (defun kill-region (beg end &optional yank-handler) | |
7955 | "Kill (\"cut\") text between point and mark. | |
7956 | This deletes the text from the buffer and saves it in the kill ring. | |
7957 | The command \\[yank] can retrieve it from there. | |
7958 | \(If you want to kill and then yank immediately, use \\[kill-ring-save].) | |
7959 | ||
7960 | If you want to append the killed region to the last killed text, | |
7961 | use \\[append-next-kill] before \\[kill-region]. | |
7962 | ||
7963 | If the buffer is read-only, Emacs will beep and refrain from deleting | |
7964 | the text, but put the text in the kill ring anyway. This means that | |
7965 | you can use the killing commands to copy text from a read-only buffer. | |
7966 | ||
7967 | This is the primitive for programs to kill text (as opposed to deleting it). | |
7968 | Supply two arguments, character positions indicating the stretch of text | |
7969 | to be killed. | |
7970 | Any command that calls this function is a \"kill command\". | |
7971 | If the previous command was also a kill command, | |
7972 | the text killed this time appends to the text killed last time | |
7973 | to make one entry in the kill ring. | |
7974 | ||
7975 | In Lisp code, optional third arg YANK-HANDLER, if non-nil, | |
7976 | specifies the yank-handler text property to be set on the killed | |
7977 | text. See `insert-for-yank'." | |
7978 | ;; Pass point first, then mark, because the order matters | |
7979 | ;; when calling kill-append. | |
7980 | (interactive (list (point) (mark))) | |
7981 | (unless (and beg end) | |
7982 | (error "The mark is not set now, so there is no region")) | |
7983 | (condition-case nil | |
7984 | (let ((string (filter-buffer-substring beg end t))) | |
7985 | (when string ;STRING is nil if BEG = END | |
7986 | ;; Add that string to the kill ring, one way or another. | |
7987 | (if (eq last-command 'kill-region) | |
7988 | (kill-append string (< end beg) yank-handler) | |
7989 | (kill-new string nil yank-handler))) | |
7990 | (when (or string (eq last-command 'kill-region)) | |
7991 | (setq this-command 'kill-region)) | |
7992 | nil) | |
7993 | ((buffer-read-only text-read-only) | |
7994 | ;; The code above failed because the buffer, or some of the characters | |
7995 | ;; in the region, are read-only. | |
7996 | ;; We should beep, in case the user just isn't aware of this. | |
7997 | ;; However, there's no harm in putting | |
7998 | ;; the region's text in the kill ring, anyway. | |
7999 | (copy-region-as-kill beg end) | |
8000 | ;; Set this-command now, so it will be set even if we get an error. | |
8001 | (setq this-command 'kill-region) | |
8002 | ;; This should barf, if appropriate, and give us the correct error. | |
8003 | (if kill-read-only-ok | |
8004 | (progn (message "Read only text copied to kill ring") nil) | |
8005 | ;; Signal an error if the buffer is read-only. | |
8006 | (barf-if-buffer-read-only) | |
8007 | ;; If the buffer isn't read-only, the text is. | |
8008 | (signal 'text-read-only (list (current-buffer))))))) | |
8009 | @end ignore | |
8010 | ||
8011 | The Emacs 22 version of that function uses @code{condition-case} and | |
8012 | @code{copy-region-as-kill}, both of which we will explain. | |
8013 | @code{condition-case} is an important special form. | |
8014 | ||
8015 | In essence, the @code{kill-region} function calls | |
8016 | @code{condition-case}, which takes three arguments. In this function, | |
8017 | the first argument does nothing. The second argument contains the | |
8018 | code that does the work when all goes well. The third argument | |
8019 | contains the code that is called in the event of an error. | |
8020 | ||
8021 | @menu | |
8022 | * Complete kill-region:: The function definition. | |
8023 | * condition-case:: Dealing with a problem. | |
8024 | * Lisp macro:: | |
8025 | @end menu | |
8026 | ||
8cda6f8f | 8027 | @ifnottex |
d6adf7e7 | 8028 | @node Complete kill-region |
8cda6f8f GM |
8029 | @unnumberedsubsec The Complete @code{kill-region} Definition |
8030 | @end ifnottex | |
8031 | ||
8032 | @need 1200 | |
8033 | We will go through the @code{condition-case} code in a moment. First, | |
8034 | let us look at the definition of @code{kill-region}, with comments | |
8035 | added: | |
8036 | ||
8037 | @c GNU Emacs 22: | |
8038 | @smallexample | |
8039 | @group | |
8040 | (defun kill-region (beg end) | |
8041 | "Kill (\"cut\") text between point and mark. | |
8042 | This deletes the text from the buffer and saves it in the kill ring. | |
8043 | The command \\[yank] can retrieve it from there. @dots{} " | |
8044 | @end group | |
8045 | ||
8046 | @group | |
8047 | ;; @bullet{} Since order matters, pass point first. | |
8048 | (interactive (list (point) (mark))) | |
8049 | ;; @bullet{} And tell us if we cannot cut the text. | |
8050 | ;; `unless' is an `if' without a then-part. | |
8051 | (unless (and beg end) | |
8052 | (error "The mark is not set now, so there is no region")) | |
8053 | @end group | |
8054 | ||
8055 | @group | |
8056 | ;; @bullet{} `condition-case' takes three arguments. | |
8057 | ;; If the first argument is nil, as it is here, | |
8058 | ;; information about the error signal is not | |
8059 | ;; stored for use by another function. | |
8060 | (condition-case nil | |
8061 | @end group | |
8062 | ||
8063 | @group | |
8064 | ;; @bullet{} The second argument to `condition-case' tells the | |
8065 | ;; Lisp interpreter what to do when all goes well. | |
8066 | @end group | |
8067 | ||
8068 | @group | |
8069 | ;; It starts with a `let' function that extracts the string | |
8070 | ;; and tests whether it exists. If so (that is what the | |
8071 | ;; `when' checks), it calls an `if' function that determines | |
8072 | ;; whether the previous command was another call to | |
8073 | ;; `kill-region'; if it was, then the new text is appended to | |
8074 | ;; the previous text; if not, then a different function, | |
8075 | ;; `kill-new', is called. | |
8076 | @end group | |
8077 | ||
8078 | @group | |
8079 | ;; The `kill-append' function concatenates the new string and | |
8080 | ;; the old. The `kill-new' function inserts text into a new | |
8081 | ;; item in the kill ring. | |
8082 | @end group | |
8083 | ||
8084 | @group | |
8085 | ;; `when' is an `if' without an else-part. The second `when' | |
8086 | ;; again checks whether the current string exists; in | |
8087 | ;; addition, it checks whether the previous command was | |
8088 | ;; another call to `kill-region'. If one or the other | |
8089 | ;; condition is true, then it sets the current command to | |
8090 | ;; be `kill-region'. | |
8091 | @end group | |
8092 | @group | |
8093 | (let ((string (filter-buffer-substring beg end t))) | |
8094 | (when string ;STRING is nil if BEG = END | |
8095 | ;; Add that string to the kill ring, one way or another. | |
8096 | (if (eq last-command 'kill-region) | |
8097 | @end group | |
8098 | @group | |
8099 | ;; @minus{} `yank-handler' is an optional argument to | |
8100 | ;; `kill-region' that tells the `kill-append' and | |
8101 | ;; `kill-new' functions how deal with properties | |
8102 | ;; added to the text, such as `bold' or `italics'. | |
8103 | (kill-append string (< end beg) yank-handler) | |
8104 | (kill-new string nil yank-handler))) | |
8105 | (when (or string (eq last-command 'kill-region)) | |
8106 | (setq this-command 'kill-region)) | |
8107 | nil) | |
8108 | @end group | |
8109 | ||
8110 | @group | |
8111 | ;; @bullet{} The third argument to `condition-case' tells the interpreter | |
8112 | ;; what to do with an error. | |
8113 | @end group | |
8114 | @group | |
8115 | ;; The third argument has a conditions part and a body part. | |
8116 | ;; If the conditions are met (in this case, | |
8117 | ;; if text or buffer are read-only) | |
8118 | ;; then the body is executed. | |
8119 | @end group | |
8120 | @group | |
8121 | ;; The first part of the third argument is the following: | |
8122 | ((buffer-read-only text-read-only) ;; the if-part | |
8123 | ;; @dots{} the then-part | |
8124 | (copy-region-as-kill beg end) | |
8125 | @end group | |
8126 | @group | |
8127 | ;; Next, also as part of the then-part, set this-command, so | |
8128 | ;; it will be set in an error | |
8129 | (setq this-command 'kill-region) | |
8130 | ;; Finally, in the then-part, send a message if you may copy | |
8350f087 | 8131 | ;; the text to the kill ring without signaling an error, but |
8cda6f8f GM |
8132 | ;; don't if you may not. |
8133 | @end group | |
8134 | @group | |
8135 | (if kill-read-only-ok | |
8136 | (progn (message "Read only text copied to kill ring") nil) | |
8137 | (barf-if-buffer-read-only) | |
8138 | ;; If the buffer isn't read-only, the text is. | |
8139 | (signal 'text-read-only (list (current-buffer))))) | |
8140 | @end group | |
8141 | @end smallexample | |
8142 | ||
8143 | @ignore | |
8144 | @c v 21 | |
8145 | @smallexample | |
8146 | @group | |
8147 | (defun kill-region (beg end) | |
8148 | "Kill between point and mark. | |
8149 | The text is deleted but saved in the kill ring." | |
8150 | (interactive "r") | |
8151 | @end group | |
8152 | ||
8153 | @group | |
8154 | ;; 1. `condition-case' takes three arguments. | |
8155 | ;; If the first argument is nil, as it is here, | |
8156 | ;; information about the error signal is not | |
8157 | ;; stored for use by another function. | |
8158 | (condition-case nil | |
8159 | @end group | |
8160 | ||
8161 | @group | |
8162 | ;; 2. The second argument to `condition-case' | |
8163 | ;; tells the Lisp interpreter what to do when all goes well. | |
8164 | @end group | |
8165 | ||
8166 | @group | |
8167 | ;; The `delete-and-extract-region' function usually does the | |
8168 | ;; work. If the beginning and ending of the region are both | |
8169 | ;; the same, then the variable `string' will be empty, or nil | |
8170 | (let ((string (delete-and-extract-region beg end))) | |
8171 | @end group | |
8172 | ||
8173 | @group | |
8174 | ;; `when' is an `if' clause that cannot take an `else-part'. | |
8175 | ;; Emacs normally sets the value of `last-command' to the | |
8176 | ;; previous command. | |
8177 | @end group | |
8178 | @group | |
8179 | ;; `kill-append' concatenates the new string and the old. | |
8180 | ;; `kill-new' inserts text into a new item in the kill ring. | |
8181 | (when string | |
8182 | (if (eq last-command 'kill-region) | |
8183 | ;; if true, prepend string | |
8184 | (kill-append string (< end beg)) | |
8185 | (kill-new string))) | |
8186 | (setq this-command 'kill-region)) | |
8187 | @end group | |
8188 | ||
8189 | @group | |
8190 | ;; 3. The third argument to `condition-case' tells the interpreter | |
8191 | ;; what to do with an error. | |
8192 | @end group | |
8193 | @group | |
8194 | ;; The third argument has a conditions part and a body part. | |
8195 | ;; If the conditions are met (in this case, | |
8196 | ;; if text or buffer are read-only) | |
8197 | ;; then the body is executed. | |
8198 | @end group | |
8199 | @group | |
8200 | ((buffer-read-only text-read-only) ;; this is the if-part | |
8201 | ;; then... | |
8202 | (copy-region-as-kill beg end) | |
8203 | @end group | |
8204 | @group | |
8205 | (if kill-read-only-ok ;; usually this variable is nil | |
8206 | (message "Read only text copied to kill ring") | |
8207 | ;; or else, signal an error if the buffer is read-only; | |
8208 | (barf-if-buffer-read-only) | |
8209 | ;; and, in any case, signal that the text is read-only. | |
8210 | (signal 'text-read-only (list (current-buffer))))))) | |
8211 | @end group | |
8212 | @end smallexample | |
8213 | @end ignore | |
8214 | ||
d6adf7e7 | 8215 | @node condition-case |
8cda6f8f GM |
8216 | @subsection @code{condition-case} |
8217 | @findex condition-case | |
8218 | ||
8219 | As we have seen earlier (@pxref{Making Errors, , Generate an Error | |
8220 | Message}), when the Emacs Lisp interpreter has trouble evaluating an | |
8221 | expression, it provides you with help; in the jargon, this is called | |
8222 | ``signaling an error''. Usually, the computer stops the program and | |
8223 | shows you a message. | |
8224 | ||
8225 | However, some programs undertake complicated actions. They should not | |
8226 | simply stop on an error. In the @code{kill-region} function, the most | |
8227 | likely error is that you will try to kill text that is read-only and | |
8228 | cannot be removed. So the @code{kill-region} function contains code | |
8229 | to handle this circumstance. This code, which makes up the body of | |
8230 | the @code{kill-region} function, is inside of a @code{condition-case} | |
8231 | special form. | |
8232 | ||
8233 | @need 800 | |
8234 | The template for @code{condition-case} looks like this: | |
8235 | ||
8236 | @smallexample | |
8237 | @group | |
8238 | (condition-case | |
8239 | @var{var} | |
8240 | @var{bodyform} | |
8241 | @var{error-handler}@dots{}) | |
8242 | @end group | |
8243 | @end smallexample | |
8244 | ||
8245 | The second argument, @var{bodyform}, is straightforward. The | |
8246 | @code{condition-case} special form causes the Lisp interpreter to | |
8247 | evaluate the code in @var{bodyform}. If no error occurs, the special | |
8248 | form returns the code's value and produces the side-effects, if any. | |
8249 | ||
8250 | In short, the @var{bodyform} part of a @code{condition-case} | |
8251 | expression determines what should happen when everything works | |
8252 | correctly. | |
8253 | ||
8254 | However, if an error occurs, among its other actions, the function | |
8255 | generating the error signal will define one or more error condition | |
8256 | names. | |
8257 | ||
8258 | An error handler is the third argument to @code{condition case}. | |
8259 | An error handler has two parts, a @var{condition-name} and a | |
8260 | @var{body}. If the @var{condition-name} part of an error handler | |
8261 | matches a condition name generated by an error, then the @var{body} | |
8262 | part of the error handler is run. | |
8263 | ||
8264 | As you will expect, the @var{condition-name} part of an error handler | |
8265 | may be either a single condition name or a list of condition names. | |
8266 | ||
8267 | Also, a complete @code{condition-case} expression may contain more | |
8268 | than one error handler. When an error occurs, the first applicable | |
8269 | handler is run. | |
8270 | ||
8271 | Lastly, the first argument to the @code{condition-case} expression, | |
8272 | the @var{var} argument, is sometimes bound to a variable that | |
8273 | contains information about the error. However, if that argument is | |
8274 | nil, as is the case in @code{kill-region}, that information is | |
8275 | discarded. | |
8276 | ||
8277 | @need 1200 | |
8278 | In brief, in the @code{kill-region} function, the code | |
8279 | @code{condition-case} works like this: | |
8280 | ||
8281 | @smallexample | |
8282 | @group | |
8283 | @var{If no errors}, @var{run only this code} | |
8284 | @var{but}, @var{if errors}, @var{run this other code}. | |
8285 | @end group | |
8286 | @end smallexample | |
8287 | ||
8288 | @ignore | |
8289 | 2006 Oct 24 | |
8290 | In Emacs 22, | |
8291 | copy-region-as-kill is short, 12 lines, and uses | |
8292 | filter-buffer-substring, which is longer, 39 lines | |
8293 | and has delete-and-extract-region in it. | |
8294 | delete-and-extract-region is written in C. | |
8295 | ||
8296 | see Initializing a Variable with @code{defvar} | |
8297 | this is line 8054 | |
8298 | Initializing a Variable with @code{defvar} includes line 8350 | |
8299 | @end ignore | |
8300 | ||
d6adf7e7 | 8301 | @node Lisp macro |
8cda6f8f GM |
8302 | @subsection Lisp macro |
8303 | @cindex Macro, lisp | |
8304 | @cindex Lisp macro | |
8305 | ||
8306 | The part of the @code{condition-case} expression that is evaluated in | |
8307 | the expectation that all goes well has a @code{when}. The code uses | |
8308 | @code{when} to determine whether the @code{string} variable points to | |
8309 | text that exists. | |
8310 | ||
8311 | A @code{when} expression is simply a programmers' convenience. It is | |
8312 | an @code{if} without the possibility of an else clause. In your mind, | |
8313 | you can replace @code{when} with @code{if} and understand what goes | |
8314 | on. That is what the Lisp interpreter does. | |
8315 | ||
8316 | Technically speaking, @code{when} is a Lisp macro. A Lisp @dfn{macro} | |
8317 | enables you to define new control constructs and other language | |
8318 | features. It tells the interpreter how to compute another Lisp | |
8319 | expression which will in turn compute the value. In this case, the | |
8320 | `other expression' is an @code{if} expression. | |
8321 | ||
8322 | The @code{kill-region} function definition also has an @code{unless} | |
8323 | macro; it is the converse of @code{when}. The @code{unless} macro is | |
8324 | an @code{if} without a then clause | |
8325 | ||
8326 | For more about Lisp macros, see @ref{Macros, , Macros, elisp, The GNU | |
8327 | Emacs Lisp Reference Manual}. The C programming language also | |
8328 | provides macros. These are different, but also useful. | |
8329 | ||
8330 | @ignore | |
8331 | We will briefly look at C macros in | |
8332 | @ref{Digression into C}. | |
8333 | @end ignore | |
8334 | ||
8335 | @need 1200 | |
8336 | Regarding the @code{when} macro, in the @code{condition-case} | |
8337 | expression, when the string has content, then another conditional | |
8338 | expression is executed. This is an @code{if} with both a then-part | |
8339 | and an else-part. | |
8340 | ||
8341 | @smallexample | |
8342 | @group | |
8343 | (if (eq last-command 'kill-region) | |
8344 | (kill-append string (< end beg) yank-handler) | |
8345 | (kill-new string nil yank-handler)) | |
8346 | @end group | |
8347 | @end smallexample | |
8348 | ||
8349 | The then-part is evaluated if the previous command was another call to | |
8350 | @code{kill-region}; if not, the else-part is evaluated. | |
8351 | ||
8352 | @code{yank-handler} is an optional argument to @code{kill-region} that | |
8353 | tells the @code{kill-append} and @code{kill-new} functions how deal | |
8354 | with properties added to the text, such as `bold' or `italics'. | |
8355 | ||
8356 | @code{last-command} is a variable that comes with Emacs that we have | |
8357 | not seen before. Normally, whenever a function is executed, Emacs | |
8358 | sets the value of @code{last-command} to the previous command. | |
8359 | ||
8360 | @need 1200 | |
8361 | In this segment of the definition, the @code{if} expression checks | |
8362 | whether the previous command was @code{kill-region}. If it was, | |
8363 | ||
8364 | @smallexample | |
8365 | (kill-append string (< end beg) yank-handler) | |
8366 | @end smallexample | |
8367 | ||
8368 | @noindent | |
8369 | concatenates a copy of the newly clipped text to the just previously | |
8370 | clipped text in the kill ring. | |
8371 | ||
d6adf7e7 | 8372 | @node copy-region-as-kill |
8cda6f8f GM |
8373 | @section @code{copy-region-as-kill} |
8374 | @findex copy-region-as-kill | |
8375 | @findex nthcdr | |
8376 | ||
8377 | The @code{copy-region-as-kill} function copies a region of text from a | |
8378 | buffer and (via either @code{kill-append} or @code{kill-new}) saves it | |
8379 | in the @code{kill-ring}. | |
8380 | ||
8381 | If you call @code{copy-region-as-kill} immediately after a | |
8382 | @code{kill-region} command, Emacs appends the newly copied text to the | |
8383 | previously copied text. This means that if you yank back the text, you | |
8384 | get it all, from both this and the previous operation. On the other | |
8385 | hand, if some other command precedes the @code{copy-region-as-kill}, | |
8386 | the function copies the text into a separate entry in the kill ring. | |
8387 | ||
8388 | @menu | |
8389 | * Complete copy-region-as-kill:: The complete function definition. | |
8390 | * copy-region-as-kill body:: The body of @code{copy-region-as-kill}. | |
8391 | @end menu | |
8392 | ||
8cda6f8f | 8393 | @ifnottex |
d6adf7e7 | 8394 | @node Complete copy-region-as-kill |
8cda6f8f GM |
8395 | @unnumberedsubsec The complete @code{copy-region-as-kill} function definition |
8396 | @end ifnottex | |
8397 | ||
8398 | @need 1200 | |
8399 | Here is the complete text of the version 22 @code{copy-region-as-kill} | |
8400 | function: | |
8401 | ||
8402 | @smallexample | |
8403 | @group | |
8404 | (defun copy-region-as-kill (beg end) | |
8405 | "Save the region as if killed, but don't kill it. | |
8406 | In Transient Mark mode, deactivate the mark. | |
8407 | If `interprogram-cut-function' is non-nil, also save the text for a window | |
8408 | system cut and paste." | |
8409 | (interactive "r") | |
8410 | @end group | |
8411 | @group | |
8412 | (if (eq last-command 'kill-region) | |
8413 | (kill-append (filter-buffer-substring beg end) (< end beg)) | |
8414 | (kill-new (filter-buffer-substring beg end))) | |
8415 | @end group | |
8416 | @group | |
8417 | (if transient-mark-mode | |
8418 | (setq deactivate-mark t)) | |
8419 | nil) | |
8420 | @end group | |
8421 | @end smallexample | |
8422 | ||
8423 | @need 800 | |
8424 | As usual, this function can be divided into its component parts: | |
8425 | ||
8426 | @smallexample | |
8427 | @group | |
8428 | (defun copy-region-as-kill (@var{argument-list}) | |
8429 | "@var{documentation}@dots{}" | |
8430 | (interactive "r") | |
8431 | @var{body}@dots{}) | |
8432 | @end group | |
8433 | @end smallexample | |
8434 | ||
8435 | The arguments are @code{beg} and @code{end} and the function is | |
8436 | interactive with @code{"r"}, so the two arguments must refer to the | |
8437 | beginning and end of the region. If you have been reading though this | |
8438 | document from the beginning, understanding these parts of a function is | |
8439 | almost becoming routine. | |
8440 | ||
8441 | The documentation is somewhat confusing unless you remember that the | |
8442 | word `kill' has a meaning different from usual. The `Transient Mark' | |
8443 | and @code{interprogram-cut-function} comments explain certain | |
8444 | side-effects. | |
8445 | ||
8446 | After you once set a mark, a buffer always contains a region. If you | |
8447 | wish, you can use Transient Mark mode to highlight the region | |
8448 | temporarily. (No one wants to highlight the region all the time, so | |
8449 | Transient Mark mode highlights it only at appropriate times. Many | |
8450 | people turn off Transient Mark mode, so the region is never | |
8451 | highlighted.) | |
8452 | ||
8453 | Also, a windowing system allows you to copy, cut, and paste among | |
8454 | different programs. In the X windowing system, for example, the | |
8455 | @code{interprogram-cut-function} function is @code{x-select-text}, | |
8456 | which works with the windowing system's equivalent of the Emacs kill | |
8457 | ring. | |
8458 | ||
8459 | The body of the @code{copy-region-as-kill} function starts with an | |
8460 | @code{if} clause. What this clause does is distinguish between two | |
8461 | different situations: whether or not this command is executed | |
8462 | immediately after a previous @code{kill-region} command. In the first | |
8463 | case, the new region is appended to the previously copied text. | |
8464 | Otherwise, it is inserted into the beginning of the kill ring as a | |
8465 | separate piece of text from the previous piece. | |
8466 | ||
8467 | The last two lines of the function prevent the region from lighting up | |
8468 | if Transient Mark mode is turned on. | |
8469 | ||
8470 | The body of @code{copy-region-as-kill} merits discussion in detail. | |
8471 | ||
d6adf7e7 | 8472 | @node copy-region-as-kill body |
8cda6f8f GM |
8473 | @subsection The Body of @code{copy-region-as-kill} |
8474 | ||
8475 | The @code{copy-region-as-kill} function works in much the same way as | |
8476 | the @code{kill-region} function. Both are written so that two or more | |
8477 | kills in a row combine their text into a single entry. If you yank | |
8478 | back the text from the kill ring, you get it all in one piece. | |
8479 | Moreover, kills that kill forward from the current position of the | |
8480 | cursor are added to the end of the previously copied text and commands | |
8481 | that copy text backwards add it to the beginning of the previously | |
8482 | copied text. This way, the words in the text stay in the proper | |
8483 | order. | |
8484 | ||
8485 | Like @code{kill-region}, the @code{copy-region-as-kill} function makes | |
8486 | use of the @code{last-command} variable that keeps track of the | |
8487 | previous Emacs command. | |
8488 | ||
8489 | @menu | |
8490 | * last-command & this-command:: | |
8491 | * kill-append function:: | |
8492 | * kill-new function:: | |
8493 | @end menu | |
8494 | ||
8cda6f8f | 8495 | @ifnottex |
d6adf7e7 | 8496 | @node last-command & this-command |
8cda6f8f GM |
8497 | @unnumberedsubsubsec @code{last-command} and @code{this-command} |
8498 | @end ifnottex | |
8499 | ||
8500 | Normally, whenever a function is executed, Emacs sets the value of | |
8501 | @code{this-command} to the function being executed (which in this case | |
8502 | would be @code{copy-region-as-kill}). At the same time, Emacs sets | |
8503 | the value of @code{last-command} to the previous value of | |
8504 | @code{this-command}. | |
8505 | ||
8506 | In the first part of the body of the @code{copy-region-as-kill} | |
8507 | function, an @code{if} expression determines whether the value of | |
8508 | @code{last-command} is @code{kill-region}. If so, the then-part of | |
8509 | the @code{if} expression is evaluated; it uses the @code{kill-append} | |
8510 | function to concatenate the text copied at this call to the function | |
8511 | with the text already in the first element (the @sc{car}) of the kill | |
8512 | ring. On the other hand, if the value of @code{last-command} is not | |
8513 | @code{kill-region}, then the @code{copy-region-as-kill} function | |
8514 | attaches a new element to the kill ring using the @code{kill-new} | |
8515 | function. | |
8516 | ||
8517 | @need 1250 | |
8518 | The @code{if} expression reads as follows; it uses @code{eq}: | |
8519 | ||
8520 | @smallexample | |
8521 | @group | |
8522 | (if (eq last-command 'kill-region) | |
8523 | ;; @r{then-part} | |
8524 | (kill-append (filter-buffer-substring beg end) (< end beg)) | |
8525 | ;; @r{else-part} | |
8526 | (kill-new (filter-buffer-substring beg end))) | |
8527 | @end group | |
8528 | @end smallexample | |
8529 | ||
8530 | @findex filter-buffer-substring | |
8531 | (The @code{filter-buffer-substring} function returns a filtered | |
8532 | substring of the buffer, if any. Optionally---the arguments are not | |
8533 | here, so neither is done---the function may delete the initial text or | |
8534 | return the text without its properties; this function is a replacement | |
8535 | for the older @code{buffer-substring} function, which came before text | |
8536 | properties were implemented.) | |
8537 | ||
8538 | @findex eq @r{(example of use)} | |
8539 | @noindent | |
8540 | The @code{eq} function tests whether its first argument is the same Lisp | |
8541 | object as its second argument. The @code{eq} function is similar to the | |
8542 | @code{equal} function in that it is used to test for equality, but | |
8543 | differs in that it determines whether two representations are actually | |
8544 | the same object inside the computer, but with different names. | |
8545 | @code{equal} determines whether the structure and contents of two | |
8546 | expressions are the same. | |
8547 | ||
8548 | If the previous command was @code{kill-region}, then the Emacs Lisp | |
8549 | interpreter calls the @code{kill-append} function | |
8550 | ||
d6adf7e7 | 8551 | @node kill-append function |
8cda6f8f GM |
8552 | @unnumberedsubsubsec The @code{kill-append} function |
8553 | @findex kill-append | |
8554 | ||
8555 | @need 800 | |
8556 | The @code{kill-append} function looks like this: | |
8557 | ||
8558 | @c in GNU Emacs 22 | |
8559 | @smallexample | |
8560 | @group | |
8561 | (defun kill-append (string before-p &optional yank-handler) | |
8562 | "Append STRING to the end of the latest kill in the kill ring. | |
8563 | If BEFORE-P is non-nil, prepend STRING to the kill. | |
8564 | @dots{} " | |
8565 | (let* ((cur (car kill-ring))) | |
8566 | (kill-new (if before-p (concat string cur) (concat cur string)) | |
8567 | (or (= (length cur) 0) | |
8568 | (equal yank-handler | |
8569 | (get-text-property 0 'yank-handler cur))) | |
8570 | yank-handler))) | |
8571 | @end group | |
8572 | @end smallexample | |
8573 | ||
8574 | @ignore | |
8575 | was: | |
8576 | (defun kill-append (string before-p) | |
8577 | "Append STRING to the end of the latest kill in the kill ring. | |
8578 | If BEFORE-P is non-nil, prepend STRING to the kill. | |
8579 | If `interprogram-cut-function' is set, pass the resulting kill to | |
8580 | it." | |
8581 | (kill-new (if before-p | |
8582 | (concat string (car kill-ring)) | |
8583 | (concat (car kill-ring) string)) | |
8584 | t)) | |
8585 | @end ignore | |
8586 | ||
8587 | @noindent | |
8588 | The @code{kill-append} function is fairly straightforward. It uses | |
8589 | the @code{kill-new} function, which we will discuss in more detail in | |
8590 | a moment. | |
8591 | ||
8592 | (Also, the function provides an optional argument called | |
8593 | @code{yank-handler}; when invoked, this argument tells the function | |
8594 | how to deal with properties added to the text, such as `bold' or | |
8595 | `italics'.) | |
8596 | ||
8597 | @c !!! bug in GNU Emacs 22 version of kill-append ? | |
8598 | It has a @code{let*} function to set the value of the first element of | |
8599 | the kill ring to @code{cur}. (I do not know why the function does not | |
8600 | use @code{let} instead; only one value is set in the expression. | |
8601 | Perhaps this is a bug that produces no problems?) | |
8602 | ||
8603 | Consider the conditional that is one of the two arguments to | |
8604 | @code{kill-new}. It uses @code{concat} to concatenate the new text to | |
8605 | the @sc{car} of the kill ring. Whether it prepends or appends the | |
8606 | text depends on the results of an @code{if} expression: | |
8607 | ||
8608 | @smallexample | |
8609 | @group | |
8610 | (if before-p ; @r{if-part} | |
8611 | (concat string cur) ; @r{then-part} | |
8612 | (concat cur string)) ; @r{else-part} | |
8613 | @end group | |
8614 | @end smallexample | |
8615 | ||
8616 | @noindent | |
8617 | If the region being killed is before the region that was killed in the | |
8618 | last command, then it should be prepended before the material that was | |
8619 | saved in the previous kill; and conversely, if the killed text follows | |
8620 | what was just killed, it should be appended after the previous text. | |
8621 | The @code{if} expression depends on the predicate @code{before-p} to | |
8622 | decide whether the newly saved text should be put before or after the | |
8623 | previously saved text. | |
8624 | ||
8625 | The symbol @code{before-p} is the name of one of the arguments to | |
8626 | @code{kill-append}. When the @code{kill-append} function is | |
8627 | evaluated, it is bound to the value returned by evaluating the actual | |
8628 | argument. In this case, this is the expression @code{(< end beg)}. | |
8629 | This expression does not directly determine whether the killed text in | |
8630 | this command is located before or after the kill text of the last | |
8631 | command; what it does is determine whether the value of the variable | |
8632 | @code{end} is less than the value of the variable @code{beg}. If it | |
8633 | is, it means that the user is most likely heading towards the | |
8634 | beginning of the buffer. Also, the result of evaluating the predicate | |
8635 | expression, @code{(< end beg)}, will be true and the text will be | |
8636 | prepended before the previous text. On the other hand, if the value of | |
8637 | the variable @code{end} is greater than the value of the variable | |
8638 | @code{beg}, the text will be appended after the previous text. | |
8639 | ||
8640 | @need 800 | |
8641 | When the newly saved text will be prepended, then the string with the new | |
8642 | text will be concatenated before the old text: | |
8643 | ||
8644 | @smallexample | |
8645 | (concat string cur) | |
8646 | @end smallexample | |
8647 | ||
8648 | @need 1200 | |
8649 | @noindent | |
8650 | But if the text will be appended, it will be concatenated | |
8651 | after the old text: | |
8652 | ||
8653 | @smallexample | |
8654 | (concat cur string)) | |
8655 | @end smallexample | |
8656 | ||
8657 | To understand how this works, we first need to review the | |
8658 | @code{concat} function. The @code{concat} function links together or | |
8659 | unites two strings of text. The result is a string. For example: | |
8660 | ||
8661 | @smallexample | |
8662 | @group | |
8663 | (concat "abc" "def") | |
8664 | @result{} "abcdef" | |
8665 | @end group | |
8666 | ||
8667 | @group | |
8668 | (concat "new " | |
8669 | (car '("first element" "second element"))) | |
8670 | @result{} "new first element" | |
8671 | ||
8672 | (concat (car | |
8673 | '("first element" "second element")) " modified") | |
8674 | @result{} "first element modified" | |
8675 | @end group | |
8676 | @end smallexample | |
8677 | ||
8678 | We can now make sense of @code{kill-append}: it modifies the contents | |
8679 | of the kill ring. The kill ring is a list, each element of which is | |
8680 | saved text. The @code{kill-append} function uses the @code{kill-new} | |
8681 | function which in turn uses the @code{setcar} function. | |
8682 | ||
d6adf7e7 | 8683 | @node kill-new function |
8cda6f8f GM |
8684 | @unnumberedsubsubsec The @code{kill-new} function |
8685 | @findex kill-new | |
8686 | ||
8687 | @c in GNU Emacs 22, additional documentation to kill-new: | |
8688 | @ignore | |
8689 | Optional third arguments YANK-HANDLER controls how the STRING is later | |
8690 | inserted into a buffer; see `insert-for-yank' for details. | |
8691 | When a yank handler is specified, STRING must be non-empty (the yank | |
8692 | handler, if non-nil, is stored as a `yank-handler' text property on STRING). | |
8693 | ||
8694 | When the yank handler has a non-nil PARAM element, the original STRING | |
8695 | argument is not used by `insert-for-yank'. However, since Lisp code | |
8696 | may access and use elements from the kill ring directly, the STRING | |
8697 | argument should still be a \"useful\" string for such uses." | |
8698 | @end ignore | |
8699 | @need 1200 | |
8700 | The @code{kill-new} function looks like this: | |
8701 | ||
8702 | @smallexample | |
8703 | @group | |
8704 | (defun kill-new (string &optional replace yank-handler) | |
8705 | "Make STRING the latest kill in the kill ring. | |
8706 | Set `kill-ring-yank-pointer' to point to it. | |
8707 | ||
8708 | If `interprogram-cut-function' is non-nil, apply it to STRING. | |
8709 | Optional second argument REPLACE non-nil means that STRING will replace | |
8710 | the front of the kill ring, rather than being added to the list. | |
8711 | @dots{}" | |
8712 | @end group | |
8713 | @group | |
8714 | (if (> (length string) 0) | |
8715 | (if yank-handler | |
8716 | (put-text-property 0 (length string) | |
8717 | 'yank-handler yank-handler string)) | |
8718 | (if yank-handler | |
8719 | (signal 'args-out-of-range | |
8720 | (list string "yank-handler specified for empty string")))) | |
8721 | @end group | |
8722 | @group | |
8723 | (if (fboundp 'menu-bar-update-yank-menu) | |
8724 | (menu-bar-update-yank-menu string (and replace (car kill-ring)))) | |
8725 | @end group | |
8726 | @group | |
8727 | (if (and replace kill-ring) | |
8728 | (setcar kill-ring string) | |
8729 | (push string kill-ring) | |
8730 | (if (> (length kill-ring) kill-ring-max) | |
8731 | (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) | |
8732 | @end group | |
8733 | @group | |
8734 | (setq kill-ring-yank-pointer kill-ring) | |
8735 | (if interprogram-cut-function | |
8736 | (funcall interprogram-cut-function string (not replace)))) | |
8737 | @end group | |
8738 | @end smallexample | |
8739 | @ignore | |
8740 | was: | |
8741 | (defun kill-new (string &optional replace) | |
8742 | "Make STRING the latest kill in the kill ring. | |
8743 | Set the kill-ring-yank pointer to point to it. | |
8744 | If `interprogram-cut-function' is non-nil, apply it to STRING. | |
8745 | Optional second argument REPLACE non-nil means that STRING will replace | |
8746 | the front of the kill ring, rather than being added to the list." | |
8747 | (and (fboundp 'menu-bar-update-yank-menu) | |
8748 | (menu-bar-update-yank-menu string (and replace (car kill-ring)))) | |
8749 | (if (and replace kill-ring) | |
8750 | (setcar kill-ring string) | |
8751 | (setq kill-ring (cons string kill-ring)) | |
8752 | (if (> (length kill-ring) kill-ring-max) | |
8753 | (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) | |
8754 | (setq kill-ring-yank-pointer kill-ring) | |
8755 | (if interprogram-cut-function | |
8756 | (funcall interprogram-cut-function string (not replace)))) | |
8757 | @end ignore | |
8758 | ||
8759 | (Notice that the function is not interactive.) | |
8760 | ||
8761 | As usual, we can look at this function in parts. | |
8762 | ||
8763 | The function definition has an optional @code{yank-handler} argument, | |
8764 | which when invoked tells the function how to deal with properties | |
8765 | added to the text, such as `bold' or `italics'. We will skip that. | |
8766 | ||
8767 | @need 1200 | |
8768 | The first line of the documentation makes sense: | |
8769 | ||
8770 | @smallexample | |
8771 | Make STRING the latest kill in the kill ring. | |
8772 | @end smallexample | |
8773 | ||
8774 | @noindent | |
8775 | Let's skip over the rest of the documentation for the moment. | |
8776 | ||
8777 | @noindent | |
8778 | Also, let's skip over the initial @code{if} expression and those lines | |
8779 | of code involving @code{menu-bar-update-yank-menu}. We will explain | |
8780 | them below. | |
8781 | ||
8782 | @need 1200 | |
8783 | The critical lines are these: | |
8784 | ||
8785 | @smallexample | |
8786 | @group | |
8787 | (if (and replace kill-ring) | |
8788 | ;; @r{then} | |
8789 | (setcar kill-ring string) | |
8790 | @end group | |
8791 | @group | |
8792 | ;; @r{else} | |
8793 | (push string kill-ring) | |
8794 | @end group | |
8795 | @group | |
8796 | (setq kill-ring (cons string kill-ring)) | |
8797 | (if (> (length kill-ring) kill-ring-max) | |
8798 | ;; @r{avoid overly long kill ring} | |
8799 | (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) | |
8800 | @end group | |
8801 | @group | |
8802 | (setq kill-ring-yank-pointer kill-ring) | |
8803 | (if interprogram-cut-function | |
8804 | (funcall interprogram-cut-function string (not replace)))) | |
8805 | @end group | |
8806 | @end smallexample | |
8807 | ||
8808 | The conditional test is @w{@code{(and replace kill-ring)}}. | |
8809 | This will be true when two conditions are met: the kill ring has | |
8810 | something in it, and the @code{replace} variable is true. | |
8811 | ||
8812 | @need 1250 | |
8813 | When the @code{kill-append} function sets @code{replace} to be true | |
8814 | and when the kill ring has at least one item in it, the @code{setcar} | |
8815 | expression is executed: | |
8816 | ||
8817 | @smallexample | |
8818 | (setcar kill-ring string) | |
8819 | @end smallexample | |
8820 | ||
8821 | The @code{setcar} function actually changes the first element of the | |
8822 | @code{kill-ring} list to the value of @code{string}. It replaces the | |
8823 | first element. | |
8824 | ||
8825 | @need 1250 | |
8826 | On the other hand, if the kill ring is empty, or replace is false, the | |
8827 | else-part of the condition is executed: | |
8828 | ||
8829 | @smallexample | |
8830 | (push string kill-ring) | |
8831 | @end smallexample | |
8832 | ||
8833 | @noindent | |
8834 | @need 1250 | |
8835 | @code{push} puts its first argument onto the second. It is similar to | |
8836 | the older | |
8837 | ||
8838 | @smallexample | |
8839 | (setq kill-ring (cons string kill-ring)) | |
8840 | @end smallexample | |
8841 | ||
8842 | @noindent | |
8843 | @need 1250 | |
8844 | or the newer | |
8845 | ||
8846 | @smallexample | |
8847 | (add-to-list kill-ring string) | |
8848 | @end smallexample | |
8849 | ||
8850 | @noindent | |
8851 | When it is false, the expression first constructs a new version of the | |
8852 | kill ring by prepending @code{string} to the existing kill ring as a | |
8853 | new element (that is what the @code{push} does). Then it executes a | |
8854 | second @code{if} clause. This second @code{if} clause keeps the kill | |
8855 | ring from growing too long. | |
8856 | ||
8857 | Let's look at these two expressions in order. | |
8858 | ||
8859 | The @code{push} line of the else-part sets the new value of the kill | |
8860 | ring to what results from adding the string being killed to the old | |
8861 | kill ring. | |
8862 | ||
8863 | We can see how this works with an example. | |
8864 | ||
8865 | @need 800 | |
8866 | First, | |
8867 | ||
8868 | @smallexample | |
8869 | (setq example-list '("here is a clause" "another clause")) | |
8870 | @end smallexample | |
8871 | ||
8872 | @need 1200 | |
8873 | @noindent | |
8874 | After evaluating this expression with @kbd{C-x C-e}, you can evaluate | |
8875 | @code{example-list} and see what it returns: | |
8876 | ||
8877 | @smallexample | |
8878 | @group | |
8879 | example-list | |
8880 | @result{} ("here is a clause" "another clause") | |
8881 | @end group | |
8882 | @end smallexample | |
8883 | ||
8884 | @need 1200 | |
8885 | @noindent | |
8886 | Now, we can add a new element on to this list by evaluating the | |
8887 | following expression: | |
8888 | @findex push, @r{example} | |
8889 | ||
8890 | @smallexample | |
8891 | (push "a third clause" example-list) | |
8892 | @end smallexample | |
8893 | ||
8894 | @need 800 | |
8895 | @noindent | |
8896 | When we evaluate @code{example-list}, we find its value is: | |
8897 | ||
8898 | @smallexample | |
8899 | @group | |
8900 | example-list | |
8901 | @result{} ("a third clause" "here is a clause" "another clause") | |
8902 | @end group | |
8903 | @end smallexample | |
8904 | ||
8905 | @noindent | |
8906 | Thus, the third clause is added to the list by @code{push}. | |
8907 | ||
8908 | @need 1200 | |
8909 | Now for the second part of the @code{if} clause. This expression | |
8910 | keeps the kill ring from growing too long. It looks like this: | |
8911 | ||
8912 | @smallexample | |
8913 | @group | |
8914 | (if (> (length kill-ring) kill-ring-max) | |
8915 | (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)) | |
8916 | @end group | |
8917 | @end smallexample | |
8918 | ||
8919 | The code checks whether the length of the kill ring is greater than | |
8920 | the maximum permitted length. This is the value of | |
8921 | @code{kill-ring-max} (which is 60, by default). If the length of the | |
8922 | kill ring is too long, then this code sets the last element of the | |
8923 | kill ring to @code{nil}. It does this by using two functions, | |
8924 | @code{nthcdr} and @code{setcdr}. | |
8925 | ||
8926 | We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}). | |
8927 | It sets the @sc{cdr} of a list, just as @code{setcar} sets the | |
8928 | @sc{car} of a list. In this case, however, @code{setcdr} will not be | |
8929 | setting the @sc{cdr} of the whole kill ring; the @code{nthcdr} | |
8930 | function is used to cause it to set the @sc{cdr} of the next to last | |
8931 | element of the kill ring---this means that since the @sc{cdr} of the | |
8932 | next to last element is the last element of the kill ring, it will set | |
8933 | the last element of the kill ring. | |
8934 | ||
8935 | @findex nthcdr, @r{example} | |
8936 | The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a | |
8937 | list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr} | |
8938 | @dots{} It does this @var{N} times and returns the results. | |
8939 | (@xref{nthcdr, , @code{nthcdr}}.) | |
8940 | ||
8941 | @findex setcdr, @r{example} | |
8942 | Thus, if we had a four element list that was supposed to be three | |
8943 | elements long, we could set the @sc{cdr} of the next to last element | |
8944 | to @code{nil}, and thereby shorten the list. (If you set the last | |
8945 | element to some other value than @code{nil}, which you could do, then | |
8946 | you would not have shortened the list. @xref{setcdr, , | |
8947 | @code{setcdr}}.) | |
8948 | ||
8949 | You can see shortening by evaluating the following three expressions | |
8950 | in turn. First set the value of @code{trees} to @code{(maple oak pine | |
8951 | birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil} | |
8952 | and then find the value of @code{trees}: | |
8953 | ||
8954 | @smallexample | |
8955 | @group | |
8956 | (setq trees '(maple oak pine birch)) | |
8957 | @result{} (maple oak pine birch) | |
8958 | @end group | |
8959 | ||
8960 | @group | |
8961 | (setcdr (nthcdr 2 trees) nil) | |
8962 | @result{} nil | |
8963 | ||
8964 | trees | |
8965 | @result{} (maple oak pine) | |
8966 | @end group | |
8967 | @end smallexample | |
8968 | ||
8969 | @noindent | |
8970 | (The value returned by the @code{setcdr} expression is @code{nil} since | |
8971 | that is what the @sc{cdr} is set to.) | |
8972 | ||
8973 | To repeat, in @code{kill-new}, the @code{nthcdr} function takes the | |
8974 | @sc{cdr} a number of times that is one less than the maximum permitted | |
8975 | size of the kill ring and @code{setcdr} sets the @sc{cdr} of that | |
8976 | element (which will be the rest of the elements in the kill ring) to | |
8977 | @code{nil}. This prevents the kill ring from growing too long. | |
8978 | ||
8979 | @need 800 | |
8980 | The next to last expression in the @code{kill-new} function is | |
8981 | ||
8982 | @smallexample | |
8983 | (setq kill-ring-yank-pointer kill-ring) | |
8984 | @end smallexample | |
8985 | ||
8986 | The @code{kill-ring-yank-pointer} is a global variable that is set to be | |
8987 | the @code{kill-ring}. | |
8988 | ||
8989 | Even though the @code{kill-ring-yank-pointer} is called a | |
8990 | @samp{pointer}, it is a variable just like the kill ring. However, the | |
8991 | name has been chosen to help humans understand how the variable is used. | |
8992 | ||
8993 | @need 1200 | |
8994 | Now, to return to an early expression in the body of the function: | |
8995 | ||
8996 | @smallexample | |
8997 | @group | |
8998 | (if (fboundp 'menu-bar-update-yank-menu) | |
8999 | (menu-bar-update-yank-menu string (and replace (car kill-ring)))) | |
9000 | @end group | |
9001 | @end smallexample | |
9002 | ||
9003 | @noindent | |
9004 | It starts with an @code{if} expression | |
9005 | ||
9006 | In this case, the expression tests first to see whether | |
9007 | @code{menu-bar-update-yank-menu} exists as a function, and if so, | |
9008 | calls it. The @code{fboundp} function returns true if the symbol it | |
9009 | is testing has a function definition that `is not void'. If the | |
9010 | symbol's function definition were void, we would receive an error | |
9011 | message, as we did when we created errors intentionally (@pxref{Making | |
9012 | Errors, , Generate an Error Message}). | |
9013 | ||
9014 | @noindent | |
9015 | The then-part contains an expression whose first element is the | |
9016 | function @code{and}. | |
9017 | ||
9018 | @findex and | |
9019 | The @code{and} special form evaluates each of its arguments until one | |
9020 | of the arguments returns a value of @code{nil}, in which case the | |
9021 | @code{and} expression returns @code{nil}; however, if none of the | |
9022 | arguments returns a value of @code{nil}, the value resulting from | |
9023 | evaluating the last argument is returned. (Since such a value is not | |
9024 | @code{nil}, it is considered true in Emacs Lisp.) In other words, an | |
9025 | @code{and} expression returns a true value only if all its arguments | |
9026 | are true. (@xref{Second Buffer Related Review}.) | |
9027 | ||
9028 | The expression determines whether the second argument to | |
9029 | @code{menu-bar-update-yank-menu} is true or not. | |
9030 | @ignore | |
9031 | ;; If we're supposed to be extending an existing string, and that | |
9032 | ;; string really is at the front of the menu, then update it in place. | |
9033 | @end ignore | |
9034 | ||
9035 | @code{menu-bar-update-yank-menu} is one of the functions that make it | |
9036 | possible to use the `Select and Paste' menu in the Edit item of a menu | |
9037 | bar; using a mouse, you can look at the various pieces of text you | |
9038 | have saved and select one piece to paste. | |
9039 | ||
9040 | The last expression in the @code{kill-new} function adds the newly | |
9041 | copied string to whatever facility exists for copying and pasting | |
9042 | among different programs running in a windowing system. In the X | |
9043 | Windowing system, for example, the @code{x-select-text} function takes | |
1df7defd | 9044 | the string and stores it in memory operated by X@. You can paste the |
8cda6f8f GM |
9045 | string in another program, such as an Xterm. |
9046 | ||
9047 | @need 1200 | |
9048 | The expression looks like this: | |
9049 | ||
9050 | @smallexample | |
9051 | @group | |
9052 | (if interprogram-cut-function | |
9053 | (funcall interprogram-cut-function string (not replace)))) | |
9054 | @end group | |
9055 | @end smallexample | |
9056 | ||
9057 | If an @code{interprogram-cut-function} exists, then Emacs executes | |
9058 | @code{funcall}, which in turn calls its first argument as a function | |
9059 | and passes the remaining arguments to it. (Incidentally, as far as I | |
9060 | can see, this @code{if} expression could be replaced by an @code{and} | |
9061 | expression similar to the one in the first part of the function.) | |
9062 | ||
9063 | We are not going to discuss windowing systems and other programs | |
9064 | further, but merely note that this is a mechanism that enables GNU | |
9065 | Emacs to work easily and well with other programs. | |
9066 | ||
9067 | This code for placing text in the kill ring, either concatenated with | |
9068 | an existing element or as a new element, leads us to the code for | |
9069 | bringing back text that has been cut out of the buffer---the yank | |
9070 | commands. However, before discussing the yank commands, it is better | |
9071 | to learn how lists are implemented in a computer. This will make | |
9072 | clear such mysteries as the use of the term `pointer'. But before | |
9073 | that, we will digress into C. | |
9074 | ||
9075 | @ignore | |
9076 | @c is this true in Emacs 22? Does not seems to be | |
9077 | ||
9078 | (If the @w{@code{(< end beg))}} | |
9079 | expression is true, @code{kill-append} prepends the string to the just | |
9080 | previously clipped text. For a detailed discussion, see | |
9081 | @ref{kill-append function, , The @code{kill-append} function}.) | |
9082 | ||
9083 | If you then yank back the text, i.e., `paste' it, you get both | |
9084 | pieces of text at once. That way, if you delete two words in a row, | |
9085 | and then yank them back, you get both words, in their proper order, | |
9086 | with one yank. (The @w{@code{(< end beg))}} expression makes sure the | |
9087 | order is correct.) | |
9088 | ||
9089 | On the other hand, if the previous command is not @code{kill-region}, | |
9090 | then the @code{kill-new} function is called, which adds the text to | |
9091 | the kill ring as the latest item, and sets the | |
9092 | @code{kill-ring-yank-pointer} variable to point to it. | |
9093 | @end ignore | |
9094 | @ignore | |
9095 | ||
9096 | @c Evidently, changed for Emacs 22. The zap-to-char command does not | |
9097 | @c use the delete-and-extract-region function | |
9098 | ||
9099 | 2006 Oct 26, the Digression into C is now OK but should come after | |
9100 | copy-region-as-kill and filter-buffer-substring | |
9101 | ||
9102 | 2006 Oct 24 | |
9103 | In Emacs 22, | |
9104 | copy-region-as-kill is short, 12 lines, and uses | |
9105 | filter-buffer-substring, which is longer, 39 lines | |
9106 | and has delete-and-extract-region in it. | |
9107 | delete-and-extract-region is written in C. | |
9108 | ||
9109 | see Initializing a Variable with @code{defvar} | |
9110 | @end ignore | |
9111 | ||
d6adf7e7 | 9112 | @node Digression into C |
8cda6f8f GM |
9113 | @section Digression into C |
9114 | @findex delete-and-extract-region | |
9115 | @cindex C, a digression into | |
9116 | @cindex Digression into C | |
9117 | ||
9118 | The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, , | |
9119 | @code{copy-region-as-kill}}) uses the @code{filter-buffer-substring} | |
9120 | function, which in turn uses the @code{delete-and-extract-region} | |
9121 | function. It removes the contents of a region and you cannot get them | |
9122 | back. | |
9123 | ||
9124 | Unlike the other code discussed here, the | |
9125 | @code{delete-and-extract-region} function is not written in Emacs | |
9126 | Lisp; it is written in C and is one of the primitives of the GNU Emacs | |
9127 | system. Since it is very simple, I will digress briefly from Lisp and | |
9128 | describe it here. | |
9129 | ||
2d7d2325 GM |
9130 | @c GNU Emacs 24 in src/editfns.c |
9131 | @c the DEFUN for delete-and-extract-region | |
8cda6f8f GM |
9132 | |
9133 | @need 1500 | |
9134 | Like many of the other Emacs primitives, | |
9135 | @code{delete-and-extract-region} is written as an instance of a C | |
9136 | macro, a macro being a template for code. The complete macro looks | |
9137 | like this: | |
9138 | ||
9139 | @smallexample | |
9140 | @group | |
2d7d2325 GM |
9141 | DEFUN ("delete-and-extract-region", Fdelete_and_extract_region, |
9142 | Sdelete_and_extract_region, 2, 2, 0, | |
9143 | doc: /* Delete the text between START and END and return it. */) | |
9144 | (Lisp_Object start, Lisp_Object end) | |
8cda6f8f | 9145 | @{ |
8cda6f8f | 9146 | validate_region (&start, &end); |
2d7d2325 GM |
9147 | if (XINT (start) == XINT (end)) |
9148 | return empty_unibyte_string; | |
9149 | return del_range_1 (XINT (start), XINT (end), 1, 1); | |
8cda6f8f GM |
9150 | @} |
9151 | @end group | |
9152 | @end smallexample | |
9153 | ||
9154 | Without going into the details of the macro writing process, let me | |
9155 | point out that this macro starts with the word @code{DEFUN}. The word | |
9156 | @code{DEFUN} was chosen since the code serves the same purpose as | |
9157 | @code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in | |
9158 | @file{emacs/src/lisp.h}.) | |
9159 | ||
9160 | The word @code{DEFUN} is followed by seven parts inside of | |
9161 | parentheses: | |
9162 | ||
9163 | @itemize @bullet | |
9164 | @item | |
9165 | The first part is the name given to the function in Lisp, | |
9166 | @code{delete-and-extract-region}. | |
9167 | ||
9168 | @item | |
9169 | The second part is the name of the function in C, | |
9170 | @code{Fdelete_and_extract_region}. By convention, it starts with | |
9171 | @samp{F}. Since C does not use hyphens in names, underscores are used | |
9172 | instead. | |
9173 | ||
9174 | @item | |
9175 | The third part is the name for the C constant structure that records | |
9176 | information on this function for internal use. It is the name of the | |
9177 | function in C but begins with an @samp{S} instead of an @samp{F}. | |
9178 | ||
9179 | @item | |
9180 | The fourth and fifth parts specify the minimum and maximum number of | |
9181 | arguments the function can have. This function demands exactly 2 | |
9182 | arguments. | |
9183 | ||
9184 | @item | |
9185 | The sixth part is nearly like the argument that follows the | |
9186 | @code{interactive} declaration in a function written in Lisp: a letter | |
9187 | followed, perhaps, by a prompt. The only difference from the Lisp is | |
9188 | when the macro is called with no arguments. Then you write a @code{0} | |
9189 | (which is a `null string'), as in this macro. | |
9190 | ||
9191 | If you were to specify arguments, you would place them between | |
9192 | quotation marks. The C macro for @code{goto-char} includes | |
9193 | @code{"NGoto char: "} in this position to indicate that the function | |
9194 | expects a raw prefix, in this case, a numerical location in a buffer, | |
9195 | and provides a prompt. | |
9196 | ||
9197 | @item | |
9198 | The seventh part is a documentation string, just like the one for a | |
2d7d2325 GM |
9199 | function written in Emacs Lisp. This is written as a C comment. (When |
9200 | you build Emacs, the program @command{lib-src/make-docfile} extracts | |
9201 | these comments and uses them to make the ``real'' documentation.) | |
8cda6f8f GM |
9202 | @end itemize |
9203 | ||
9204 | @need 1200 | |
9205 | In a C macro, the formal parameters come next, with a statement of | |
9206 | what kind of object they are, followed by what might be called the `body' | |
9207 | of the macro. For @code{delete-and-extract-region} the `body' | |
9208 | consists of the following four lines: | |
9209 | ||
9210 | @smallexample | |
9211 | @group | |
9212 | validate_region (&start, &end); | |
9213 | if (XINT (start) == XINT (end)) | |
2d7d2325 | 9214 | return empty_unibyte_string; |
8cda6f8f GM |
9215 | return del_range_1 (XINT (start), XINT (end), 1, 1); |
9216 | @end group | |
9217 | @end smallexample | |
9218 | ||
2d7d2325 | 9219 | The @code{validate_region} function checks whether the values |
8cda6f8f GM |
9220 | passed as the beginning and end of the region are the proper type and |
9221 | are within range. If the beginning and end positions are the same, | |
2d7d2325 | 9222 | then return an empty string. |
8cda6f8f GM |
9223 | |
9224 | The @code{del_range_1} function actually deletes the text. It is a | |
9225 | complex function we will not look into. It updates the buffer and | |
9226 | does other things. However, it is worth looking at the two arguments | |
9227 | passed to @code{del_range}. These are @w{@code{XINT (start)}} and | |
9228 | @w{@code{XINT (end)}}. | |
9229 | ||
9230 | As far as the C language is concerned, @code{start} and @code{end} are | |
9231 | two integers that mark the beginning and end of the region to be | |
9232 | deleted@footnote{More precisely, and requiring more expert knowledge | |
9233 | to understand, the two integers are of type `Lisp_Object', which can | |
9234 | also be a C union instead of an integer type.}. | |
9235 | ||
9236 | In early versions of Emacs, these two numbers were thirty-two bits | |
9237 | long, but the code is slowly being generalized to handle other | |
9238 | lengths. Three of the available bits are used to specify the type of | |
9239 | information; the remaining bits are used as `content'. | |
9240 | ||
9241 | @samp{XINT} is a C macro that extracts the relevant number from the | |
9242 | longer collection of bits; the three other bits are discarded. | |
9243 | ||
9244 | @need 800 | |
9245 | The command in @code{delete-and-extract-region} looks like this: | |
9246 | ||
9247 | @smallexample | |
9248 | del_range_1 (XINT (start), XINT (end), 1, 1); | |
9249 | @end smallexample | |
9250 | ||
9251 | @noindent | |
9252 | It deletes the region between the beginning position, @code{start}, | |
9253 | and the ending position, @code{end}. | |
9254 | ||
9255 | From the point of view of the person writing Lisp, Emacs is all very | |
9256 | simple; but hidden underneath is a great deal of complexity to make it | |
9257 | all work. | |
9258 | ||
d6adf7e7 | 9259 | @node defvar |
8cda6f8f GM |
9260 | @section Initializing a Variable with @code{defvar} |
9261 | @findex defvar | |
9262 | @cindex Initializing a variable | |
9263 | @cindex Variable initialization | |
9264 | ||
9265 | @ignore | |
9266 | 2006 Oct 24 | |
9267 | In Emacs 22, | |
9268 | copy-region-as-kill is short, 12 lines, and uses | |
9269 | filter-buffer-substring, which is longer, 39 lines | |
9270 | and has delete-and-extract-region in it. | |
9271 | delete-and-extract-region is written in C. | |
9272 | ||
9273 | see Initializing a Variable with @code{defvar} | |
9274 | ||
9275 | @end ignore | |
9276 | ||
9277 | The @code{copy-region-as-kill} function is written in Emacs Lisp. Two | |
9278 | functions within it, @code{kill-append} and @code{kill-new}, copy a | |
9279 | region in a buffer and save it in a variable called the | |
9280 | @code{kill-ring}. This section describes how the @code{kill-ring} | |
9281 | variable is created and initialized using the @code{defvar} special | |
9282 | form. | |
9283 | ||
9284 | (Again we note that the term @code{kill-ring} is a misnomer. The text | |
9285 | that is clipped out of the buffer can be brought back; it is not a ring | |
9286 | of corpses, but a ring of resurrectable text.) | |
9287 | ||
9288 | In Emacs Lisp, a variable such as the @code{kill-ring} is created and | |
9289 | given an initial value by using the @code{defvar} special form. The | |
9290 | name comes from ``define variable''. | |
9291 | ||
9292 | The @code{defvar} special form is similar to @code{setq} in that it sets | |
9293 | the value of a variable. It is unlike @code{setq} in two ways: first, | |
9294 | it only sets the value of the variable if the variable does not already | |
9295 | have a value. If the variable already has a value, @code{defvar} does | |
9296 | not override the existing value. Second, @code{defvar} has a | |
9297 | documentation string. | |
9298 | ||
2325c82f XF |
9299 | (There is a related macro, @code{defcustom}, designed for variables |
9300 | that people customize. It has more features than @code{defvar}. | |
9301 | (@xref{defcustom, , Setting Variables with @code{defcustom}}.) | |
9302 | ||
8cda6f8f GM |
9303 | @menu |
9304 | * See variable current value:: | |
9305 | * defvar and asterisk:: | |
9306 | @end menu | |
9307 | ||
8cda6f8f | 9308 | @ifnottex |
d6adf7e7 | 9309 | @node See variable current value |
8cda6f8f GM |
9310 | @unnumberedsubsec Seeing the Current Value of a Variable |
9311 | @end ifnottex | |
9312 | ||
9313 | You can see the current value of a variable, any variable, by using | |
9314 | the @code{describe-variable} function, which is usually invoked by | |
9315 | typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring} | |
9316 | (followed by @key{RET}) when prompted, you will see what is in your | |
9317 | current kill ring---this may be quite a lot! Conversely, if you have | |
9318 | been doing nothing this Emacs session except read this document, you | |
9319 | may have nothing in it. Also, you will see the documentation for | |
9320 | @code{kill-ring}: | |
9321 | ||
9322 | @smallexample | |
9323 | @group | |
9324 | Documentation: | |
9325 | List of killed text sequences. | |
9326 | Since the kill ring is supposed to interact nicely with cut-and-paste | |
9327 | facilities offered by window systems, use of this variable should | |
9328 | @end group | |
9329 | @group | |
9330 | interact nicely with `interprogram-cut-function' and | |
9331 | `interprogram-paste-function'. The functions `kill-new', | |
9332 | `kill-append', and `current-kill' are supposed to implement this | |
9333 | interaction; you may want to use them instead of manipulating the kill | |
9334 | ring directly. | |
9335 | @end group | |
9336 | @end smallexample | |
9337 | ||
9338 | @need 800 | |
9339 | The kill ring is defined by a @code{defvar} in the following way: | |
9340 | ||
9341 | @smallexample | |
9342 | @group | |
9343 | (defvar kill-ring nil | |
9344 | "List of killed text sequences. | |
9345 | @dots{}") | |
9346 | @end group | |
9347 | @end smallexample | |
9348 | ||
9349 | @noindent | |
9350 | In this variable definition, the variable is given an initial value of | |
9351 | @code{nil}, which makes sense, since if you have saved nothing, you want | |
9352 | nothing back if you give a @code{yank} command. The documentation | |
9353 | string is written just like the documentation string of a @code{defun}. | |
9354 | As with the documentation string of the @code{defun}, the first line of | |
9355 | the documentation should be a complete sentence, since some commands, | |
9356 | like @code{apropos}, print only the first line of documentation. | |
9357 | Succeeding lines should not be indented; otherwise they look odd when | |
9358 | you use @kbd{C-h v} (@code{describe-variable}). | |
9359 | ||
d6adf7e7 | 9360 | @node defvar and asterisk |
8cda6f8f GM |
9361 | @subsection @code{defvar} and an asterisk |
9362 | @findex defvar @r{for a user customizable variable} | |
9363 | @findex defvar @r{with an asterisk} | |
9364 | ||
9365 | In the past, Emacs used the @code{defvar} special form both for | |
9366 | internal variables that you would not expect a user to change and for | |
9367 | variables that you do expect a user to change. Although you can still | |
9368 | use @code{defvar} for user customizable variables, please use | |
9369 | @code{defcustom} instead, since that special form provides a path into | |
9370 | the Customization commands. (@xref{defcustom, , Specifying Variables | |
9371 | using @code{defcustom}}.) | |
9372 | ||
9373 | When you specified a variable using the @code{defvar} special form, | |
943157cf GM |
9374 | you could distinguish a variable that a user might want to change from |
9375 | others by typing an asterisk, @samp{*}, in the first column of its | |
9376 | documentation string. For example: | |
8cda6f8f GM |
9377 | |
9378 | @smallexample | |
9379 | @group | |
9380 | (defvar shell-command-default-error-buffer nil | |
9381 | "*Buffer name for `shell-command' @dots{} error output. | |
9382 | @dots{} ") | |
9383 | @end group | |
9384 | @end smallexample | |
9385 | ||
9386 | @findex set-variable | |
9387 | @noindent | |
9388 | You could (and still can) use the @code{set-variable} command to | |
9389 | change the value of @code{shell-command-default-error-buffer} | |
9390 | temporarily. However, options set using @code{set-variable} are set | |
9391 | only for the duration of your editing session. The new values are not | |
9392 | saved between sessions. Each time Emacs starts, it reads the original | |
9393 | value, unless you change the value within your @file{.emacs} file, | |
9394 | either by setting it manually or by using @code{customize}. | |
9395 | @xref{Emacs Initialization, , Your @file{.emacs} File}. | |
9396 | ||
9397 | For me, the major use of the @code{set-variable} command is to suggest | |
9398 | variables that I might want to set in my @file{.emacs} file. There | |
f99f1641 | 9399 | are now more than 700 such variables, far too many to remember |
8cda6f8f GM |
9400 | readily. Fortunately, you can press @key{TAB} after calling the |
9401 | @code{M-x set-variable} command to see the list of variables. | |
9402 | (@xref{Examining, , Examining and Setting Variables, emacs, | |
9403 | The GNU Emacs Manual}.) | |
9404 | ||
9405 | @need 1250 | |
d6adf7e7 | 9406 | @node cons & search-fwd Review |
8cda6f8f GM |
9407 | @section Review |
9408 | ||
9409 | Here is a brief summary of some recently introduced functions. | |
9410 | ||
9411 | @table @code | |
9412 | @item car | |
9413 | @itemx cdr | |
9414 | @code{car} returns the first element of a list; @code{cdr} returns the | |
9415 | second and subsequent elements of a list. | |
9416 | ||
9417 | @need 1250 | |
9418 | For example: | |
9419 | ||
9420 | @smallexample | |
9421 | @group | |
9422 | (car '(1 2 3 4 5 6 7)) | |
9423 | @result{} 1 | |
9424 | (cdr '(1 2 3 4 5 6 7)) | |
9425 | @result{} (2 3 4 5 6 7) | |
9426 | @end group | |
9427 | @end smallexample | |
9428 | ||
9429 | @item cons | |
9430 | @code{cons} constructs a list by prepending its first argument to its | |
9431 | second argument. | |
9432 | ||
9433 | @need 1250 | |
9434 | For example: | |
9435 | ||
9436 | @smallexample | |
9437 | @group | |
9438 | (cons 1 '(2 3 4)) | |
9439 | @result{} (1 2 3 4) | |
9440 | @end group | |
9441 | @end smallexample | |
9442 | ||
9443 | @item funcall | |
9444 | @code{funcall} evaluates its first argument as a function. It passes | |
9445 | its remaining arguments to its first argument. | |
9446 | ||
9447 | @item nthcdr | |
9448 | Return the result of taking @sc{cdr} `n' times on a list. | |
9449 | @iftex | |
9450 | The | |
9451 | @tex | |
9452 | $n^{th}$ | |
9453 | @end tex | |
9454 | @code{cdr}. | |
9455 | @end iftex | |
9456 | The `rest of the rest', as it were. | |
9457 | ||
9458 | @need 1250 | |
9459 | For example: | |
9460 | ||
9461 | @smallexample | |
9462 | @group | |
9463 | (nthcdr 3 '(1 2 3 4 5 6 7)) | |
9464 | @result{} (4 5 6 7) | |
9465 | @end group | |
9466 | @end smallexample | |
9467 | ||
9468 | @item setcar | |
9469 | @itemx setcdr | |
9470 | @code{setcar} changes the first element of a list; @code{setcdr} | |
9471 | changes the second and subsequent elements of a list. | |
9472 | ||
9473 | @need 1250 | |
9474 | For example: | |
9475 | ||
9476 | @smallexample | |
9477 | @group | |
9478 | (setq triple '(1 2 3)) | |
9479 | ||
9480 | (setcar triple '37) | |
9481 | ||
9482 | triple | |
9483 | @result{} (37 2 3) | |
9484 | ||
9485 | (setcdr triple '("foo" "bar")) | |
9486 | ||
9487 | triple | |
9488 | @result{} (37 "foo" "bar") | |
9489 | @end group | |
9490 | @end smallexample | |
9491 | ||
9492 | @item progn | |
9493 | Evaluate each argument in sequence and then return the value of the | |
9494 | last. | |
9495 | ||
9496 | @need 1250 | |
9497 | For example: | |
9498 | ||
9499 | @smallexample | |
9500 | @group | |
9501 | (progn 1 2 3 4) | |
9502 | @result{} 4 | |
9503 | @end group | |
9504 | @end smallexample | |
9505 | ||
9506 | @item save-restriction | |
9507 | Record whatever narrowing is in effect in the current buffer, if any, | |
9508 | and restore that narrowing after evaluating the arguments. | |
9509 | ||
9510 | @item search-forward | |
9511 | Search for a string, and if the string is found, move point. With a | |
9512 | regular expression, use the similar @code{re-search-forward}. | |
9513 | (@xref{Regexp Search, , Regular Expression Searches}, for an | |
9514 | explanation of regular expression patterns and searches.) | |
9515 | ||
9516 | @need 1250 | |
9517 | @noindent | |
9518 | @code{search-forward} and @code{re-search-forward} take four | |
9519 | arguments: | |
9520 | ||
9521 | @enumerate | |
9522 | @item | |
9523 | The string or regular expression to search for. | |
9524 | ||
9525 | @item | |
9526 | Optionally, the limit of the search. | |
9527 | ||
9528 | @item | |
9529 | Optionally, what to do if the search fails, return @code{nil} or an | |
9530 | error message. | |
9531 | ||
9532 | @item | |
9533 | Optionally, how many times to repeat the search; if negative, the | |
9534 | search goes backwards. | |
9535 | @end enumerate | |
9536 | ||
9537 | @item kill-region | |
9538 | @itemx delete-and-extract-region | |
9539 | @itemx copy-region-as-kill | |
9540 | ||
9541 | @code{kill-region} cuts the text between point and mark from the | |
9542 | buffer and stores that text in the kill ring, so you can get it back | |
9543 | by yanking. | |
9544 | ||
9545 | @code{copy-region-as-kill} copies the text between point and mark into | |
9546 | the kill ring, from which you can get it by yanking. The function | |
9547 | does not cut or remove the text from the buffer. | |
9548 | @end table | |
9549 | ||
9550 | @code{delete-and-extract-region} removes the text between point and | |
9551 | mark from the buffer and throws it away. You cannot get it back. | |
9552 | (This is not an interactive command.) | |
9553 | ||
9554 | @need 1500 | |
d6adf7e7 | 9555 | @node search Exercises |
8cda6f8f GM |
9556 | @section Searching Exercises |
9557 | ||
9558 | @itemize @bullet | |
9559 | @item | |
9560 | Write an interactive function that searches for a string. If the | |
9561 | search finds the string, leave point after it and display a message | |
9562 | that says ``Found!''. (Do not use @code{search-forward} for the name | |
9563 | of this function; if you do, you will overwrite the existing version of | |
9564 | @code{search-forward} that comes with Emacs. Use a name such as | |
9565 | @code{test-search} instead.) | |
9566 | ||
9567 | @item | |
9568 | Write a function that prints the third element of the kill ring in the | |
9569 | echo area, if any; if the kill ring does not contain a third element, | |
9570 | print an appropriate message. | |
9571 | @end itemize | |
9572 | ||
d6adf7e7 | 9573 | @node List Implementation |
8cda6f8f GM |
9574 | @chapter How Lists are Implemented |
9575 | @cindex Lists in a computer | |
9576 | ||
9577 | In Lisp, atoms are recorded in a straightforward fashion; if the | |
9578 | implementation is not straightforward in practice, it is, nonetheless, | |
9579 | straightforward in theory. The atom @samp{rose}, for example, is | |
9580 | recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s}, | |
9581 | @samp{e}. A list, on the other hand, is kept differently. The mechanism | |
9582 | is equally simple, but it takes a moment to get used to the idea. A | |
9583 | list is kept using a series of pairs of pointers. In the series, the | |
9584 | first pointer in each pair points to an atom or to another list, and the | |
9585 | second pointer in each pair points to the next pair, or to the symbol | |
9586 | @code{nil}, which marks the end of the list. | |
9587 | ||
9588 | A pointer itself is quite simply the electronic address of what is | |
9589 | pointed to. Hence, a list is kept as a series of electronic addresses. | |
9590 | ||
9591 | @menu | |
9592 | * Lists diagrammed:: | |
9593 | * Symbols as Chest:: Exploring a powerful metaphor. | |
9594 | * List Exercise:: | |
9595 | @end menu | |
9596 | ||
8cda6f8f | 9597 | @ifnottex |
d6adf7e7 | 9598 | @node Lists diagrammed |
8cda6f8f GM |
9599 | @unnumberedsec Lists diagrammed |
9600 | @end ifnottex | |
9601 | ||
9602 | For example, the list @code{(rose violet buttercup)} has three elements, | |
9603 | @samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the | |
9604 | electronic address of @samp{rose} is recorded in a segment of computer | |
9605 | memory along with the address that gives the electronic address of where | |
9606 | the atom @samp{violet} is located; and that address (the one that tells | |
9607 | where @samp{violet} is located) is kept along with an address that tells | |
9608 | where the address for the atom @samp{buttercup} is located. | |
9609 | ||
9610 | @need 1200 | |
9611 | This sounds more complicated than it is and is easier seen in a diagram: | |
9612 | ||
9613 | @c clear print-postscript-figures | |
9614 | @c !!! cons-cell-diagram #1 | |
9615 | @ifnottex | |
9616 | @smallexample | |
9617 | @group | |
9618 | ___ ___ ___ ___ ___ ___ | |
9619 | |___|___|--> |___|___|--> |___|___|--> nil | |
9620 | | | | | |
9621 | | | | | |
9622 | --> rose --> violet --> buttercup | |
9623 | @end group | |
9624 | @end smallexample | |
9625 | @end ifnottex | |
9626 | @ifset print-postscript-figures | |
9627 | @sp 1 | |
9628 | @tex | |
9629 | @center @image{cons-1} | |
9630 | %%%% old method of including an image | |
9631 | % \input /usr/local/lib/tex/inputs/psfig.tex | |
9632 | % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}} | |
9633 | % \catcode`\@=0 % | |
9634 | @end tex | |
9635 | @sp 1 | |
9636 | @end ifset | |
9637 | @ifclear print-postscript-figures | |
9638 | @iftex | |
9639 | @smallexample | |
9640 | @group | |
9641 | ___ ___ ___ ___ ___ ___ | |
9642 | |___|___|--> |___|___|--> |___|___|--> nil | |
9643 | | | | | |
9644 | | | | | |
9645 | --> rose --> violet --> buttercup | |
9646 | @end group | |
9647 | @end smallexample | |
9648 | @end iftex | |
9649 | @end ifclear | |
9650 | ||
9651 | @noindent | |
9652 | In the diagram, each box represents a word of computer memory that | |
9653 | holds a Lisp object, usually in the form of a memory address. The boxes, | |
1df7defd | 9654 | i.e., the addresses, are in pairs. Each arrow points to what the address |
8cda6f8f GM |
9655 | is the address of, either an atom or another pair of addresses. The |
9656 | first box is the electronic address of @samp{rose} and the arrow points | |
9657 | to @samp{rose}; the second box is the address of the next pair of boxes, | |
9658 | the first part of which is the address of @samp{violet} and the second | |
9659 | part of which is the address of the next pair. The very last box | |
9660 | points to the symbol @code{nil}, which marks the end of the list. | |
9661 | ||
9662 | @need 1200 | |
9663 | When a variable is set to a list with a function such as @code{setq}, | |
9664 | it stores the address of the first box in the variable. Thus, | |
9665 | evaluation of the expression | |
9666 | ||
9667 | @smallexample | |
9668 | (setq bouquet '(rose violet buttercup)) | |
9669 | @end smallexample | |
9670 | ||
9671 | @need 1250 | |
9672 | @noindent | |
9673 | creates a situation like this: | |
9674 | ||
9675 | @c cons-cell-diagram #2 | |
9676 | @ifnottex | |
9677 | @smallexample | |
9678 | @group | |
9679 | bouquet | |
9680 | | | |
9681 | | ___ ___ ___ ___ ___ ___ | |
9682 | --> |___|___|--> |___|___|--> |___|___|--> nil | |
9683 | | | | | |
9684 | | | | | |
9685 | --> rose --> violet --> buttercup | |
9686 | @end group | |
9687 | @end smallexample | |
9688 | @end ifnottex | |
9689 | @ifset print-postscript-figures | |
9690 | @sp 1 | |
9691 | @tex | |
9692 | @center @image{cons-2} | |
9693 | %%%% old method of including an image | |
9694 | % \input /usr/local/lib/tex/inputs/psfig.tex | |
9695 | % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}} | |
9696 | % \catcode`\@=0 % | |
9697 | @end tex | |
9698 | @sp 1 | |
9699 | @end ifset | |
9700 | @ifclear print-postscript-figures | |
9701 | @iftex | |
9702 | @smallexample | |
9703 | @group | |
9704 | bouquet | |
9705 | | | |
9706 | | ___ ___ ___ ___ ___ ___ | |
9707 | --> |___|___|--> |___|___|--> |___|___|--> nil | |
9708 | | | | | |
9709 | | | | | |
9710 | --> rose --> violet --> buttercup | |
9711 | @end group | |
9712 | @end smallexample | |
9713 | @end iftex | |
9714 | @end ifclear | |
9715 | ||
9716 | @noindent | |
9717 | In this example, the symbol @code{bouquet} holds the address of the first | |
9718 | pair of boxes. | |
9719 | ||
9720 | @need 1200 | |
9721 | This same list can be illustrated in a different sort of box notation | |
9722 | like this: | |
9723 | ||
9724 | @c cons-cell-diagram #2a | |
9725 | @ifnottex | |
9726 | @smallexample | |
9727 | @group | |
9728 | bouquet | |
9729 | | | |
9730 | | -------------- --------------- ---------------- | |
9731 | | | car | cdr | | car | cdr | | car | cdr | | |
9732 | -->| rose | o------->| violet | o------->| butter- | nil | | |
9733 | | | | | | | | cup | | | |
9734 | -------------- --------------- ---------------- | |
9735 | @end group | |
9736 | @end smallexample | |
9737 | @end ifnottex | |
9738 | @ifset print-postscript-figures | |
9739 | @sp 1 | |
9740 | @tex | |
9741 | @center @image{cons-2a} | |
9742 | %%%% old method of including an image | |
9743 | % \input /usr/local/lib/tex/inputs/psfig.tex | |
9744 | % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}} | |
9745 | % \catcode`\@=0 % | |
9746 | @end tex | |
9747 | @sp 1 | |
9748 | @end ifset | |
9749 | @ifclear print-postscript-figures | |
9750 | @iftex | |
9751 | @smallexample | |
9752 | @group | |
9753 | bouquet | |
9754 | | | |
9755 | | -------------- --------------- ---------------- | |
9756 | | | car | cdr | | car | cdr | | car | cdr | | |
9757 | -->| rose | o------->| violet | o------->| butter- | nil | | |
9758 | | | | | | | | cup | | | |
9759 | -------------- --------------- ---------------- | |
9760 | @end group | |
9761 | @end smallexample | |
9762 | @end iftex | |
9763 | @end ifclear | |
9764 | ||
9765 | (Symbols consist of more than pairs of addresses, but the structure of | |
9766 | a symbol is made up of addresses. Indeed, the symbol @code{bouquet} | |
9767 | consists of a group of address-boxes, one of which is the address of | |
9768 | the printed word @samp{bouquet}, a second of which is the address of a | |
9769 | function definition attached to the symbol, if any, a third of which | |
9770 | is the address of the first pair of address-boxes for the list | |
9771 | @code{(rose violet buttercup)}, and so on. Here we are showing that | |
9772 | the symbol's third address-box points to the first pair of | |
9773 | address-boxes for the list.) | |
9774 | ||
9775 | If a symbol is set to the @sc{cdr} of a list, the list itself is not | |
9776 | changed; the symbol simply has an address further down the list. (In | |
9777 | the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus, | |
9778 | evaluation of the following expression | |
9779 | ||
9780 | @smallexample | |
9781 | (setq flowers (cdr bouquet)) | |
9782 | @end smallexample | |
9783 | ||
9784 | @need 800 | |
9785 | @noindent | |
9786 | produces this: | |
9787 | ||
9788 | @c cons-cell-diagram #3 | |
9789 | @ifnottex | |
9790 | @sp 1 | |
9791 | @smallexample | |
9792 | @group | |
9793 | bouquet flowers | |
9794 | | | | |
9795 | | ___ ___ | ___ ___ ___ ___ | |
9796 | --> | | | --> | | | | | | | |
9797 | |___|___|----> |___|___|--> |___|___|--> nil | |
9798 | | | | | |
9799 | | | | | |
9800 | --> rose --> violet --> buttercup | |
9801 | @end group | |
9802 | @end smallexample | |
9803 | @sp 1 | |
9804 | @end ifnottex | |
9805 | @ifset print-postscript-figures | |
9806 | @sp 1 | |
9807 | @tex | |
9808 | @center @image{cons-3} | |
9809 | %%%% old method of including an image | |
9810 | % \input /usr/local/lib/tex/inputs/psfig.tex | |
9811 | % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}} | |
9812 | % \catcode`\@=0 % | |
9813 | @end tex | |
9814 | @sp 1 | |
9815 | @end ifset | |
9816 | @ifclear print-postscript-figures | |
9817 | @iftex | |
9818 | @sp 1 | |
9819 | @smallexample | |
9820 | @group | |
9821 | bouquet flowers | |
9822 | | | | |
9823 | | ___ ___ | ___ ___ ___ ___ | |
9824 | --> | | | --> | | | | | | | |
9825 | |___|___|----> |___|___|--> |___|___|--> nil | |
9826 | | | | | |
9827 | | | | | |
9828 | --> rose --> violet --> buttercup | |
9829 | @end group | |
9830 | @end smallexample | |
9831 | @sp 1 | |
9832 | @end iftex | |
9833 | @end ifclear | |
9834 | ||
9835 | @noindent | |
9836 | The value of @code{flowers} is @code{(violet buttercup)}, which is | |
9837 | to say, the symbol @code{flowers} holds the address of the pair of | |
9838 | address-boxes, the first of which holds the address of @code{violet}, | |
9839 | and the second of which holds the address of @code{buttercup}. | |
9840 | ||
9841 | A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted | |
9842 | pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp | |
9843 | Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair | |
9844 | Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more | |
9845 | information about cons cells and dotted pairs. | |
9846 | ||
9847 | @need 1200 | |
9848 | The function @code{cons} adds a new pair of addresses to the front of | |
9849 | a series of addresses like that shown above. For example, evaluating | |
9850 | the expression | |
9851 | ||
9852 | @smallexample | |
9853 | (setq bouquet (cons 'lily bouquet)) | |
9854 | @end smallexample | |
9855 | ||
9856 | @need 1500 | |
9857 | @noindent | |
9858 | produces: | |
9859 | ||
9860 | @c cons-cell-diagram #4 | |
9861 | @ifnottex | |
9862 | @sp 1 | |
9863 | @smallexample | |
9864 | @group | |
9865 | bouquet flowers | |
9866 | | | | |
9867 | | ___ ___ ___ ___ | ___ ___ ___ ___ | |
9868 | --> | | | | | | --> | | | | | | | |
9869 | |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil | |
9870 | | | | | | |
9871 | | | | | | |
9872 | --> lily --> rose --> violet --> buttercup | |
9873 | @end group | |
9874 | @end smallexample | |
9875 | @sp 1 | |
9876 | @end ifnottex | |
9877 | @ifset print-postscript-figures | |
9878 | @sp 1 | |
9879 | @tex | |
9880 | @center @image{cons-4} | |
9881 | %%%% old method of including an image | |
9882 | % \input /usr/local/lib/tex/inputs/psfig.tex | |
9883 | % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}} | |
9884 | % \catcode`\@=0 % | |
9885 | @end tex | |
9886 | @sp 1 | |
9887 | @end ifset | |
9888 | @ifclear print-postscript-figures | |
9889 | @iftex | |
9890 | @sp 1 | |
9891 | @smallexample | |
9892 | @group | |
9893 | bouquet flowers | |
9894 | | | | |
9895 | | ___ ___ ___ ___ | ___ ___ ___ ___ | |
9896 | --> | | | | | | --> | | | | | | | |
9897 | |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil | |
9898 | | | | | | |
9899 | | | | | | |
9900 | --> lily --> rose --> violet --> buttercup | |
9901 | @end group | |
9902 | @end smallexample | |
9903 | @sp 1 | |
9904 | @end iftex | |
9905 | @end ifclear | |
9906 | ||
9907 | @need 1200 | |
9908 | @noindent | |
9909 | However, this does not change the value of the symbol | |
9910 | @code{flowers}, as you can see by evaluating the following, | |
9911 | ||
9912 | @smallexample | |
9913 | (eq (cdr (cdr bouquet)) flowers) | |
9914 | @end smallexample | |
9915 | ||
9916 | @noindent | |
9917 | which returns @code{t} for true. | |
9918 | ||
9919 | Until it is reset, @code{flowers} still has the value | |
9920 | @code{(violet buttercup)}; that is, it has the address of the cons | |
9921 | cell whose first address is of @code{violet}. Also, this does not | |
9922 | alter any of the pre-existing cons cells; they are all still there. | |
9923 | ||
9924 | Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address | |
9925 | of the next cons cell in the series; to get the @sc{car} of a list, | |
9926 | you get the address of the first element of the list; to @code{cons} a | |
9927 | new element on a list, you add a new cons cell to the front of the list. | |
9928 | That is all there is to it! The underlying structure of Lisp is | |
9929 | brilliantly simple! | |
9930 | ||
9931 | And what does the last address in a series of cons cells refer to? It | |
9932 | is the address of the empty list, of @code{nil}. | |
9933 | ||
9934 | In summary, when a Lisp variable is set to a value, it is provided with | |
9935 | the address of the list to which the variable refers. | |
9936 | ||
d6adf7e7 | 9937 | @node Symbols as Chest |
8cda6f8f GM |
9938 | @section Symbols as a Chest of Drawers |
9939 | @cindex Symbols as a Chest of Drawers | |
9940 | @cindex Chest of Drawers, metaphor for a symbol | |
9941 | @cindex Drawers, Chest of, metaphor for a symbol | |
9942 | ||
9943 | In an earlier section, I suggested that you might imagine a symbol as | |
9944 | being a chest of drawers. The function definition is put in one | |
9945 | drawer, the value in another, and so on. What is put in the drawer | |
9946 | holding the value can be changed without affecting the contents of the | |
9947 | drawer holding the function definition, and vice-verse. | |
9948 | ||
9949 | Actually, what is put in each drawer is the address of the value or | |
9950 | function definition. It is as if you found an old chest in the attic, | |
9951 | and in one of its drawers you found a map giving you directions to | |
9952 | where the buried treasure lies. | |
9953 | ||
9954 | (In addition to its name, symbol definition, and variable value, a | |
9955 | symbol has a `drawer' for a @dfn{property list} which can be used to | |
9956 | record other information. Property lists are not discussed here; see | |
9957 | @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp | |
9958 | Reference Manual}.) | |
9959 | ||
9960 | @need 1500 | |
9961 | Here is a fanciful representation: | |
9962 | ||
9963 | @c chest-of-drawers diagram | |
9964 | @ifnottex | |
9965 | @sp 1 | |
9966 | @smallexample | |
9967 | @group | |
9968 | Chest of Drawers Contents of Drawers | |
9969 | ||
9970 | __ o0O0o __ | |
9971 | / \ | |
9972 | --------------------- | |
9973 | | directions to | [map to] | |
9974 | | symbol name | bouquet | |
9975 | | | | |
9976 | +---------------------+ | |
9977 | | directions to | | |
9978 | | symbol definition | [none] | |
9979 | | | | |
9980 | +---------------------+ | |
9981 | | directions to | [map to] | |
9982 | | variable value | (rose violet buttercup) | |
9983 | | | | |
9984 | +---------------------+ | |
9985 | | directions to | | |
9986 | | property list | [not described here] | |
9987 | | | | |
9988 | +---------------------+ | |
9989 | |/ \| | |
9990 | @end group | |
9991 | @end smallexample | |
9992 | @sp 1 | |
9993 | @end ifnottex | |
9994 | @ifset print-postscript-figures | |
9995 | @sp 1 | |
9996 | @tex | |
9997 | @center @image{drawers} | |
9998 | %%%% old method of including an image | |
9999 | % \input /usr/local/lib/tex/inputs/psfig.tex | |
10000 | % \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}} | |
10001 | % \catcode`\@=0 % | |
10002 | @end tex | |
10003 | @sp 1 | |
10004 | @end ifset | |
10005 | @ifclear print-postscript-figures | |
10006 | @iftex | |
10007 | @sp 1 | |
10008 | @smallexample | |
10009 | @group | |
10010 | Chest of Drawers Contents of Drawers | |
10011 | ||
10012 | __ o0O0o __ | |
10013 | / \ | |
10014 | --------------------- | |
10015 | | directions to | [map to] | |
10016 | | symbol name | bouquet | |
10017 | | | | |
10018 | +---------------------+ | |
10019 | | directions to | | |
10020 | | symbol definition | [none] | |
10021 | | | | |
10022 | +---------------------+ | |
10023 | | directions to | [map to] | |
10024 | | variable value | (rose violet buttercup) | |
10025 | | | | |
10026 | +---------------------+ | |
10027 | | directions to | | |
10028 | | property list | [not described here] | |
10029 | | | | |
10030 | +---------------------+ | |
10031 | |/ \| | |
10032 | @end group | |
10033 | @end smallexample | |
10034 | @sp 1 | |
10035 | @end iftex | |
10036 | @end ifclear | |
10037 | ||
d6adf7e7 | 10038 | @node List Exercise |
8cda6f8f GM |
10039 | @section Exercise |
10040 | ||
10041 | Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two | |
10042 | more flowers on to this list and set this new list to | |
10043 | @code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish. | |
10044 | What does the @code{more-flowers} list now contain? | |
10045 | ||
d6adf7e7 | 10046 | @node Yanking |
8cda6f8f GM |
10047 | @chapter Yanking Text Back |
10048 | @findex yank | |
10049 | @cindex Text retrieval | |
10050 | @cindex Retrieving text | |
10051 | @cindex Pasting text | |
10052 | ||
10053 | Whenever you cut text out of a buffer with a `kill' command in GNU Emacs, | |
10054 | you can bring it back with a `yank' command. The text that is cut out of | |
10055 | the buffer is put in the kill ring and the yank commands insert the | |
10056 | appropriate contents of the kill ring back into a buffer (not necessarily | |
10057 | the original buffer). | |
10058 | ||
10059 | A simple @kbd{C-y} (@code{yank}) command inserts the first item from | |
10060 | the kill ring into the current buffer. If the @kbd{C-y} command is | |
10061 | followed immediately by @kbd{M-y}, the first element is replaced by | |
10062 | the second element. Successive @kbd{M-y} commands replace the second | |
10063 | element with the third, fourth, or fifth element, and so on. When the | |
10064 | last element in the kill ring is reached, it is replaced by the first | |
10065 | element and the cycle is repeated. (Thus the kill ring is called a | |
10066 | `ring' rather than just a `list'. However, the actual data structure | |
10067 | that holds the text is a list. | |
10068 | @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the | |
10069 | list is handled as a ring.) | |
10070 | ||
10071 | @menu | |
10072 | * Kill Ring Overview:: | |
10073 | * kill-ring-yank-pointer:: The kill ring is a list. | |
10074 | * yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. | |
10075 | @end menu | |
10076 | ||
d6adf7e7 | 10077 | @node Kill Ring Overview |
8cda6f8f GM |
10078 | @section Kill Ring Overview |
10079 | @cindex Kill ring overview | |
10080 | ||
10081 | The kill ring is a list of textual strings. This is what it looks like: | |
10082 | ||
10083 | @smallexample | |
10084 | ("some text" "a different piece of text" "yet more text") | |
10085 | @end smallexample | |
10086 | ||
10087 | If this were the contents of my kill ring and I pressed @kbd{C-y}, the | |
10088 | string of characters saying @samp{some text} would be inserted in this | |
10089 | buffer where my cursor is located. | |
10090 | ||
10091 | The @code{yank} command is also used for duplicating text by copying it. | |
10092 | The copied text is not cut from the buffer, but a copy of it is put on the | |
10093 | kill ring and is inserted by yanking it back. | |
10094 | ||
10095 | Three functions are used for bringing text back from the kill ring: | |
10096 | @code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop}, | |
10097 | which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer}, | |
10098 | which is used by the two other functions. | |
10099 | ||
10100 | These functions refer to the kill ring through a variable called the | |
10101 | @code{kill-ring-yank-pointer}. Indeed, the insertion code for both the | |
10102 | @code{yank} and @code{yank-pop} functions is: | |
10103 | ||
10104 | @smallexample | |
10105 | (insert (car kill-ring-yank-pointer)) | |
10106 | @end smallexample | |
10107 | ||
10108 | @noindent | |
10109 | (Well, no more. In GNU Emacs 22, the function has been replaced by | |
10110 | @code{insert-for-yank} which calls @code{insert-for-yank-1} | |
10111 | repetitively for each @code{yank-handler} segment. In turn, | |
10112 | @code{insert-for-yank-1} strips text properties from the inserted text | |
10113 | according to @code{yank-excluded-properties}. Otherwise, it is just | |
10114 | like @code{insert}. We will stick with plain @code{insert} since it | |
10115 | is easier to understand.) | |
10116 | ||
10117 | To begin to understand how @code{yank} and @code{yank-pop} work, it is | |
10118 | first necessary to look at the @code{kill-ring-yank-pointer} variable. | |
10119 | ||
d6adf7e7 | 10120 | @node kill-ring-yank-pointer |
8cda6f8f GM |
10121 | @section The @code{kill-ring-yank-pointer} Variable |
10122 | ||
10123 | @code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is | |
10124 | a variable. It points to something by being bound to the value of what | |
10125 | it points to, like any other Lisp variable. | |
10126 | ||
10127 | @need 1000 | |
10128 | Thus, if the value of the kill ring is: | |
10129 | ||
10130 | @smallexample | |
10131 | ("some text" "a different piece of text" "yet more text") | |
10132 | @end smallexample | |
10133 | ||
10134 | @need 1250 | |
10135 | @noindent | |
10136 | and the @code{kill-ring-yank-pointer} points to the second clause, the | |
10137 | value of @code{kill-ring-yank-pointer} is: | |
10138 | ||
10139 | @smallexample | |
10140 | ("a different piece of text" "yet more text") | |
10141 | @end smallexample | |
10142 | ||
10143 | As explained in the previous chapter (@pxref{List Implementation}), the | |
10144 | computer does not keep two different copies of the text being pointed to | |
10145 | by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The | |
10146 | words ``a different piece of text'' and ``yet more text'' are not | |
10147 | duplicated. Instead, the two Lisp variables point to the same pieces of | |
10148 | text. Here is a diagram: | |
10149 | ||
10150 | @c cons-cell-diagram #5 | |
10151 | @ifnottex | |
10152 | @smallexample | |
10153 | @group | |
10154 | kill-ring kill-ring-yank-pointer | |
10155 | | | | |
10156 | | ___ ___ | ___ ___ ___ ___ | |
10157 | ---> | | | --> | | | | | | | |
10158 | |___|___|----> |___|___|--> |___|___|--> nil | |
10159 | | | | | |
10160 | | | | | |
10161 | | | --> "yet more text" | |
10162 | | | | |
10163 | | --> "a different piece of text" | |
10164 | | | |
10165 | --> "some text" | |
10166 | @end group | |
10167 | @end smallexample | |
10168 | @sp 1 | |
10169 | @end ifnottex | |
10170 | @ifset print-postscript-figures | |
10171 | @sp 1 | |
10172 | @tex | |
10173 | @center @image{cons-5} | |
10174 | %%%% old method of including an image | |
10175 | % \input /usr/local/lib/tex/inputs/psfig.tex | |
10176 | % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}} | |
10177 | % \catcode`\@=0 % | |
10178 | @end tex | |
10179 | @sp 1 | |
10180 | @end ifset | |
10181 | @ifclear print-postscript-figures | |
10182 | @iftex | |
10183 | @smallexample | |
10184 | @group | |
10185 | kill-ring kill-ring-yank-pointer | |
10186 | | | | |
10187 | | ___ ___ | ___ ___ ___ ___ | |
10188 | ---> | | | --> | | | | | | | |
10189 | |___|___|----> |___|___|--> |___|___|--> nil | |
10190 | | | | | |
10191 | | | | | |
10192 | | | --> "yet more text" | |
10193 | | | | |
10194 | | --> "a different piece of text | |
10195 | | | |
10196 | --> "some text" | |
10197 | @end group | |
10198 | @end smallexample | |
10199 | @sp 1 | |
10200 | @end iftex | |
10201 | @end ifclear | |
10202 | ||
10203 | Both the variable @code{kill-ring} and the variable | |
10204 | @code{kill-ring-yank-pointer} are pointers. But the kill ring itself is | |
10205 | usually described as if it were actually what it is composed of. The | |
10206 | @code{kill-ring} is spoken of as if it were the list rather than that it | |
10207 | points to the list. Conversely, the @code{kill-ring-yank-pointer} is | |
10208 | spoken of as pointing to a list. | |
10209 | ||
10210 | These two ways of talking about the same thing sound confusing at first but | |
10211 | make sense on reflection. The kill ring is generally thought of as the | |
10212 | complete structure of data that holds the information of what has recently | |
10213 | been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer} | |
10214 | on the other hand, serves to indicate---that is, to `point to'---that part | |
10215 | of the kill ring of which the first element (the @sc{car}) will be | |
10216 | inserted. | |
10217 | ||
10218 | @ignore | |
10219 | In GNU Emacs 22, the @code{kill-new} function calls | |
10220 | ||
10221 | @code{(setq kill-ring-yank-pointer kill-ring)} | |
10222 | ||
10223 | (defun rotate-yank-pointer (arg) | |
10224 | "Rotate the yanking point in the kill ring. | |
10225 | With argument, rotate that many kills forward (or backward, if negative)." | |
10226 | (interactive "p") | |
10227 | (current-kill arg)) | |
10228 | ||
10229 | (defun current-kill (n &optional do-not-move) | |
10230 | "Rotate the yanking point by N places, and then return that kill. | |
10231 | If N is zero, `interprogram-paste-function' is set, and calling it | |
10232 | returns a string, then that string is added to the front of the | |
10233 | kill ring and returned as the latest kill. | |
10234 | If optional arg DO-NOT-MOVE is non-nil, then don't actually move the | |
10235 | yanking point; just return the Nth kill forward." | |
10236 | (let ((interprogram-paste (and (= n 0) | |
10237 | interprogram-paste-function | |
10238 | (funcall interprogram-paste-function)))) | |
10239 | (if interprogram-paste | |
10240 | (progn | |
10241 | ;; Disable the interprogram cut function when we add the new | |
10242 | ;; text to the kill ring, so Emacs doesn't try to own the | |
10243 | ;; selection, with identical text. | |
10244 | (let ((interprogram-cut-function nil)) | |
10245 | (kill-new interprogram-paste)) | |
10246 | interprogram-paste) | |
10247 | (or kill-ring (error "Kill ring is empty")) | |
10248 | (let ((ARGth-kill-element | |
10249 | (nthcdr (mod (- n (length kill-ring-yank-pointer)) | |
10250 | (length kill-ring)) | |
10251 | kill-ring))) | |
10252 | (or do-not-move | |
10253 | (setq kill-ring-yank-pointer ARGth-kill-element)) | |
10254 | (car ARGth-kill-element))))) | |
10255 | ||
10256 | @end ignore | |
10257 | ||
10258 | @need 1500 | |
d6adf7e7 | 10259 | @node yank nthcdr Exercises |
8cda6f8f GM |
10260 | @section Exercises with @code{yank} and @code{nthcdr} |
10261 | ||
10262 | @itemize @bullet | |
10263 | @item | |
10264 | Using @kbd{C-h v} (@code{describe-variable}), look at the value of | |
10265 | your kill ring. Add several items to your kill ring; look at its | |
10266 | value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way | |
10267 | around the kill ring. How many items were in your kill ring? Find | |
10268 | the value of @code{kill-ring-max}. Was your kill ring full, or could | |
10269 | you have kept more blocks of text within it? | |
10270 | ||
10271 | @item | |
10272 | Using @code{nthcdr} and @code{car}, construct a series of expressions | |
10273 | to return the first, second, third, and fourth elements of a list. | |
10274 | @end itemize | |
10275 | ||
d6adf7e7 | 10276 | @node Loops & Recursion |
8cda6f8f GM |
10277 | @chapter Loops and Recursion |
10278 | @cindex Loops and recursion | |
10279 | @cindex Recursion and loops | |
10280 | @cindex Repetition (loops) | |
10281 | ||
10282 | Emacs Lisp has two primary ways to cause an expression, or a series of | |
10283 | expressions, to be evaluated repeatedly: one uses a @code{while} | |
10284 | loop, and the other uses @dfn{recursion}. | |
10285 | ||
10286 | Repetition can be very valuable. For example, to move forward four | |
10287 | sentences, you need only write a program that will move forward one | |
10288 | sentence and then repeat the process four times. Since a computer does | |
10289 | not get bored or tired, such repetitive action does not have the | |
10290 | deleterious effects that excessive or the wrong kinds of repetition can | |
10291 | have on humans. | |
10292 | ||
10293 | People mostly write Emacs Lisp functions using @code{while} loops and | |
10294 | their kin; but you can use recursion, which provides a very powerful | |
10295 | way to think about and then to solve problems@footnote{You can write | |
10296 | recursive functions to be frugal or wasteful of mental or computer | |
10297 | resources; as it happens, methods that people find easy---that are | |
10298 | frugal of `mental resources'---sometimes use considerable computer | |
10299 | resources. Emacs was designed to run on machines that we now consider | |
10300 | limited and its default settings are conservative. You may want to | |
10301 | increase the values of @code{max-specpdl-size} and | |
10302 | @code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to | |
10303 | 15 and 30 times their default value.}. | |
10304 | ||
10305 | @menu | |
10306 | * while:: Causing a stretch of code to repeat. | |
10307 | * dolist dotimes:: | |
10308 | * Recursion:: Causing a function to call itself. | |
10309 | * Looping exercise:: | |
10310 | @end menu | |
10311 | ||
d6adf7e7 | 10312 | @node while |
8cda6f8f GM |
10313 | @section @code{while} |
10314 | @cindex Loops | |
10315 | @findex while | |
10316 | ||
10317 | The @code{while} special form tests whether the value returned by | |
10318 | evaluating its first argument is true or false. This is similar to what | |
10319 | the Lisp interpreter does with an @code{if}; what the interpreter does | |
10320 | next, however, is different. | |
10321 | ||
10322 | In a @code{while} expression, if the value returned by evaluating the | |
10323 | first argument is false, the Lisp interpreter skips the rest of the | |
10324 | expression (the @dfn{body} of the expression) and does not evaluate it. | |
10325 | However, if the value is true, the Lisp interpreter evaluates the body | |
10326 | of the expression and then again tests whether the first argument to | |
10327 | @code{while} is true or false. If the value returned by evaluating the | |
10328 | first argument is again true, the Lisp interpreter again evaluates the | |
10329 | body of the expression. | |
10330 | ||
10331 | @need 1200 | |
10332 | The template for a @code{while} expression looks like this: | |
10333 | ||
10334 | @smallexample | |
10335 | @group | |
10336 | (while @var{true-or-false-test} | |
10337 | @var{body}@dots{}) | |
10338 | @end group | |
10339 | @end smallexample | |
10340 | ||
10341 | @menu | |
10342 | * Looping with while:: Repeat so long as test returns true. | |
10343 | * Loop Example:: A @code{while} loop that uses a list. | |
10344 | * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. | |
10345 | * Incrementing Loop:: A loop with an incrementing counter. | |
10346 | * Incrementing Loop Details:: | |
10347 | * Decrementing Loop:: A loop with a decrementing counter. | |
10348 | @end menu | |
10349 | ||
8cda6f8f | 10350 | @ifnottex |
d6adf7e7 | 10351 | @node Looping with while |
8cda6f8f GM |
10352 | @unnumberedsubsec Looping with @code{while} |
10353 | @end ifnottex | |
10354 | ||
10355 | So long as the true-or-false-test of the @code{while} expression | |
10356 | returns a true value when it is evaluated, the body is repeatedly | |
10357 | evaluated. This process is called a loop since the Lisp interpreter | |
10358 | repeats the same thing again and again, like an airplane doing a loop. | |
10359 | When the result of evaluating the true-or-false-test is false, the | |
10360 | Lisp interpreter does not evaluate the rest of the @code{while} | |
10361 | expression and `exits the loop'. | |
10362 | ||
10363 | Clearly, if the value returned by evaluating the first argument to | |
10364 | @code{while} is always true, the body following will be evaluated | |
10365 | again and again @dots{} and again @dots{} forever. Conversely, if the | |
10366 | value returned is never true, the expressions in the body will never | |
10367 | be evaluated. The craft of writing a @code{while} loop consists of | |
10368 | choosing a mechanism such that the true-or-false-test returns true | |
10369 | just the number of times that you want the subsequent expressions to | |
10370 | be evaluated, and then have the test return false. | |
10371 | ||
10372 | The value returned by evaluating a @code{while} is the value of the | |
10373 | true-or-false-test. An interesting consequence of this is that a | |
10374 | @code{while} loop that evaluates without error will return @code{nil} | |
10375 | or false regardless of whether it has looped 1 or 100 times or none at | |
10376 | all. A @code{while} expression that evaluates successfully never | |
10377 | returns a true value! What this means is that @code{while} is always | |
10378 | evaluated for its side effects, which is to say, the consequences of | |
10379 | evaluating the expressions within the body of the @code{while} loop. | |
10380 | This makes sense. It is not the mere act of looping that is desired, | |
10381 | but the consequences of what happens when the expressions in the loop | |
10382 | are repeatedly evaluated. | |
10383 | ||
d6adf7e7 | 10384 | @node Loop Example |
8cda6f8f GM |
10385 | @subsection A @code{while} Loop and a List |
10386 | ||
10387 | A common way to control a @code{while} loop is to test whether a list | |
10388 | has any elements. If it does, the loop is repeated; but if it does not, | |
10389 | the repetition is ended. Since this is an important technique, we will | |
10390 | create a short example to illustrate it. | |
10391 | ||
10392 | A simple way to test whether a list has elements is to evaluate the | |
10393 | list: if it has no elements, it is an empty list and will return the | |
10394 | empty list, @code{()}, which is a synonym for @code{nil} or false. On | |
10395 | the other hand, a list with elements will return those elements when it | |
10396 | is evaluated. Since Emacs Lisp considers as true any value that is not | |
10397 | @code{nil}, a list that returns elements will test true in a | |
10398 | @code{while} loop. | |
10399 | ||
10400 | @need 1200 | |
10401 | For example, you can set the variable @code{empty-list} to @code{nil} by | |
10402 | evaluating the following @code{setq} expression: | |
10403 | ||
10404 | @smallexample | |
10405 | (setq empty-list ()) | |
10406 | @end smallexample | |
10407 | ||
10408 | @noindent | |
10409 | After evaluating the @code{setq} expression, you can evaluate the | |
10410 | variable @code{empty-list} in the usual way, by placing the cursor after | |
10411 | the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your | |
10412 | echo area: | |
10413 | ||
10414 | @smallexample | |
10415 | empty-list | |
10416 | @end smallexample | |
10417 | ||
10418 | On the other hand, if you set a variable to be a list with elements, the | |
10419 | list will appear when you evaluate the variable, as you can see by | |
10420 | evaluating the following two expressions: | |
10421 | ||
10422 | @smallexample | |
10423 | @group | |
10424 | (setq animals '(gazelle giraffe lion tiger)) | |
10425 | ||
10426 | animals | |
10427 | @end group | |
10428 | @end smallexample | |
10429 | ||
10430 | Thus, to create a @code{while} loop that tests whether there are any | |
10431 | items in the list @code{animals}, the first part of the loop will be | |
10432 | written like this: | |
10433 | ||
10434 | @smallexample | |
10435 | @group | |
10436 | (while animals | |
10437 | @dots{} | |
10438 | @end group | |
10439 | @end smallexample | |
10440 | ||
10441 | @noindent | |
10442 | When the @code{while} tests its first argument, the variable | |
10443 | @code{animals} is evaluated. It returns a list. So long as the list | |
10444 | has elements, the @code{while} considers the results of the test to be | |
10445 | true; but when the list is empty, it considers the results of the test | |
10446 | to be false. | |
10447 | ||
10448 | To prevent the @code{while} loop from running forever, some mechanism | |
10449 | needs to be provided to empty the list eventually. An oft-used | |
10450 | technique is to have one of the subsequent forms in the @code{while} | |
10451 | expression set the value of the list to be the @sc{cdr} of the list. | |
10452 | Each time the @code{cdr} function is evaluated, the list will be made | |
10453 | shorter, until eventually only the empty list will be left. At this | |
10454 | point, the test of the @code{while} loop will return false, and the | |
10455 | arguments to the @code{while} will no longer be evaluated. | |
10456 | ||
10457 | For example, the list of animals bound to the variable @code{animals} | |
10458 | can be set to be the @sc{cdr} of the original list with the | |
10459 | following expression: | |
10460 | ||
10461 | @smallexample | |
10462 | (setq animals (cdr animals)) | |
10463 | @end smallexample | |
10464 | ||
10465 | @noindent | |
10466 | If you have evaluated the previous expressions and then evaluate this | |
10467 | expression, you will see @code{(giraffe lion tiger)} appear in the echo | |
10468 | area. If you evaluate the expression again, @code{(lion tiger)} will | |
10469 | appear in the echo area. If you evaluate it again and yet again, | |
10470 | @code{(tiger)} appears and then the empty list, shown by @code{nil}. | |
10471 | ||
10472 | A template for a @code{while} loop that uses the @code{cdr} function | |
10473 | repeatedly to cause the true-or-false-test eventually to test false | |
10474 | looks like this: | |
10475 | ||
10476 | @smallexample | |
10477 | @group | |
10478 | (while @var{test-whether-list-is-empty} | |
10479 | @var{body}@dots{} | |
10480 | @var{set-list-to-cdr-of-list}) | |
10481 | @end group | |
10482 | @end smallexample | |
10483 | ||
10484 | This test and use of @code{cdr} can be put together in a function that | |
10485 | goes through a list and prints each element of the list on a line of its | |
10486 | own. | |
10487 | ||
d6adf7e7 | 10488 | @node print-elements-of-list |
8cda6f8f GM |
10489 | @subsection An Example: @code{print-elements-of-list} |
10490 | @findex print-elements-of-list | |
10491 | ||
10492 | The @code{print-elements-of-list} function illustrates a @code{while} | |
10493 | loop with a list. | |
10494 | ||
10495 | @cindex @file{*scratch*} buffer | |
10496 | The function requires several lines for its output. If you are | |
10497 | reading this in a recent instance of GNU Emacs, | |
10498 | @c GNU Emacs 21, GNU Emacs 22, or a later version, | |
10499 | you can evaluate the following expression inside of Info, as usual. | |
10500 | ||
10501 | If you are using an earlier version of Emacs, you need to copy the | |
10502 | necessary expressions to your @file{*scratch*} buffer and evaluate | |
10503 | them there. This is because the echo area had only one line in the | |
10504 | earlier versions. | |
10505 | ||
10506 | You can copy the expressions by marking the beginning of the region | |
10507 | with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to | |
10508 | the end of the region and then copying the region using @kbd{M-w} | |
10509 | (@code{kill-ring-save}, which calls @code{copy-region-as-kill} and | |
10510 | then provides visual feedback). In the @file{*scratch*} | |
10511 | buffer, you can yank the expressions back by typing @kbd{C-y} | |
10512 | (@code{yank}). | |
10513 | ||
10514 | After you have copied the expressions to the @file{*scratch*} buffer, | |
10515 | evaluate each expression in turn. Be sure to evaluate the last | |
10516 | expression, @code{(print-elements-of-list animals)}, by typing | |
10517 | @kbd{C-u C-x C-e}, that is, by giving an argument to | |
10518 | @code{eval-last-sexp}. This will cause the result of the evaluation | |
10519 | to be printed in the @file{*scratch*} buffer instead of being printed | |
10520 | in the echo area. (Otherwise you will see something like this in your | |
10521 | echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which | |
10522 | each @samp{^J} stands for a `newline'.) | |
10523 | ||
10524 | @need 1500 | |
10525 | In a recent instance of GNU Emacs, you can evaluate these expressions | |
10526 | directly in the Info buffer, and the echo area will grow to show the | |
10527 | results. | |
10528 | ||
10529 | @smallexample | |
10530 | @group | |
10531 | (setq animals '(gazelle giraffe lion tiger)) | |
10532 | ||
10533 | (defun print-elements-of-list (list) | |
10534 | "Print each element of LIST on a line of its own." | |
10535 | (while list | |
10536 | (print (car list)) | |
10537 | (setq list (cdr list)))) | |
10538 | ||
10539 | (print-elements-of-list animals) | |
10540 | @end group | |
10541 | @end smallexample | |
10542 | ||
10543 | @need 1200 | |
10544 | @noindent | |
10545 | When you evaluate the three expressions in sequence, you will see | |
10546 | this: | |
10547 | ||
10548 | @smallexample | |
10549 | @group | |
10550 | gazelle | |
10551 | ||
10552 | giraffe | |
10553 | ||
10554 | lion | |
10555 | ||
10556 | tiger | |
10557 | nil | |
10558 | @end group | |
10559 | @end smallexample | |
10560 | ||
10561 | Each element of the list is printed on a line of its own (that is what | |
10562 | the function @code{print} does) and then the value returned by the | |
10563 | function is printed. Since the last expression in the function is the | |
10564 | @code{while} loop, and since @code{while} loops always return | |
10565 | @code{nil}, a @code{nil} is printed after the last element of the list. | |
10566 | ||
d6adf7e7 | 10567 | @node Incrementing Loop |
8cda6f8f GM |
10568 | @subsection A Loop with an Incrementing Counter |
10569 | ||
10570 | A loop is not useful unless it stops when it ought. Besides | |
10571 | controlling a loop with a list, a common way of stopping a loop is to | |
10572 | write the first argument as a test that returns false when the correct | |
10573 | number of repetitions are complete. This means that the loop must | |
10574 | have a counter---an expression that counts how many times the loop | |
10575 | repeats itself. | |
10576 | ||
8cda6f8f | 10577 | @ifnottex |
d6adf7e7 | 10578 | @node Incrementing Loop Details |
8cda6f8f GM |
10579 | @unnumberedsubsec Details of an Incrementing Loop |
10580 | @end ifnottex | |
10581 | ||
10582 | The test for a loop with an incrementing counter can be an expression | |
10583 | such as @code{(< count desired-number)} which returns @code{t} for | |
10584 | true if the value of @code{count} is less than the | |
10585 | @code{desired-number} of repetitions and @code{nil} for false if the | |
10586 | value of @code{count} is equal to or is greater than the | |
10587 | @code{desired-number}. The expression that increments the count can | |
10588 | be a simple @code{setq} such as @code{(setq count (1+ count))}, where | |
10589 | @code{1+} is a built-in function in Emacs Lisp that adds 1 to its | |
10590 | argument. (The expression @w{@code{(1+ count)}} has the same result | |
10591 | as @w{@code{(+ count 1)}}, but is easier for a human to read.) | |
10592 | ||
10593 | @need 1250 | |
10594 | The template for a @code{while} loop controlled by an incrementing | |
10595 | counter looks like this: | |
10596 | ||
10597 | @smallexample | |
10598 | @group | |
10599 | @var{set-count-to-initial-value} | |
10600 | (while (< count desired-number) ; @r{true-or-false-test} | |
10601 | @var{body}@dots{} | |
10602 | (setq count (1+ count))) ; @r{incrementer} | |
10603 | @end group | |
10604 | @end smallexample | |
10605 | ||
10606 | @noindent | |
10607 | Note that you need to set the initial value of @code{count}; usually it | |
10608 | is set to 1. | |
10609 | ||
10610 | @menu | |
10611 | * Incrementing Example:: Counting pebbles in a triangle. | |
10612 | * Inc Example parts:: The parts of the function definition. | |
10613 | * Inc Example altogether:: Putting the function definition together. | |
10614 | @end menu | |
10615 | ||
d6adf7e7 | 10616 | @node Incrementing Example |
8cda6f8f GM |
10617 | @unnumberedsubsubsec Example with incrementing counter |
10618 | ||
10619 | Suppose you are playing on the beach and decide to make a triangle of | |
10620 | pebbles, putting one pebble in the first row, two in the second row, | |
10621 | three in the third row and so on, like this: | |
10622 | ||
10623 | @sp 1 | |
10624 | @c pebble diagram | |
10625 | @ifnottex | |
10626 | @smallexample | |
10627 | @group | |
10628 | * | |
10629 | * * | |
10630 | * * * | |
10631 | * * * * | |
10632 | @end group | |
10633 | @end smallexample | |
10634 | @end ifnottex | |
10635 | @iftex | |
10636 | @smallexample | |
10637 | @group | |
10638 | @bullet{} | |
10639 | @bullet{} @bullet{} | |
10640 | @bullet{} @bullet{} @bullet{} | |
10641 | @bullet{} @bullet{} @bullet{} @bullet{} | |
10642 | @end group | |
10643 | @end smallexample | |
10644 | @end iftex | |
10645 | @sp 1 | |
10646 | ||
10647 | @noindent | |
10648 | (About 2500 years ago, Pythagoras and others developed the beginnings of | |
10649 | number theory by considering questions such as this.) | |
10650 | ||
10651 | Suppose you want to know how many pebbles you will need to make a | |
10652 | triangle with 7 rows? | |
10653 | ||
10654 | Clearly, what you need to do is add up the numbers from 1 to 7. There | |
10655 | are two ways to do this; start with the smallest number, one, and add up | |
10656 | the list in sequence, 1, 2, 3, 4 and so on; or start with the largest | |
10657 | number and add the list going down: 7, 6, 5, 4 and so on. Because both | |
10658 | mechanisms illustrate common ways of writing @code{while} loops, we will | |
10659 | create two examples, one counting up and the other counting down. In | |
10660 | this first example, we will start with 1 and add 2, 3, 4 and so on. | |
10661 | ||
10662 | If you are just adding up a short list of numbers, the easiest way to do | |
10663 | it is to add up all the numbers at once. However, if you do not know | |
10664 | ahead of time how many numbers your list will have, or if you want to be | |
10665 | prepared for a very long list, then you need to design your addition so | |
10666 | that what you do is repeat a simple process many times instead of doing | |
10667 | a more complex process once. | |
10668 | ||
10669 | For example, instead of adding up all the pebbles all at once, what you | |
10670 | can do is add the number of pebbles in the first row, 1, to the number | |
10671 | in the second row, 2, and then add the total of those two rows to the | |
10672 | third row, 3. Then you can add the number in the fourth row, 4, to the | |
10673 | total of the first three rows; and so on. | |
10674 | ||
10675 | The critical characteristic of the process is that each repetitive | |
10676 | action is simple. In this case, at each step we add only two numbers, | |
10677 | the number of pebbles in the row and the total already found. This | |
10678 | process of adding two numbers is repeated again and again until the last | |
10679 | row has been added to the total of all the preceding rows. In a more | |
10680 | complex loop the repetitive action might not be so simple, but it will | |
10681 | be simpler than doing everything all at once. | |
10682 | ||
d6adf7e7 | 10683 | @node Inc Example parts |
8cda6f8f GM |
10684 | @unnumberedsubsubsec The parts of the function definition |
10685 | ||
10686 | The preceding analysis gives us the bones of our function definition: | |
10687 | first, we will need a variable that we can call @code{total} that will | |
10688 | be the total number of pebbles. This will be the value returned by | |
10689 | the function. | |
10690 | ||
10691 | Second, we know that the function will require an argument: this | |
10692 | argument will be the total number of rows in the triangle. It can be | |
10693 | called @code{number-of-rows}. | |
10694 | ||
10695 | Finally, we need a variable to use as a counter. We could call this | |
10696 | variable @code{counter}, but a better name is @code{row-number}. That | |
10697 | is because what the counter does in this function is count rows, and a | |
10698 | program should be written to be as understandable as possible. | |
10699 | ||
10700 | When the Lisp interpreter first starts evaluating the expressions in the | |
10701 | function, the value of @code{total} should be set to zero, since we have | |
10702 | not added anything to it. Then the function should add the number of | |
10703 | pebbles in the first row to the total, and then add the number of | |
10704 | pebbles in the second to the total, and then add the number of | |
10705 | pebbles in the third row to the total, and so on, until there are no | |
10706 | more rows left to add. | |
10707 | ||
10708 | Both @code{total} and @code{row-number} are used only inside the | |
10709 | function, so they can be declared as local variables with @code{let} | |
10710 | and given initial values. Clearly, the initial value for @code{total} | |
10711 | should be 0. The initial value of @code{row-number} should be 1, | |
10712 | since we start with the first row. This means that the @code{let} | |
10713 | statement will look like this: | |
10714 | ||
10715 | @smallexample | |
10716 | @group | |
10717 | (let ((total 0) | |
10718 | (row-number 1)) | |
10719 | @var{body}@dots{}) | |
10720 | @end group | |
10721 | @end smallexample | |
10722 | ||
10723 | After the internal variables are declared and bound to their initial | |
10724 | values, we can begin the @code{while} loop. The expression that serves | |
10725 | as the test should return a value of @code{t} for true so long as the | |
10726 | @code{row-number} is less than or equal to the @code{number-of-rows}. | |
10727 | (If the expression tests true only so long as the row number is less | |
10728 | than the number of rows in the triangle, the last row will never be | |
10729 | added to the total; hence the row number has to be either less than or | |
10730 | equal to the number of rows.) | |
10731 | ||
10732 | @need 1500 | |
10733 | @findex <= @r{(less than or equal)} | |
10734 | Lisp provides the @code{<=} function that returns true if the value of | |
10735 | its first argument is less than or equal to the value of its second | |
10736 | argument and false otherwise. So the expression that the @code{while} | |
10737 | will evaluate as its test should look like this: | |
10738 | ||
10739 | @smallexample | |
10740 | (<= row-number number-of-rows) | |
10741 | @end smallexample | |
10742 | ||
10743 | The total number of pebbles can be found by repeatedly adding the number | |
10744 | of pebbles in a row to the total already found. Since the number of | |
10745 | pebbles in the row is equal to the row number, the total can be found by | |
10746 | adding the row number to the total. (Clearly, in a more complex | |
10747 | situation, the number of pebbles in the row might be related to the row | |
10748 | number in a more complicated way; if this were the case, the row number | |
10749 | would be replaced by the appropriate expression.) | |
10750 | ||
10751 | @smallexample | |
10752 | (setq total (+ total row-number)) | |
10753 | @end smallexample | |
10754 | ||
10755 | @noindent | |
10756 | What this does is set the new value of @code{total} to be equal to the | |
10757 | sum of adding the number of pebbles in the row to the previous total. | |
10758 | ||
10759 | After setting the value of @code{total}, the conditions need to be | |
10760 | established for the next repetition of the loop, if there is one. This | |
10761 | is done by incrementing the value of the @code{row-number} variable, | |
10762 | which serves as a counter. After the @code{row-number} variable has | |
10763 | been incremented, the true-or-false-test at the beginning of the | |
10764 | @code{while} loop tests whether its value is still less than or equal to | |
10765 | the value of the @code{number-of-rows} and if it is, adds the new value | |
10766 | of the @code{row-number} variable to the @code{total} of the previous | |
10767 | repetition of the loop. | |
10768 | ||
10769 | @need 1200 | |
10770 | The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the | |
10771 | @code{row-number} variable can be incremented with this expression: | |
10772 | ||
10773 | @smallexample | |
10774 | (setq row-number (1+ row-number)) | |
10775 | @end smallexample | |
10776 | ||
d6adf7e7 | 10777 | @node Inc Example altogether |
8cda6f8f GM |
10778 | @unnumberedsubsubsec Putting the function definition together |
10779 | ||
10780 | We have created the parts for the function definition; now we need to | |
10781 | put them together. | |
10782 | ||
10783 | @need 800 | |
10784 | First, the contents of the @code{while} expression: | |
10785 | ||
10786 | @smallexample | |
10787 | @group | |
10788 | (while (<= row-number number-of-rows) ; @r{true-or-false-test} | |
10789 | (setq total (+ total row-number)) | |
10790 | (setq row-number (1+ row-number))) ; @r{incrementer} | |
10791 | @end group | |
10792 | @end smallexample | |
10793 | ||
10794 | Along with the @code{let} expression varlist, this very nearly | |
10795 | completes the body of the function definition. However, it requires | |
10796 | one final element, the need for which is somewhat subtle. | |
10797 | ||
10798 | The final touch is to place the variable @code{total} on a line by | |
10799 | itself after the @code{while} expression. Otherwise, the value returned | |
10800 | by the whole function is the value of the last expression that is | |
10801 | evaluated in the body of the @code{let}, and this is the value | |
10802 | returned by the @code{while}, which is always @code{nil}. | |
10803 | ||
10804 | This may not be evident at first sight. It almost looks as if the | |
10805 | incrementing expression is the last expression of the whole function. | |
10806 | But that expression is part of the body of the @code{while}; it is the | |
10807 | last element of the list that starts with the symbol @code{while}. | |
10808 | Moreover, the whole of the @code{while} loop is a list within the body | |
10809 | of the @code{let}. | |
10810 | ||
10811 | @need 1250 | |
10812 | In outline, the function will look like this: | |
10813 | ||
10814 | @smallexample | |
10815 | @group | |
10816 | (defun @var{name-of-function} (@var{argument-list}) | |
10817 | "@var{documentation}@dots{}" | |
10818 | (let (@var{varlist}) | |
10819 | (while (@var{true-or-false-test}) | |
10820 | @var{body-of-while}@dots{} ) | |
10821 | @dots{} )) ; @r{Need final expression here.} | |
10822 | @end group | |
10823 | @end smallexample | |
10824 | ||
10825 | The result of evaluating the @code{let} is what is going to be returned | |
10826 | by the @code{defun} since the @code{let} is not embedded within any | |
10827 | containing list, except for the @code{defun} as a whole. However, if | |
10828 | the @code{while} is the last element of the @code{let} expression, the | |
10829 | function will always return @code{nil}. This is not what we want! | |
10830 | Instead, what we want is the value of the variable @code{total}. This | |
10831 | is returned by simply placing the symbol as the last element of the list | |
10832 | starting with @code{let}. It gets evaluated after the preceding | |
10833 | elements of the list are evaluated, which means it gets evaluated after | |
10834 | it has been assigned the correct value for the total. | |
10835 | ||
10836 | It may be easier to see this by printing the list starting with | |
10837 | @code{let} all on one line. This format makes it evident that the | |
10838 | @var{varlist} and @code{while} expressions are the second and third | |
10839 | elements of the list starting with @code{let}, and the @code{total} is | |
10840 | the last element: | |
10841 | ||
10842 | @smallexample | |
10843 | @group | |
10844 | (let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total) | |
10845 | @end group | |
10846 | @end smallexample | |
10847 | ||
10848 | @need 1200 | |
10849 | Putting everything together, the @code{triangle} function definition | |
10850 | looks like this: | |
10851 | ||
10852 | @smallexample | |
10853 | @group | |
10854 | (defun triangle (number-of-rows) ; @r{Version with} | |
10855 | ; @r{ incrementing counter.} | |
10856 | "Add up the number of pebbles in a triangle. | |
10857 | The first row has one pebble, the second row two pebbles, | |
10858 | the third row three pebbles, and so on. | |
10859 | The argument is NUMBER-OF-ROWS." | |
10860 | @end group | |
10861 | @group | |
10862 | (let ((total 0) | |
10863 | (row-number 1)) | |
10864 | (while (<= row-number number-of-rows) | |
10865 | (setq total (+ total row-number)) | |
10866 | (setq row-number (1+ row-number))) | |
10867 | total)) | |
10868 | @end group | |
10869 | @end smallexample | |
10870 | ||
10871 | @need 1200 | |
10872 | After you have installed @code{triangle} by evaluating the function, you | |
10873 | can try it out. Here are two examples: | |
10874 | ||
10875 | @smallexample | |
10876 | @group | |
10877 | (triangle 4) | |
10878 | ||
10879 | (triangle 7) | |
10880 | @end group | |
10881 | @end smallexample | |
10882 | ||
10883 | @noindent | |
10884 | The sum of the first four numbers is 10 and the sum of the first seven | |
10885 | numbers is 28. | |
10886 | ||
d6adf7e7 | 10887 | @node Decrementing Loop |
8cda6f8f GM |
10888 | @subsection Loop with a Decrementing Counter |
10889 | ||
10890 | Another common way to write a @code{while} loop is to write the test | |
10891 | so that it determines whether a counter is greater than zero. So long | |
10892 | as the counter is greater than zero, the loop is repeated. But when | |
10893 | the counter is equal to or less than zero, the loop is stopped. For | |
10894 | this to work, the counter has to start out greater than zero and then | |
10895 | be made smaller and smaller by a form that is evaluated | |
10896 | repeatedly. | |
10897 | ||
10898 | The test will be an expression such as @code{(> counter 0)} which | |
10899 | returns @code{t} for true if the value of @code{counter} is greater | |
10900 | than zero, and @code{nil} for false if the value of @code{counter} is | |
10901 | equal to or less than zero. The expression that makes the number | |
10902 | smaller and smaller can be a simple @code{setq} such as @code{(setq | |
10903 | counter (1- counter))}, where @code{1-} is a built-in function in | |
10904 | Emacs Lisp that subtracts 1 from its argument. | |
10905 | ||
10906 | @need 1250 | |
10907 | The template for a decrementing @code{while} loop looks like this: | |
10908 | ||
10909 | @smallexample | |
10910 | @group | |
10911 | (while (> counter 0) ; @r{true-or-false-test} | |
10912 | @var{body}@dots{} | |
10913 | (setq counter (1- counter))) ; @r{decrementer} | |
10914 | @end group | |
10915 | @end smallexample | |
10916 | ||
10917 | @menu | |
10918 | * Decrementing Example:: More pebbles on the beach. | |
10919 | * Dec Example parts:: The parts of the function definition. | |
10920 | * Dec Example altogether:: Putting the function definition together. | |
10921 | @end menu | |
10922 | ||
d6adf7e7 | 10923 | @node Decrementing Example |
8cda6f8f GM |
10924 | @unnumberedsubsubsec Example with decrementing counter |
10925 | ||
10926 | To illustrate a loop with a decrementing counter, we will rewrite the | |
10927 | @code{triangle} function so the counter decreases to zero. | |
10928 | ||
10929 | This is the reverse of the earlier version of the function. In this | |
10930 | case, to find out how many pebbles are needed to make a triangle with | |
10931 | 3 rows, add the number of pebbles in the third row, 3, to the number | |
10932 | in the preceding row, 2, and then add the total of those two rows to | |
10933 | the row that precedes them, which is 1. | |
10934 | ||
10935 | Likewise, to find the number of pebbles in a triangle with 7 rows, add | |
10936 | the number of pebbles in the seventh row, 7, to the number in the | |
10937 | preceding row, which is 6, and then add the total of those two rows to | |
10938 | the row that precedes them, which is 5, and so on. As in the previous | |
10939 | example, each addition only involves adding two numbers, the total of | |
10940 | the rows already added up and the number of pebbles in the row that is | |
10941 | being added to the total. This process of adding two numbers is | |
10942 | repeated again and again until there are no more pebbles to add. | |
10943 | ||
10944 | We know how many pebbles to start with: the number of pebbles in the | |
10945 | last row is equal to the number of rows. If the triangle has seven | |
10946 | rows, the number of pebbles in the last row is 7. Likewise, we know how | |
10947 | many pebbles are in the preceding row: it is one less than the number in | |
10948 | the row. | |
10949 | ||
d6adf7e7 | 10950 | @node Dec Example parts |
8cda6f8f GM |
10951 | @unnumberedsubsubsec The parts of the function definition |
10952 | ||
10953 | We start with three variables: the total number of rows in the | |
10954 | triangle; the number of pebbles in a row; and the total number of | |
10955 | pebbles, which is what we want to calculate. These variables can be | |
10956 | named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and | |
10957 | @code{total}, respectively. | |
10958 | ||
10959 | Both @code{total} and @code{number-of-pebbles-in-row} are used only | |
10960 | inside the function and are declared with @code{let}. The initial | |
10961 | value of @code{total} should, of course, be zero. However, the | |
10962 | initial value of @code{number-of-pebbles-in-row} should be equal to | |
10963 | the number of rows in the triangle, since the addition will start with | |
10964 | the longest row. | |
10965 | ||
10966 | @need 1250 | |
10967 | This means that the beginning of the @code{let} expression will look | |
10968 | like this: | |
10969 | ||
10970 | @smallexample | |
10971 | @group | |
10972 | (let ((total 0) | |
10973 | (number-of-pebbles-in-row number-of-rows)) | |
10974 | @var{body}@dots{}) | |
10975 | @end group | |
10976 | @end smallexample | |
10977 | ||
10978 | The total number of pebbles can be found by repeatedly adding the number | |
10979 | of pebbles in a row to the total already found, that is, by repeatedly | |
10980 | evaluating the following expression: | |
10981 | ||
10982 | @smallexample | |
10983 | (setq total (+ total number-of-pebbles-in-row)) | |
10984 | @end smallexample | |
10985 | ||
10986 | @noindent | |
10987 | After the @code{number-of-pebbles-in-row} is added to the @code{total}, | |
10988 | the @code{number-of-pebbles-in-row} should be decremented by one, since | |
10989 | the next time the loop repeats, the preceding row will be | |
10990 | added to the total. | |
10991 | ||
10992 | The number of pebbles in a preceding row is one less than the number of | |
10993 | pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be | |
10994 | used to compute the number of pebbles in the preceding row. This can be | |
10995 | done with the following expression: | |
10996 | ||
10997 | @smallexample | |
10998 | @group | |
10999 | (setq number-of-pebbles-in-row | |
11000 | (1- number-of-pebbles-in-row)) | |
11001 | @end group | |
11002 | @end smallexample | |
11003 | ||
11004 | Finally, we know that the @code{while} loop should stop making repeated | |
11005 | additions when there are no pebbles in a row. So the test for | |
11006 | the @code{while} loop is simply: | |
11007 | ||
11008 | @smallexample | |
11009 | (while (> number-of-pebbles-in-row 0) | |
11010 | @end smallexample | |
11011 | ||
d6adf7e7 | 11012 | @node Dec Example altogether |
8cda6f8f GM |
11013 | @unnumberedsubsubsec Putting the function definition together |
11014 | ||
11015 | We can put these expressions together to create a function definition | |
11016 | that works. However, on examination, we find that one of the local | |
11017 | variables is unneeded! | |
11018 | ||
11019 | @need 1250 | |
11020 | The function definition looks like this: | |
11021 | ||
11022 | @smallexample | |
11023 | @group | |
11024 | ;;; @r{First subtractive version.} | |
11025 | (defun triangle (number-of-rows) | |
11026 | "Add up the number of pebbles in a triangle." | |
11027 | (let ((total 0) | |
11028 | (number-of-pebbles-in-row number-of-rows)) | |
11029 | (while (> number-of-pebbles-in-row 0) | |
11030 | (setq total (+ total number-of-pebbles-in-row)) | |
11031 | (setq number-of-pebbles-in-row | |
11032 | (1- number-of-pebbles-in-row))) | |
11033 | total)) | |
11034 | @end group | |
11035 | @end smallexample | |
11036 | ||
11037 | As written, this function works. | |
11038 | ||
11039 | However, we do not need @code{number-of-pebbles-in-row}. | |
11040 | ||
11041 | @cindex Argument as local variable | |
11042 | When the @code{triangle} function is evaluated, the symbol | |
11043 | @code{number-of-rows} will be bound to a number, giving it an initial | |
11044 | value. That number can be changed in the body of the function as if | |
11045 | it were a local variable, without any fear that such a change will | |
11046 | effect the value of the variable outside of the function. This is a | |
11047 | very useful characteristic of Lisp; it means that the variable | |
11048 | @code{number-of-rows} can be used anywhere in the function where | |
11049 | @code{number-of-pebbles-in-row} is used. | |
11050 | ||
11051 | @need 800 | |
11052 | Here is a second version of the function written a bit more cleanly: | |
11053 | ||
11054 | @smallexample | |
11055 | @group | |
11056 | (defun triangle (number) ; @r{Second version.} | |
11057 | "Return sum of numbers 1 through NUMBER inclusive." | |
11058 | (let ((total 0)) | |
11059 | (while (> number 0) | |
11060 | (setq total (+ total number)) | |
11061 | (setq number (1- number))) | |
11062 | total)) | |
11063 | @end group | |
11064 | @end smallexample | |
11065 | ||
11066 | In brief, a properly written @code{while} loop will consist of three parts: | |
11067 | ||
11068 | @enumerate | |
11069 | @item | |
11070 | A test that will return false after the loop has repeated itself the | |
11071 | correct number of times. | |
11072 | ||
11073 | @item | |
11074 | An expression the evaluation of which will return the value desired | |
11075 | after being repeatedly evaluated. | |
11076 | ||
11077 | @item | |
11078 | An expression to change the value passed to the true-or-false-test so | |
11079 | that the test returns false after the loop has repeated itself the right | |
11080 | number of times. | |
11081 | @end enumerate | |
11082 | ||
d6adf7e7 | 11083 | @node dolist dotimes |
8cda6f8f GM |
11084 | @section Save your time: @code{dolist} and @code{dotimes} |
11085 | ||
11086 | In addition to @code{while}, both @code{dolist} and @code{dotimes} | |
11087 | provide for looping. Sometimes these are quicker to write than the | |
11088 | equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, , | |
11089 | Macros, elisp, The GNU Emacs Lisp Reference Manual}. ) | |
11090 | ||
11091 | @code{dolist} works like a @code{while} loop that `@sc{cdr}s down a | |
11092 | list': @code{dolist} automatically shortens the list each time it | |
11093 | loops---takes the @sc{cdr} of the list---and binds the @sc{car} of | |
11094 | each shorter version of the list to the first of its arguments. | |
11095 | ||
11096 | @code{dotimes} loops a specific number of times: you specify the number. | |
11097 | ||
11098 | @menu | |
11099 | * dolist:: | |
11100 | * dotimes:: | |
11101 | @end menu | |
11102 | ||
d6adf7e7 GM |
11103 | @node dolist |
11104 | @unnumberedsubsec The @code{dolist} Macro | |
8cda6f8f GM |
11105 | @findex dolist |
11106 | ||
11107 | Suppose, for example, you want to reverse a list, so that | |
11108 | ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''. | |
11109 | ||
11110 | @need 1250 | |
11111 | In practice, you would use the @code{reverse} function, like this: | |
11112 | ||
11113 | @smallexample | |
11114 | @group | |
11115 | (setq animals '(gazelle giraffe lion tiger)) | |
11116 | ||
11117 | (reverse animals) | |
11118 | @end group | |
11119 | @end smallexample | |
11120 | ||
11121 | @need 800 | |
11122 | @noindent | |
11123 | Here is how you could reverse the list using a @code{while} loop: | |
11124 | ||
11125 | @smallexample | |
11126 | @group | |
11127 | (setq animals '(gazelle giraffe lion tiger)) | |
11128 | ||
11129 | (defun reverse-list-with-while (list) | |
11130 | "Using while, reverse the order of LIST." | |
11131 | (let (value) ; make sure list starts empty | |
11132 | (while list | |
11133 | (setq value (cons (car list) value)) | |
11134 | (setq list (cdr list))) | |
11135 | value)) | |
11136 | ||
11137 | (reverse-list-with-while animals) | |
11138 | @end group | |
11139 | @end smallexample | |
11140 | ||
11141 | @need 800 | |
11142 | @noindent | |
11143 | And here is how you could use the @code{dolist} macro: | |
11144 | ||
11145 | @smallexample | |
11146 | @group | |
11147 | (setq animals '(gazelle giraffe lion tiger)) | |
11148 | ||
11149 | (defun reverse-list-with-dolist (list) | |
11150 | "Using dolist, reverse the order of LIST." | |
11151 | (let (value) ; make sure list starts empty | |
11152 | (dolist (element list value) | |
11153 | (setq value (cons element value))))) | |
11154 | ||
11155 | (reverse-list-with-dolist animals) | |
11156 | @end group | |
11157 | @end smallexample | |
11158 | ||
11159 | @need 1250 | |
11160 | @noindent | |
11161 | In Info, you can place your cursor after the closing parenthesis of | |
11162 | each expression and type @kbd{C-x C-e}; in each case, you should see | |
11163 | ||
11164 | @smallexample | |
11165 | (tiger lion giraffe gazelle) | |
11166 | @end smallexample | |
11167 | ||
11168 | @noindent | |
11169 | in the echo area. | |
11170 | ||
11171 | For this example, the existing @code{reverse} function is obviously best. | |
11172 | The @code{while} loop is just like our first example (@pxref{Loop | |
11173 | Example, , A @code{while} Loop and a List}). The @code{while} first | |
11174 | checks whether the list has elements; if so, it constructs a new list | |
11175 | by adding the first element of the list to the existing list (which in | |
11176 | the first iteration of the loop is @code{nil}). Since the second | |
11177 | element is prepended in front of the first element, and the third | |
11178 | element is prepended in front of the second element, the list is reversed. | |
11179 | ||
11180 | In the expression using a @code{while} loop, | |
11181 | the @w{@code{(setq list (cdr list))}} | |
11182 | expression shortens the list, so the @code{while} loop eventually | |
11183 | stops. In addition, it provides the @code{cons} expression with a new | |
11184 | first element by creating a new and shorter list at each repetition of | |
11185 | the loop. | |
11186 | ||
11187 | The @code{dolist} expression does very much the same as the | |
11188 | @code{while} expression, except that the @code{dolist} macro does some | |
11189 | of the work you have to do when writing a @code{while} expression. | |
11190 | ||
11191 | Like a @code{while} loop, a @code{dolist} loops. What is different is | |
f99f1641 PE |
11192 | that it automatically shortens the list each time it loops---it |
11193 | `@sc{cdr}s down the list' on its own---and it automatically binds | |
8cda6f8f GM |
11194 | the @sc{car} of each shorter version of the list to the first of its |
11195 | arguments. | |
11196 | ||
11197 | In the example, the @sc{car} of each shorter version of the list is | |
11198 | referred to using the symbol @samp{element}, the list itself is called | |
11199 | @samp{list}, and the value returned is called @samp{value}. The | |
11200 | remainder of the @code{dolist} expression is the body. | |
11201 | ||
11202 | The @code{dolist} expression binds the @sc{car} of each shorter | |
11203 | version of the list to @code{element} and then evaluates the body of | |
11204 | the expression; and repeats the loop. The result is returned in | |
11205 | @code{value}. | |
11206 | ||
d6adf7e7 GM |
11207 | @node dotimes |
11208 | @unnumberedsubsec The @code{dotimes} Macro | |
8cda6f8f GM |
11209 | @findex dotimes |
11210 | ||
11211 | The @code{dotimes} macro is similar to @code{dolist}, except that it | |
11212 | loops a specific number of times. | |
11213 | ||
11214 | The first argument to @code{dotimes} is assigned the numbers 0, 1, 2 | |
11215 | and so forth each time around the loop, and the value of the third | |
11216 | argument is returned. You need to provide the value of the second | |
11217 | argument, which is how many times the macro loops. | |
11218 | ||
11219 | @need 1250 | |
11220 | For example, the following binds the numbers from 0 up to, but not | |
11221 | including, the number 3 to the first argument, @var{number}, and then | |
11222 | constructs a list of the three numbers. (The first number is 0, the | |
11223 | second number is 1, and the third number is 2; this makes a total of | |
11224 | three numbers in all, starting with zero as the first number.) | |
11225 | ||
11226 | @smallexample | |
11227 | @group | |
11228 | (let (value) ; otherwise a value is a void variable | |
11229 | (dotimes (number 3 value) | |
11230 | (setq value (cons number value)))) | |
11231 | ||
11232 | @result{} (2 1 0) | |
11233 | @end group | |
11234 | @end smallexample | |
11235 | ||
11236 | @noindent | |
11237 | @code{dotimes} returns @code{value}, so the way to use | |
11238 | @code{dotimes} is to operate on some expression @var{number} number of | |
11239 | times and then return the result, either as a list or an atom. | |
11240 | ||
11241 | @need 1250 | |
11242 | Here is an example of a @code{defun} that uses @code{dotimes} to add | |
11243 | up the number of pebbles in a triangle. | |
11244 | ||
11245 | @smallexample | |
11246 | @group | |
11247 | (defun triangle-using-dotimes (number-of-rows) | |
11248 | "Using dotimes, add up the number of pebbles in a triangle." | |
11249 | (let ((total 0)) ; otherwise a total is a void variable | |
11250 | (dotimes (number number-of-rows total) | |
11251 | (setq total (+ total (1+ number)))))) | |
11252 | ||
11253 | (triangle-using-dotimes 4) | |
11254 | @end group | |
11255 | @end smallexample | |
11256 | ||
d6adf7e7 | 11257 | @node Recursion |
8cda6f8f GM |
11258 | @section Recursion |
11259 | @cindex Recursion | |
11260 | ||
11261 | A recursive function contains code that tells the Lisp interpreter to | |
11262 | call a program that runs exactly like itself, but with slightly | |
11263 | different arguments. The code runs exactly the same because it has | |
11264 | the same name. However, even though the program has the same name, it | |
11265 | is not the same entity. It is different. In the jargon, it is a | |
11266 | different `instance'. | |
11267 | ||
11268 | Eventually, if the program is written correctly, the `slightly | |
11269 | different arguments' will become sufficiently different from the first | |
11270 | arguments that the final instance will stop. | |
11271 | ||
11272 | @menu | |
11273 | * Building Robots:: Same model, different serial number ... | |
11274 | * Recursive Definition Parts:: Walk until you stop ... | |
11275 | * Recursion with list:: Using a list as the test whether to recurse. | |
11276 | * Recursive triangle function:: | |
11277 | * Recursion with cond:: | |
11278 | * Recursive Patterns:: Often used templates. | |
11279 | * No Deferment:: Don't store up work ... | |
11280 | * No deferment solution:: | |
11281 | @end menu | |
11282 | ||
d6adf7e7 | 11283 | @node Building Robots |
8cda6f8f GM |
11284 | @subsection Building Robots: Extending the Metaphor |
11285 | @cindex Building robots | |
11286 | @cindex Robots, building | |
11287 | ||
11288 | It is sometimes helpful to think of a running program as a robot that | |
11289 | does a job. In doing its job, a recursive function calls on a second | |
11290 | robot to help it. The second robot is identical to the first in every | |
11291 | way, except that the second robot helps the first and has been | |
11292 | passed different arguments than the first. | |
11293 | ||
11294 | In a recursive function, the second robot may call a third; and the | |
11295 | third may call a fourth, and so on. Each of these is a different | |
11296 | entity; but all are clones. | |
11297 | ||
11298 | Since each robot has slightly different instructions---the arguments | |
11299 | will differ from one robot to the next---the last robot should know | |
11300 | when to stop. | |
11301 | ||
11302 | Let's expand on the metaphor in which a computer program is a robot. | |
11303 | ||
11304 | A function definition provides the blueprints for a robot. When you | |
11305 | install a function definition, that is, when you evaluate a | |
767b8eae XF |
11306 | @code{defun} macro, you install the necessary equipment to build |
11307 | robots. It is as if you were in a factory, setting up an assembly | |
11308 | line. Robots with the same name are built according to the same | |
11309 | blueprints. So they have, as it were, the same `model number', but a | |
11310 | different `serial number'. | |
8cda6f8f GM |
11311 | |
11312 | We often say that a recursive function `calls itself'. What we mean | |
11313 | is that the instructions in a recursive function cause the Lisp | |
11314 | interpreter to run a different function that has the same name and | |
11315 | does the same job as the first, but with different arguments. | |
11316 | ||
11317 | It is important that the arguments differ from one instance to the | |
11318 | next; otherwise, the process will never stop. | |
11319 | ||
d6adf7e7 | 11320 | @node Recursive Definition Parts |
8cda6f8f GM |
11321 | @subsection The Parts of a Recursive Definition |
11322 | @cindex Parts of a Recursive Definition | |
11323 | @cindex Recursive Definition Parts | |
11324 | ||
11325 | A recursive function typically contains a conditional expression which | |
11326 | has three parts: | |
11327 | ||
11328 | @enumerate | |
11329 | @item | |
11330 | A true-or-false-test that determines whether the function is called | |
11331 | again, here called the @dfn{do-again-test}. | |
11332 | ||
11333 | @item | |
11334 | The name of the function. When this name is called, a new instance of | |
11335 | the function---a new robot, as it were---is created and told what to do. | |
11336 | ||
11337 | @item | |
11338 | An expression that returns a different value each time the function is | |
11339 | called, here called the @dfn{next-step-expression}. Consequently, the | |
11340 | argument (or arguments) passed to the new instance of the function | |
11341 | will be different from that passed to the previous instance. This | |
11342 | causes the conditional expression, the @dfn{do-again-test}, to test | |
11343 | false after the correct number of repetitions. | |
11344 | @end enumerate | |
11345 | ||
11346 | Recursive functions can be much simpler than any other kind of | |
11347 | function. Indeed, when people first start to use them, they often look | |
11348 | so mysteriously simple as to be incomprehensible. Like riding a | |
11349 | bicycle, reading a recursive function definition takes a certain knack | |
11350 | which is hard at first but then seems simple. | |
11351 | ||
11352 | @need 1200 | |
11353 | There are several different common recursive patterns. A very simple | |
11354 | pattern looks like this: | |
11355 | ||
11356 | @smallexample | |
11357 | @group | |
11358 | (defun @var{name-of-recursive-function} (@var{argument-list}) | |
11359 | "@var{documentation}@dots{}" | |
11360 | (if @var{do-again-test} | |
11361 | @var{body}@dots{} | |
11362 | (@var{name-of-recursive-function} | |
11363 | @var{next-step-expression}))) | |
11364 | @end group | |
11365 | @end smallexample | |
11366 | ||
11367 | Each time a recursive function is evaluated, a new instance of it is | |
11368 | created and told what to do. The arguments tell the instance what to do. | |
11369 | ||
11370 | An argument is bound to the value of the next-step-expression. Each | |
11371 | instance runs with a different value of the next-step-expression. | |
11372 | ||
11373 | The value in the next-step-expression is used in the do-again-test. | |
11374 | ||
11375 | The value returned by the next-step-expression is passed to the new | |
11376 | instance of the function, which evaluates it (or some | |
11377 | transmogrification of it) to determine whether to continue or stop. | |
11378 | The next-step-expression is designed so that the do-again-test returns | |
11379 | false when the function should no longer be repeated. | |
11380 | ||
11381 | The do-again-test is sometimes called the @dfn{stop condition}, | |
11382 | since it stops the repetitions when it tests false. | |
11383 | ||
d6adf7e7 | 11384 | @node Recursion with list |
8cda6f8f GM |
11385 | @subsection Recursion with a List |
11386 | ||
11387 | The example of a @code{while} loop that printed the elements of a list | |
11388 | of numbers can be written recursively. Here is the code, including | |
11389 | an expression to set the value of the variable @code{animals} to a list. | |
11390 | ||
8f4ea8e0 GM |
11391 | If you are reading this in Info in Emacs, you can evaluate this |
11392 | expression directly in Info. Otherwise, you must copy the example | |
11393 | to the @file{*scratch*} buffer and evaluate each expression there. | |
11394 | Use @kbd{C-u C-x C-e} to evaluate the | |
8cda6f8f GM |
11395 | @code{(print-elements-recursively animals)} expression so that the |
11396 | results are printed in the buffer; otherwise the Lisp interpreter will | |
11397 | try to squeeze the results into the one line of the echo area. | |
11398 | ||
11399 | Also, place your cursor immediately after the last closing parenthesis | |
11400 | of the @code{print-elements-recursively} function, before the comment. | |
11401 | Otherwise, the Lisp interpreter will try to evaluate the comment. | |
11402 | ||
8cda6f8f GM |
11403 | @findex print-elements-recursively |
11404 | @smallexample | |
11405 | @group | |
11406 | (setq animals '(gazelle giraffe lion tiger)) | |
11407 | ||
11408 | (defun print-elements-recursively (list) | |
11409 | "Print each element of LIST on a line of its own. | |
11410 | Uses recursion." | |
11411 | (when list ; @r{do-again-test} | |
11412 | (print (car list)) ; @r{body} | |
11413 | (print-elements-recursively ; @r{recursive call} | |
11414 | (cdr list)))) ; @r{next-step-expression} | |
11415 | ||
11416 | (print-elements-recursively animals) | |
11417 | @end group | |
11418 | @end smallexample | |
11419 | ||
11420 | The @code{print-elements-recursively} function first tests whether | |
11421 | there is any content in the list; if there is, the function prints the | |
11422 | first element of the list, the @sc{car} of the list. Then the | |
11423 | function `invokes itself', but gives itself as its argument, not the | |
11424 | whole list, but the second and subsequent elements of the list, the | |
11425 | @sc{cdr} of the list. | |
11426 | ||
11427 | Put another way, if the list is not empty, the function invokes | |
11428 | another instance of code that is similar to the initial code, but is a | |
11429 | different thread of execution, with different arguments than the first | |
11430 | instance. | |
11431 | ||
11432 | Put in yet another way, if the list is not empty, the first robot | |
2d7752a0 | 11433 | assembles a second robot and tells it what to do; the second robot is |
8cda6f8f GM |
11434 | a different individual from the first, but is the same model. |
11435 | ||
11436 | When the second evaluation occurs, the @code{when} expression is | |
11437 | evaluated and if true, prints the first element of the list it | |
11438 | receives as its argument (which is the second element of the original | |
11439 | list). Then the function `calls itself' with the @sc{cdr} of the list | |
11440 | it is invoked with, which (the second time around) is the @sc{cdr} of | |
11441 | the @sc{cdr} of the original list. | |
11442 | ||
11443 | Note that although we say that the function `calls itself', what we | |
11444 | mean is that the Lisp interpreter assembles and instructs a new | |
11445 | instance of the program. The new instance is a clone of the first, | |
11446 | but is a separate individual. | |
11447 | ||
11448 | Each time the function `invokes itself', it invokes itself on a | |
11449 | shorter version of the original list. It creates a new instance that | |
11450 | works on a shorter list. | |
11451 | ||
11452 | Eventually, the function invokes itself on an empty list. It creates | |
11453 | a new instance whose argument is @code{nil}. The conditional expression | |
11454 | tests the value of @code{list}. Since the value of @code{list} is | |
11455 | @code{nil}, the @code{when} expression tests false so the then-part is | |
11456 | not evaluated. The function as a whole then returns @code{nil}. | |
11457 | ||
11458 | @need 1200 | |
a9097c6d KB |
11459 | When you evaluate the expression @code{(print-elements-recursively |
11460 | animals)} in the @file{*scratch*} buffer, you see this result: | |
8cda6f8f GM |
11461 | |
11462 | @smallexample | |
11463 | @group | |
11464 | gazelle | |
11465 | ||
11466 | giraffe | |
11467 | ||
11468 | lion | |
11469 | ||
11470 | tiger | |
11471 | nil | |
11472 | @end group | |
11473 | @end smallexample | |
11474 | ||
11475 | @need 2000 | |
d6adf7e7 | 11476 | @node Recursive triangle function |
8cda6f8f GM |
11477 | @subsection Recursion in Place of a Counter |
11478 | @findex triangle-recursively | |
11479 | ||
11480 | @need 1200 | |
11481 | The @code{triangle} function described in a previous section can also | |
11482 | be written recursively. It looks like this: | |
11483 | ||
11484 | @smallexample | |
11485 | @group | |
11486 | (defun triangle-recursively (number) | |
11487 | "Return the sum of the numbers 1 through NUMBER inclusive. | |
11488 | Uses recursion." | |
11489 | (if (= number 1) ; @r{do-again-test} | |
11490 | 1 ; @r{then-part} | |
11491 | (+ number ; @r{else-part} | |
11492 | (triangle-recursively ; @r{recursive call} | |
11493 | (1- number))))) ; @r{next-step-expression} | |
11494 | ||
11495 | (triangle-recursively 7) | |
11496 | @end group | |
11497 | @end smallexample | |
11498 | ||
11499 | @noindent | |
11500 | You can install this function by evaluating it and then try it by | |
11501 | evaluating @code{(triangle-recursively 7)}. (Remember to put your | |
11502 | cursor immediately after the last parenthesis of the function | |
11503 | definition, before the comment.) The function evaluates to 28. | |
11504 | ||
11505 | To understand how this function works, let's consider what happens in the | |
11506 | various cases when the function is passed 1, 2, 3, or 4 as the value of | |
11507 | its argument. | |
11508 | ||
11509 | @menu | |
11510 | * Recursive Example arg of 1 or 2:: | |
11511 | * Recursive Example arg of 3 or 4:: | |
11512 | @end menu | |
11513 | ||
8cda6f8f | 11514 | @ifnottex |
d6adf7e7 | 11515 | @node Recursive Example arg of 1 or 2 |
8cda6f8f GM |
11516 | @unnumberedsubsubsec An argument of 1 or 2 |
11517 | @end ifnottex | |
11518 | ||
11519 | First, what happens if the value of the argument is 1? | |
11520 | ||
11521 | The function has an @code{if} expression after the documentation | |
11522 | string. It tests whether the value of @code{number} is equal to 1; if | |
11523 | so, Emacs evaluates the then-part of the @code{if} expression, which | |
11524 | returns the number 1 as the value of the function. (A triangle with | |
11525 | one row has one pebble in it.) | |
11526 | ||
11527 | Suppose, however, that the value of the argument is 2. In this case, | |
11528 | Emacs evaluates the else-part of the @code{if} expression. | |
11529 | ||
11530 | @need 1200 | |
11531 | The else-part consists of an addition, the recursive call to | |
11532 | @code{triangle-recursively} and a decrementing action; and it looks like | |
11533 | this: | |
11534 | ||
11535 | @smallexample | |
11536 | (+ number (triangle-recursively (1- number))) | |
11537 | @end smallexample | |
11538 | ||
11539 | When Emacs evaluates this expression, the innermost expression is | |
11540 | evaluated first; then the other parts in sequence. Here are the steps | |
11541 | in detail: | |
11542 | ||
11543 | @table @i | |
11544 | @item Step 1 @w{ } Evaluate the innermost expression. | |
11545 | ||
11546 | The innermost expression is @code{(1- number)} so Emacs decrements the | |
11547 | value of @code{number} from 2 to 1. | |
11548 | ||
11549 | @item Step 2 @w{ } Evaluate the @code{triangle-recursively} function. | |
11550 | ||
11551 | The Lisp interpreter creates an individual instance of | |
11552 | @code{triangle-recursively}. It does not matter that this function is | |
11553 | contained within itself. Emacs passes the result Step 1 as the | |
11554 | argument used by this instance of the @code{triangle-recursively} | |
11555 | function | |
11556 | ||
11557 | In this case, Emacs evaluates @code{triangle-recursively} with an | |
11558 | argument of 1. This means that this evaluation of | |
11559 | @code{triangle-recursively} returns 1. | |
11560 | ||
11561 | @item Step 3 @w{ } Evaluate the value of @code{number}. | |
11562 | ||
11563 | The variable @code{number} is the second element of the list that | |
11564 | starts with @code{+}; its value is 2. | |
11565 | ||
11566 | @item Step 4 @w{ } Evaluate the @code{+} expression. | |
11567 | ||
11568 | The @code{+} expression receives two arguments, the first | |
11569 | from the evaluation of @code{number} (Step 3) and the second from the | |
11570 | evaluation of @code{triangle-recursively} (Step 2). | |
11571 | ||
11572 | The result of the addition is the sum of 2 plus 1, and the number 3 is | |
11573 | returned, which is correct. A triangle with two rows has three | |
11574 | pebbles in it. | |
11575 | @end table | |
11576 | ||
d6adf7e7 | 11577 | @node Recursive Example arg of 3 or 4 |
8cda6f8f GM |
11578 | @unnumberedsubsubsec An argument of 3 or 4 |
11579 | ||
11580 | Suppose that @code{triangle-recursively} is called with an argument of | |
11581 | 3. | |
11582 | ||
11583 | @table @i | |
11584 | @item Step 1 @w{ } Evaluate the do-again-test. | |
11585 | ||
11586 | The @code{if} expression is evaluated first. This is the do-again | |
11587 | test and returns false, so the else-part of the @code{if} expression | |
11588 | is evaluated. (Note that in this example, the do-again-test causes | |
11589 | the function to call itself when it tests false, not when it tests | |
11590 | true.) | |
11591 | ||
11592 | @item Step 2 @w{ } Evaluate the innermost expression of the else-part. | |
11593 | ||
11594 | The innermost expression of the else-part is evaluated, which decrements | |
11595 | 3 to 2. This is the next-step-expression. | |
11596 | ||
11597 | @item Step 3 @w{ } Evaluate the @code{triangle-recursively} function. | |
11598 | ||
11599 | The number 2 is passed to the @code{triangle-recursively} function. | |
11600 | ||
a9097c6d | 11601 | We already know what happens when Emacs evaluates @code{triangle-recursively} with |
8cda6f8f GM |
11602 | an argument of 2. After going through the sequence of actions described |
11603 | earlier, it returns a value of 3. So that is what will happen here. | |
11604 | ||
11605 | @item Step 4 @w{ } Evaluate the addition. | |
11606 | ||
11607 | 3 will be passed as an argument to the addition and will be added to the | |
11608 | number with which the function was called, which is 3. | |
11609 | @end table | |
11610 | ||
11611 | @noindent | |
11612 | The value returned by the function as a whole will be 6. | |
11613 | ||
11614 | Now that we know what will happen when @code{triangle-recursively} is | |
11615 | called with an argument of 3, it is evident what will happen if it is | |
11616 | called with an argument of 4: | |
11617 | ||
11618 | @quotation | |
11619 | @need 800 | |
11620 | In the recursive call, the evaluation of | |
11621 | ||
11622 | @smallexample | |
11623 | (triangle-recursively (1- 4)) | |
11624 | @end smallexample | |
11625 | ||
11626 | @need 800 | |
11627 | @noindent | |
11628 | will return the value of evaluating | |
11629 | ||
11630 | @smallexample | |
11631 | (triangle-recursively 3) | |
11632 | @end smallexample | |
11633 | ||
11634 | @noindent | |
11635 | which is 6 and this value will be added to 4 by the addition in the | |
11636 | third line. | |
11637 | @end quotation | |
11638 | ||
11639 | @noindent | |
11640 | The value returned by the function as a whole will be 10. | |
11641 | ||
11642 | Each time @code{triangle-recursively} is evaluated, it evaluates a | |
11643 | version of itself---a different instance of itself---with a smaller | |
11644 | argument, until the argument is small enough so that it does not | |
11645 | evaluate itself. | |
11646 | ||
11647 | Note that this particular design for a recursive function | |
11648 | requires that operations be deferred. | |
11649 | ||
11650 | Before @code{(triangle-recursively 7)} can calculate its answer, it | |
11651 | must call @code{(triangle-recursively 6)}; and before | |
11652 | @code{(triangle-recursively 6)} can calculate its answer, it must call | |
11653 | @code{(triangle-recursively 5)}; and so on. That is to say, the | |
11654 | calculation that @code{(triangle-recursively 7)} makes must be | |
11655 | deferred until @code{(triangle-recursively 6)} makes its calculation; | |
11656 | and @code{(triangle-recursively 6)} must defer until | |
11657 | @code{(triangle-recursively 5)} completes; and so on. | |
11658 | ||
11659 | If each of these instances of @code{triangle-recursively} are thought | |
11660 | of as different robots, the first robot must wait for the second to | |
11661 | complete its job, which must wait until the third completes, and so | |
11662 | on. | |
11663 | ||
11664 | There is a way around this kind of waiting, which we will discuss in | |
11665 | @ref{No Deferment, , Recursion without Deferments}. | |
11666 | ||
d6adf7e7 | 11667 | @node Recursion with cond |
8cda6f8f GM |
11668 | @subsection Recursion Example Using @code{cond} |
11669 | @findex cond | |
11670 | ||
11671 | The version of @code{triangle-recursively} described earlier is written | |
11672 | with the @code{if} special form. It can also be written using another | |
11673 | special form called @code{cond}. The name of the special form | |
11674 | @code{cond} is an abbreviation of the word @samp{conditional}. | |
11675 | ||
11676 | Although the @code{cond} special form is not used as often in the | |
11677 | Emacs Lisp sources as @code{if}, it is used often enough to justify | |
11678 | explaining it. | |
11679 | ||
11680 | @need 800 | |
11681 | The template for a @code{cond} expression looks like this: | |
11682 | ||
11683 | @smallexample | |
11684 | @group | |
11685 | (cond | |
11686 | @var{body}@dots{}) | |
11687 | @end group | |
11688 | @end smallexample | |
11689 | ||
11690 | @noindent | |
11691 | where the @var{body} is a series of lists. | |
11692 | ||
11693 | @need 800 | |
11694 | Written out more fully, the template looks like this: | |
11695 | ||
11696 | @smallexample | |
11697 | @group | |
11698 | (cond | |
11699 | (@var{first-true-or-false-test} @var{first-consequent}) | |
11700 | (@var{second-true-or-false-test} @var{second-consequent}) | |
11701 | (@var{third-true-or-false-test} @var{third-consequent}) | |
11702 | @dots{}) | |
11703 | @end group | |
11704 | @end smallexample | |
11705 | ||
11706 | When the Lisp interpreter evaluates the @code{cond} expression, it | |
11707 | evaluates the first element (the @sc{car} or true-or-false-test) of | |
11708 | the first expression in a series of expressions within the body of the | |
11709 | @code{cond}. | |
11710 | ||
11711 | If the true-or-false-test returns @code{nil} the rest of that | |
11712 | expression, the consequent, is skipped and the true-or-false-test of the | |
11713 | next expression is evaluated. When an expression is found whose | |
11714 | true-or-false-test returns a value that is not @code{nil}, the | |
11715 | consequent of that expression is evaluated. The consequent can be one | |
11716 | or more expressions. If the consequent consists of more than one | |
11717 | expression, the expressions are evaluated in sequence and the value of | |
11718 | the last one is returned. If the expression does not have a consequent, | |
11719 | the value of the true-or-false-test is returned. | |
11720 | ||
11721 | If none of the true-or-false-tests test true, the @code{cond} expression | |
11722 | returns @code{nil}. | |
11723 | ||
11724 | @need 1250 | |
11725 | Written using @code{cond}, the @code{triangle} function looks like this: | |
11726 | ||
11727 | @smallexample | |
11728 | @group | |
11729 | (defun triangle-using-cond (number) | |
11730 | (cond ((<= number 0) 0) | |
11731 | ((= number 1) 1) | |
11732 | ((> number 1) | |
11733 | (+ number (triangle-using-cond (1- number)))))) | |
11734 | @end group | |
11735 | @end smallexample | |
11736 | ||
11737 | @noindent | |
11738 | In this example, the @code{cond} returns 0 if the number is less than or | |
11739 | equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+ | |
11740 | number (triangle-using-cond (1- number)))} if the number is greater than | |
11741 | 1. | |
11742 | ||
d6adf7e7 | 11743 | @node Recursive Patterns |
8cda6f8f GM |
11744 | @subsection Recursive Patterns |
11745 | @cindex Recursive Patterns | |
11746 | ||
11747 | Here are three common recursive patterns. Each involves a list. | |
11748 | Recursion does not need to involve lists, but Lisp is designed for lists | |
11749 | and this provides a sense of its primal capabilities. | |
11750 | ||
11751 | @menu | |
11752 | * Every:: | |
11753 | * Accumulate:: | |
11754 | * Keep:: | |
11755 | @end menu | |
11756 | ||
d6adf7e7 | 11757 | @node Every |
8cda6f8f GM |
11758 | @unnumberedsubsubsec Recursive Pattern: @emph{every} |
11759 | @cindex Every, type of recursive pattern | |
11760 | @cindex Recursive pattern: every | |
11761 | ||
11762 | In the @code{every} recursive pattern, an action is performed on every | |
11763 | element of a list. | |
11764 | ||
11765 | @need 1500 | |
11766 | The basic pattern is: | |
11767 | ||
11768 | @itemize @bullet | |
11769 | @item | |
11770 | If a list be empty, return @code{nil}. | |
11771 | @item | |
11772 | Else, act on the beginning of the list (the @sc{car} of the list) | |
11773 | @itemize @minus | |
11774 | @item | |
11775 | through a recursive call by the function on the rest (the | |
11776 | @sc{cdr}) of the list, | |
11777 | @item | |
11778 | and, optionally, combine the acted-on element, using @code{cons}, | |
11779 | with the results of acting on the rest. | |
11780 | @end itemize | |
11781 | @end itemize | |
11782 | ||
11783 | @need 1500 | |
11784 | Here is example: | |
11785 | ||
11786 | @smallexample | |
11787 | @group | |
11788 | (defun square-each (numbers-list) | |
11789 | "Square each of a NUMBERS LIST, recursively." | |
11790 | (if (not numbers-list) ; do-again-test | |
11791 | nil | |
11792 | (cons | |
11793 | (* (car numbers-list) (car numbers-list)) | |
11794 | (square-each (cdr numbers-list))))) ; next-step-expression | |
11795 | @end group | |
11796 | ||
11797 | @group | |
11798 | (square-each '(1 2 3)) | |
11799 | @result{} (1 4 9) | |
11800 | @end group | |
11801 | @end smallexample | |
11802 | ||
11803 | @need 1200 | |
11804 | @noindent | |
11805 | If @code{numbers-list} is empty, do nothing. But if it has content, | |
11806 | construct a list combining the square of the first number in the list | |
11807 | with the result of the recursive call. | |
11808 | ||
11809 | (The example follows the pattern exactly: @code{nil} is returned if | |
11810 | the numbers' list is empty. In practice, you would write the | |
11811 | conditional so it carries out the action when the numbers' list is not | |
11812 | empty.) | |
11813 | ||
11814 | The @code{print-elements-recursively} function (@pxref{Recursion with | |
11815 | list, , Recursion with a List}) is another example of an @code{every} | |
11816 | pattern, except in this case, rather than bring the results together | |
11817 | using @code{cons}, we print each element of output. | |
11818 | ||
11819 | @need 1250 | |
11820 | The @code{print-elements-recursively} function looks like this: | |
11821 | ||
11822 | @smallexample | |
11823 | @group | |
11824 | (setq animals '(gazelle giraffe lion tiger)) | |
11825 | @end group | |
11826 | ||
11827 | @group | |
11828 | (defun print-elements-recursively (list) | |
11829 | "Print each element of LIST on a line of its own. | |
11830 | Uses recursion." | |
11831 | (when list ; @r{do-again-test} | |
11832 | (print (car list)) ; @r{body} | |
11833 | (print-elements-recursively ; @r{recursive call} | |
11834 | (cdr list)))) ; @r{next-step-expression} | |
11835 | ||
11836 | (print-elements-recursively animals) | |
11837 | @end group | |
11838 | @end smallexample | |
11839 | ||
11840 | @need 1500 | |
11841 | The pattern for @code{print-elements-recursively} is: | |
11842 | ||
11843 | @itemize @bullet | |
11844 | @item | |
11845 | When the list is empty, do nothing. | |
11846 | @item | |
11847 | But when the list has at least one element, | |
11848 | @itemize @minus | |
11849 | @item | |
11850 | act on the beginning of the list (the @sc{car} of the list), | |
11851 | @item | |
11852 | and make a recursive call on the rest (the @sc{cdr}) of the list. | |
11853 | @end itemize | |
11854 | @end itemize | |
11855 | ||
d6adf7e7 | 11856 | @node Accumulate |
8cda6f8f GM |
11857 | @unnumberedsubsubsec Recursive Pattern: @emph{accumulate} |
11858 | @cindex Accumulate, type of recursive pattern | |
11859 | @cindex Recursive pattern: accumulate | |
11860 | ||
11861 | Another recursive pattern is called the @code{accumulate} pattern. In | |
11862 | the @code{accumulate} recursive pattern, an action is performed on | |
11863 | every element of a list and the result of that action is accumulated | |
11864 | with the results of performing the action on the other elements. | |
11865 | ||
11866 | This is very like the `every' pattern using @code{cons}, except that | |
11867 | @code{cons} is not used, but some other combiner. | |
11868 | ||
11869 | @need 1500 | |
11870 | The pattern is: | |
11871 | ||
11872 | @itemize @bullet | |
11873 | @item | |
11874 | If a list be empty, return zero or some other constant. | |
11875 | @item | |
11876 | Else, act on the beginning of the list (the @sc{car} of the list), | |
11877 | @itemize @minus | |
11878 | @item | |
11879 | and combine that acted-on element, using @code{+} or | |
11880 | some other combining function, with | |
11881 | @item | |
11882 | a recursive call by the function on the rest (the @sc{cdr}) of the list. | |
11883 | @end itemize | |
11884 | @end itemize | |
11885 | ||
11886 | @need 1500 | |
11887 | Here is an example: | |
11888 | ||
11889 | @smallexample | |
11890 | @group | |
11891 | (defun add-elements (numbers-list) | |
11892 | "Add the elements of NUMBERS-LIST together." | |
11893 | (if (not numbers-list) | |
11894 | 0 | |
11895 | (+ (car numbers-list) (add-elements (cdr numbers-list))))) | |
11896 | @end group | |
11897 | ||
11898 | @group | |
11899 | (add-elements '(1 2 3 4)) | |
11900 | @result{} 10 | |
11901 | @end group | |
11902 | @end smallexample | |
11903 | ||
11904 | @xref{Files List, , Making a List of Files}, for an example of the | |
11905 | accumulate pattern. | |
11906 | ||
d6adf7e7 | 11907 | @node Keep |
8cda6f8f GM |
11908 | @unnumberedsubsubsec Recursive Pattern: @emph{keep} |
11909 | @cindex Keep, type of recursive pattern | |
11910 | @cindex Recursive pattern: keep | |
11911 | ||
11912 | A third recursive pattern is called the @code{keep} pattern. | |
11913 | In the @code{keep} recursive pattern, each element of a list is tested; | |
11914 | the element is acted on and the results are kept only if the element | |
11915 | meets a criterion. | |
11916 | ||
11917 | Again, this is very like the `every' pattern, except the element is | |
11918 | skipped unless it meets a criterion. | |
11919 | ||
11920 | @need 1500 | |
11921 | The pattern has three parts: | |
11922 | ||
11923 | @itemize @bullet | |
11924 | @item | |
11925 | If a list be empty, return @code{nil}. | |
11926 | @item | |
11927 | Else, if the beginning of the list (the @sc{car} of the list) passes | |
11928 | a test | |
11929 | @itemize @minus | |
11930 | @item | |
11931 | act on that element and combine it, using @code{cons} with | |
11932 | @item | |
11933 | a recursive call by the function on the rest (the @sc{cdr}) of the list. | |
11934 | @end itemize | |
11935 | @item | |
11936 | Otherwise, if the beginning of the list (the @sc{car} of the list) fails | |
11937 | the test | |
11938 | @itemize @minus | |
11939 | @item | |
11940 | skip on that element, | |
11941 | @item | |
11942 | and, recursively call the function on the rest (the @sc{cdr}) of the list. | |
11943 | @end itemize | |
11944 | @end itemize | |
11945 | ||
11946 | @need 1500 | |
11947 | Here is an example that uses @code{cond}: | |
11948 | ||
11949 | @smallexample | |
11950 | @group | |
11951 | (defun keep-three-letter-words (word-list) | |
11952 | "Keep three letter words in WORD-LIST." | |
11953 | (cond | |
11954 | ;; First do-again-test: stop-condition | |
11955 | ((not word-list) nil) | |
11956 | ||
11957 | ;; Second do-again-test: when to act | |
11958 | ((eq 3 (length (symbol-name (car word-list)))) | |
11959 | ;; combine acted-on element with recursive call on shorter list | |
11960 | (cons (car word-list) (keep-three-letter-words (cdr word-list)))) | |
11961 | ||
11962 | ;; Third do-again-test: when to skip element; | |
11963 | ;; recursively call shorter list with next-step expression | |
11964 | (t (keep-three-letter-words (cdr word-list))))) | |
11965 | @end group | |
11966 | ||
11967 | @group | |
11968 | (keep-three-letter-words '(one two three four five six)) | |
11969 | @result{} (one two six) | |
11970 | @end group | |
11971 | @end smallexample | |
11972 | ||
11973 | It goes without saying that you need not use @code{nil} as the test for | |
11974 | when to stop; and you can, of course, combine these patterns. | |
11975 | ||
d6adf7e7 | 11976 | @node No Deferment |
8cda6f8f GM |
11977 | @subsection Recursion without Deferments |
11978 | @cindex Deferment in recursion | |
11979 | @cindex Recursion without Deferments | |
11980 | ||
11981 | Let's consider again what happens with the @code{triangle-recursively} | |
11982 | function. We will find that the intermediate calculations are | |
11983 | deferred until all can be done. | |
11984 | ||
11985 | @need 800 | |
11986 | Here is the function definition: | |
11987 | ||
11988 | @smallexample | |
11989 | @group | |
11990 | (defun triangle-recursively (number) | |
11991 | "Return the sum of the numbers 1 through NUMBER inclusive. | |
11992 | Uses recursion." | |
11993 | (if (= number 1) ; @r{do-again-test} | |
11994 | 1 ; @r{then-part} | |
11995 | (+ number ; @r{else-part} | |
11996 | (triangle-recursively ; @r{recursive call} | |
11997 | (1- number))))) ; @r{next-step-expression} | |
11998 | @end group | |
11999 | @end smallexample | |
12000 | ||
12001 | What happens when we call this function with a argument of 7? | |
12002 | ||
12003 | The first instance of the @code{triangle-recursively} function adds | |
12004 | the number 7 to the value returned by a second instance of | |
12005 | @code{triangle-recursively}, an instance that has been passed an | |
12006 | argument of 6. That is to say, the first calculation is: | |
12007 | ||
12008 | @smallexample | |
12009 | (+ 7 (triangle-recursively 6)) | |
12010 | @end smallexample | |
12011 | ||
12012 | @noindent | |
12013 | The first instance of @code{triangle-recursively}---you may want to | |
12014 | think of it as a little robot---cannot complete its job. It must hand | |
12015 | off the calculation for @code{(triangle-recursively 6)} to a second | |
12016 | instance of the program, to a second robot. This second individual is | |
12017 | completely different from the first one; it is, in the jargon, a | |
12018 | `different instantiation'. Or, put another way, it is a different | |
12019 | robot. It is the same model as the first; it calculates triangle | |
12020 | numbers recursively; but it has a different serial number. | |
12021 | ||
12022 | And what does @code{(triangle-recursively 6)} return? It returns the | |
12023 | number 6 added to the value returned by evaluating | |
12024 | @code{triangle-recursively} with an argument of 5. Using the robot | |
12025 | metaphor, it asks yet another robot to help it. | |
12026 | ||
12027 | @need 800 | |
12028 | Now the total is: | |
12029 | ||
12030 | @smallexample | |
12031 | (+ 7 6 (triangle-recursively 5)) | |
12032 | @end smallexample | |
12033 | ||
12034 | @need 800 | |
12035 | And what happens next? | |
12036 | ||
12037 | @smallexample | |
12038 | (+ 7 6 5 (triangle-recursively 4)) | |
12039 | @end smallexample | |
12040 | ||
12041 | Each time @code{triangle-recursively} is called, except for the last | |
12042 | time, it creates another instance of the program---another robot---and | |
12043 | asks it to make a calculation. | |
12044 | ||
12045 | @need 800 | |
12046 | Eventually, the full addition is set up and performed: | |
12047 | ||
12048 | @smallexample | |
12049 | (+ 7 6 5 4 3 2 1) | |
12050 | @end smallexample | |
12051 | ||
12052 | This design for the function defers the calculation of the first step | |
12053 | until the second can be done, and defers that until the third can be | |
12054 | done, and so on. Each deferment means the computer must remember what | |
12055 | is being waited on. This is not a problem when there are only a few | |
12056 | steps, as in this example. But it can be a problem when there are | |
12057 | more steps. | |
12058 | ||
d6adf7e7 | 12059 | @node No deferment solution |
8cda6f8f GM |
12060 | @subsection No Deferment Solution |
12061 | @cindex No deferment solution | |
12062 | @cindex Defermentless solution | |
12063 | @cindex Solution without deferment | |
12064 | ||
12065 | The solution to the problem of deferred operations is to write in a | |
12066 | manner that does not defer operations@footnote{The phrase @dfn{tail | |
12067 | recursive} is used to describe such a process, one that uses | |
12068 | `constant space'.}. This requires | |
12069 | writing to a different pattern, often one that involves writing two | |
12070 | function definitions, an `initialization' function and a `helper' | |
12071 | function. | |
12072 | ||
12073 | The `initialization' function sets up the job; the `helper' function | |
12074 | does the work. | |
12075 | ||
12076 | @need 1200 | |
12077 | Here are the two function definitions for adding up numbers. They are | |
12078 | so simple, I find them hard to understand. | |
12079 | ||
12080 | @smallexample | |
12081 | @group | |
12082 | (defun triangle-initialization (number) | |
12083 | "Return the sum of the numbers 1 through NUMBER inclusive. | |
12084 | This is the `initialization' component of a two function | |
12085 | duo that uses recursion." | |
12086 | (triangle-recursive-helper 0 0 number)) | |
12087 | @end group | |
12088 | @end smallexample | |
12089 | ||
12090 | @smallexample | |
12091 | @group | |
12092 | (defun triangle-recursive-helper (sum counter number) | |
12093 | "Return SUM, using COUNTER, through NUMBER inclusive. | |
12094 | This is the `helper' component of a two function duo | |
12095 | that uses recursion." | |
12096 | (if (> counter number) | |
12097 | sum | |
12098 | (triangle-recursive-helper (+ sum counter) ; @r{sum} | |
12099 | (1+ counter) ; @r{counter} | |
12100 | number))) ; @r{number} | |
12101 | @end group | |
12102 | @end smallexample | |
12103 | ||
12104 | @need 1250 | |
12105 | Install both function definitions by evaluating them, then call | |
12106 | @code{triangle-initialization} with 2 rows: | |
12107 | ||
12108 | @smallexample | |
12109 | @group | |
12110 | (triangle-initialization 2) | |
12111 | @result{} 3 | |
12112 | @end group | |
12113 | @end smallexample | |
12114 | ||
12115 | The `initialization' function calls the first instance of the `helper' | |
12116 | function with three arguments: zero, zero, and a number which is the | |
12117 | number of rows in the triangle. | |
12118 | ||
12119 | The first two arguments passed to the `helper' function are | |
12120 | initialization values. These values are changed when | |
12121 | @code{triangle-recursive-helper} invokes new instances.@footnote{The | |
12122 | jargon is mildly confusing: @code{triangle-recursive-helper} uses a | |
12123 | process that is iterative in a procedure that is recursive. The | |
12124 | process is called iterative because the computer need only record the | |
12125 | three values, @code{sum}, @code{counter}, and @code{number}; the | |
12126 | procedure is recursive because the function `calls itself'. On the | |
12127 | other hand, both the process and the procedure used by | |
12128 | @code{triangle-recursively} are called recursive. The word | |
12129 | `recursive' has different meanings in the two contexts.} | |
12130 | ||
12131 | Let's see what happens when we have a triangle that has one row. (This | |
12132 | triangle will have one pebble in it!) | |
12133 | ||
12134 | @need 1200 | |
12135 | @code{triangle-initialization} will call its helper with | |
12136 | the arguments @w{@code{0 0 1}}. That function will run the conditional | |
12137 | test whether @code{(> counter number)}: | |
12138 | ||
12139 | @smallexample | |
12140 | (> 0 1) | |
12141 | @end smallexample | |
12142 | ||
12143 | @need 1200 | |
12144 | @noindent | |
12145 | and find that the result is false, so it will invoke | |
12146 | the else-part of the @code{if} clause: | |
12147 | ||
12148 | @smallexample | |
12149 | @group | |
12150 | (triangle-recursive-helper | |
12151 | (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} | |
12152 | (1+ counter) ; @r{increment counter} @result{} @r{counter} | |
12153 | number) ; @r{number stays the same} | |
12154 | @end group | |
12155 | @end smallexample | |
12156 | ||
12157 | @need 800 | |
12158 | @noindent | |
12159 | which will first compute: | |
12160 | ||
12161 | @smallexample | |
12162 | @group | |
12163 | (triangle-recursive-helper (+ 0 0) ; @r{sum} | |
12164 | (1+ 0) ; @r{counter} | |
12165 | 1) ; @r{number} | |
12166 | @exdent which is: | |
12167 | ||
12168 | (triangle-recursive-helper 0 1 1) | |
12169 | @end group | |
12170 | @end smallexample | |
12171 | ||
12172 | Again, @code{(> counter number)} will be false, so again, the Lisp | |
12173 | interpreter will evaluate @code{triangle-recursive-helper}, creating a | |
12174 | new instance with new arguments. | |
12175 | ||
12176 | @need 800 | |
12177 | This new instance will be; | |
12178 | ||
12179 | @smallexample | |
12180 | @group | |
12181 | (triangle-recursive-helper | |
12182 | (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} | |
12183 | (1+ counter) ; @r{increment counter} @result{} @r{counter} | |
12184 | number) ; @r{number stays the same} | |
12185 | ||
12186 | @exdent which is: | |
12187 | ||
12188 | (triangle-recursive-helper 1 2 1) | |
12189 | @end group | |
12190 | @end smallexample | |
12191 | ||
12192 | In this case, the @code{(> counter number)} test will be true! So the | |
12193 | instance will return the value of the sum, which will be 1, as | |
12194 | expected. | |
12195 | ||
12196 | Now, let's pass @code{triangle-initialization} an argument | |
12197 | of 2, to find out how many pebbles there are in a triangle with two rows. | |
12198 | ||
12199 | That function calls @code{(triangle-recursive-helper 0 0 2)}. | |
12200 | ||
12201 | @need 800 | |
12202 | In stages, the instances called will be: | |
12203 | ||
12204 | @smallexample | |
12205 | @group | |
12206 | @r{sum counter number} | |
12207 | (triangle-recursive-helper 0 1 2) | |
12208 | ||
12209 | (triangle-recursive-helper 1 2 2) | |
12210 | ||
12211 | (triangle-recursive-helper 3 3 2) | |
12212 | @end group | |
12213 | @end smallexample | |
12214 | ||
12215 | When the last instance is called, the @code{(> counter number)} test | |
12216 | will be true, so the instance will return the value of @code{sum}, | |
12217 | which will be 3. | |
12218 | ||
12219 | This kind of pattern helps when you are writing functions that can use | |
12220 | many resources in a computer. | |
12221 | ||
12222 | @need 1500 | |
d6adf7e7 | 12223 | @node Looping exercise |
8cda6f8f GM |
12224 | @section Looping Exercise |
12225 | ||
12226 | @itemize @bullet | |
12227 | @item | |
12228 | Write a function similar to @code{triangle} in which each row has a | |
12229 | value which is the square of the row number. Use a @code{while} loop. | |
12230 | ||
12231 | @item | |
12232 | Write a function similar to @code{triangle} that multiplies instead of | |
12233 | adds the values. | |
12234 | ||
12235 | @item | |
12236 | Rewrite these two functions recursively. Rewrite these functions | |
12237 | using @code{cond}. | |
12238 | ||
12239 | @c comma in printed title causes problem in Info cross reference | |
12240 | @item | |
12241 | Write a function for Texinfo mode that creates an index entry at the | |
12242 | beginning of a paragraph for every @samp{@@dfn} within the paragraph. | |
12243 | (In a Texinfo file, @samp{@@dfn} marks a definition. This book is | |
12244 | written in Texinfo.) | |
12245 | ||
12246 | Many of the functions you will need are described in two of the | |
12247 | previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing | |
12248 | Text}, and @ref{Yanking, , Yanking Text Back}. If you use | |
12249 | @code{forward-paragraph} to put the index entry at the beginning of | |
12250 | the paragraph, you will have to use @w{@kbd{C-h f}} | |
12251 | (@code{describe-function}) to find out how to make the command go | |
12252 | backwards. | |
12253 | ||
12254 | For more information, see | |
12255 | @ifinfo | |
12256 | @ref{Indicating, , Indicating Definitions, texinfo}. | |
12257 | @end ifinfo | |
12258 | @ifhtml | |
12259 | @ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to | |
12260 | a Texinfo manual in the current directory. Or, if you are on the | |
12261 | Internet, see | |
12262 | @uref{http://www.gnu.org/software/texinfo/manual/texinfo/} | |
12263 | @end ifhtml | |
12264 | @iftex | |
12265 | ``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU | |
12266 | Documentation Format}. | |
12267 | @end iftex | |
12268 | @end itemize | |
12269 | ||
d6adf7e7 | 12270 | @node Regexp Search |
8cda6f8f GM |
12271 | @chapter Regular Expression Searches |
12272 | @cindex Searches, illustrating | |
12273 | @cindex Regular expression searches | |
12274 | @cindex Patterns, searching for | |
12275 | @cindex Motion by sentence and paragraph | |
12276 | @cindex Sentences, movement by | |
12277 | @cindex Paragraphs, movement by | |
12278 | ||
12279 | Regular expression searches are used extensively in GNU Emacs. The | |
12280 | two functions, @code{forward-sentence} and @code{forward-paragraph}, | |
12281 | illustrate these searches well. They use regular expressions to find | |
12282 | where to move point. The phrase `regular expression' is often written | |
12283 | as `regexp'. | |
12284 | ||
12285 | Regular expression searches are described in @ref{Regexp Search, , | |
12286 | Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in | |
12287 | @ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference | |
12288 | Manual}. In writing this chapter, I am presuming that you have at | |
12289 | least a mild acquaintance with them. The major point to remember is | |
12290 | that regular expressions permit you to search for patterns as well as | |
12291 | for literal strings of characters. For example, the code in | |
12292 | @code{forward-sentence} searches for the pattern of possible | |
12293 | characters that could mark the end of a sentence, and moves point to | |
12294 | that spot. | |
12295 | ||
12296 | Before looking at the code for the @code{forward-sentence} function, it | |
12297 | is worth considering what the pattern that marks the end of a sentence | |
12298 | must be. The pattern is discussed in the next section; following that | |
12299 | is a description of the regular expression search function, | |
12300 | @code{re-search-forward}. The @code{forward-sentence} function | |
12301 | is described in the section following. Finally, the | |
12302 | @code{forward-paragraph} function is described in the last section of | |
12303 | this chapter. @code{forward-paragraph} is a complex function that | |
12304 | introduces several new features. | |
12305 | ||
12306 | @menu | |
12307 | * sentence-end:: The regular expression for @code{sentence-end}. | |
12308 | * re-search-forward:: Very similar to @code{search-forward}. | |
12309 | * forward-sentence:: A straightforward example of regexp search. | |
12310 | * forward-paragraph:: A somewhat complex example. | |
12311 | * etags:: How to create your own @file{TAGS} table. | |
12312 | * Regexp Review:: | |
12313 | * re-search Exercises:: | |
12314 | @end menu | |
12315 | ||
d6adf7e7 | 12316 | @node sentence-end |
8cda6f8f GM |
12317 | @section The Regular Expression for @code{sentence-end} |
12318 | @findex sentence-end | |
12319 | ||
12320 | The symbol @code{sentence-end} is bound to the pattern that marks the | |
12321 | end of a sentence. What should this regular expression be? | |
12322 | ||
12323 | Clearly, a sentence may be ended by a period, a question mark, or an | |
12324 | exclamation mark. Indeed, in English, only clauses that end with one | |
12325 | of those three characters should be considered the end of a sentence. | |
12326 | This means that the pattern should include the character set: | |
12327 | ||
12328 | @smallexample | |
12329 | [.?!] | |
12330 | @end smallexample | |
12331 | ||
12332 | However, we do not want @code{forward-sentence} merely to jump to a | |
12333 | period, a question mark, or an exclamation mark, because such a character | |
12334 | might be used in the middle of a sentence. A period, for example, is | |
12335 | used after abbreviations. So other information is needed. | |
12336 | ||
12337 | According to convention, you type two spaces after every sentence, but | |
12338 | only one space after a period, a question mark, or an exclamation mark in | |
12339 | the body of a sentence. So a period, a question mark, or an exclamation | |
12340 | mark followed by two spaces is a good indicator of an end of sentence. | |
12341 | However, in a file, the two spaces may instead be a tab or the end of a | |
12342 | line. This means that the regular expression should include these three | |
12343 | items as alternatives. | |
12344 | ||
12345 | @need 800 | |
12346 | This group of alternatives will look like this: | |
12347 | ||
12348 | @smallexample | |
12349 | @group | |
12350 | \\($\\| \\| \\) | |
12351 | ^ ^^ | |
12352 | TAB SPC | |
12353 | @end group | |
12354 | @end smallexample | |
12355 | ||
12356 | @noindent | |
12357 | Here, @samp{$} indicates the end of the line, and I have pointed out | |
12358 | where the tab and two spaces are inserted in the expression. Both are | |
12359 | inserted by putting the actual characters into the expression. | |
12360 | ||
12361 | Two backslashes, @samp{\\}, are required before the parentheses and | |
12362 | vertical bars: the first backslash quotes the following backslash in | |
12363 | Emacs; and the second indicates that the following character, the | |
12364 | parenthesis or the vertical bar, is special. | |
12365 | ||
12366 | @need 1000 | |
12367 | Also, a sentence may be followed by one or more carriage returns, like | |
12368 | this: | |
12369 | ||
12370 | @smallexample | |
12371 | @group | |
12372 | [ | |
12373 | ]* | |
12374 | @end group | |
12375 | @end smallexample | |
12376 | ||
12377 | @noindent | |
12378 | Like tabs and spaces, a carriage return is inserted into a regular | |
12379 | expression by inserting it literally. The asterisk indicates that the | |
12380 | @key{RET} is repeated zero or more times. | |
12381 | ||
12382 | But a sentence end does not consist only of a period, a question mark or | |
12383 | an exclamation mark followed by appropriate space: a closing quotation | |
12384 | mark or a closing brace of some kind may precede the space. Indeed more | |
12385 | than one such mark or brace may precede the space. These require a | |
12386 | expression that looks like this: | |
12387 | ||
12388 | @smallexample | |
12389 | []\"')@}]* | |
12390 | @end smallexample | |
12391 | ||
12392 | In this expression, the first @samp{]} is the first character in the | |
12393 | expression; the second character is @samp{"}, which is preceded by a | |
12394 | @samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last | |
12395 | three characters are @samp{'}, @samp{)}, and @samp{@}}. | |
12396 | ||
12397 | All this suggests what the regular expression pattern for matching the | |
12398 | end of a sentence should be; and, indeed, if we evaluate | |
12399 | @code{sentence-end} we find that it returns the following value: | |
12400 | ||
12401 | @smallexample | |
12402 | @group | |
12403 | sentence-end | |
12404 | @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[ | |
12405 | ]*" | |
12406 | @end group | |
12407 | @end smallexample | |
12408 | ||
12409 | @noindent | |
12410 | (Well, not in GNU Emacs 22; that is because of an effort to make the | |
12411 | process simpler and to handle more glyphs and languages. When the | |
12412 | value of @code{sentence-end} is @code{nil}, then use the value defined | |
12413 | by the function @code{sentence-end}. (Here is a use of the difference | |
12414 | between a value and a function in Emacs Lisp.) The function returns a | |
12415 | value constructed from the variables @code{sentence-end-base}, | |
12416 | @code{sentence-end-double-space}, @code{sentence-end-without-period}, | |
12417 | and @code{sentence-end-without-space}. The critical variable is | |
12418 | @code{sentence-end-base}; its global value is similar to the one | |
12419 | described above but it also contains two additional quotation marks. | |
12420 | These have differing degrees of curliness. The | |
12421 | @code{sentence-end-without-period} variable, when true, tells Emacs | |
12422 | that a sentence may end without a period, such as text in Thai.) | |
12423 | ||
12424 | @ignore | |
12425 | @noindent | |
12426 | (Note that here the @key{TAB}, two spaces, and @key{RET} are shown | |
12427 | literally in the pattern.) | |
12428 | ||
12429 | This regular expression can be deciphered as follows: | |
12430 | ||
12431 | @table @code | |
12432 | @item [.?!] | |
12433 | The first part of the pattern is the three characters, a period, a question | |
12434 | mark and an exclamation mark, within square brackets. The pattern must | |
12435 | begin with one or other of these characters. | |
12436 | ||
12437 | @item []\"')@}]* | |
12438 | The second part of the pattern is the group of closing braces and | |
12439 | quotation marks, which can appear zero or more times. These may follow | |
12440 | the period, question mark or exclamation mark. In a regular expression, | |
12441 | the backslash, @samp{\}, followed by the double quotation mark, | |
12442 | @samp{"}, indicates the class of string-quote characters. Usually, the | |
12443 | double quotation mark is the only character in this class. The | |
12444 | asterisk, @samp{*}, indicates that the items in the previous group (the | |
12445 | group surrounded by square brackets, @samp{[]}) may be repeated zero or | |
12446 | more times. | |
12447 | ||
12448 | @item \\($\\| \\| \\) | |
12449 | The third part of the pattern is one or other of: either the end of a | |
12450 | line, or two blank spaces, or a tab. The double back-slashes are used | |
12451 | to prevent Emacs from reading the parentheses and vertical bars as part | |
12452 | of the search pattern; the parentheses are used to mark the group and | |
12453 | the vertical bars are used to indicated that the patterns to either side | |
12454 | of them are alternatives. The dollar sign is used to indicate the end | |
12455 | of a line and both the two spaces and the tab are each inserted as is to | |
12456 | indicate what they are. | |
12457 | ||
12458 | @item [@key{RET}]* | |
12459 | Finally, the last part of the pattern indicates that the end of the line | |
12460 | or the whitespace following the period, question mark or exclamation | |
12461 | mark may, but need not, be followed by one or more carriage returns. In | |
12462 | the pattern, the carriage return is inserted as an actual carriage | |
12463 | return between square brackets but here it is shown as @key{RET}. | |
12464 | @end table | |
12465 | @end ignore | |
12466 | ||
d6adf7e7 | 12467 | @node re-search-forward |
8cda6f8f GM |
12468 | @section The @code{re-search-forward} Function |
12469 | @findex re-search-forward | |
12470 | ||
12471 | The @code{re-search-forward} function is very like the | |
12472 | @code{search-forward} function. (@xref{search-forward, , The | |
12473 | @code{search-forward} Function}.) | |
12474 | ||
12475 | @code{re-search-forward} searches for a regular expression. If the | |
12476 | search is successful, it leaves point immediately after the last | |
12477 | character in the target. If the search is backwards, it leaves point | |
12478 | just before the first character in the target. You may tell | |
12479 | @code{re-search-forward} to return @code{t} for true. (Moving point | |
12480 | is therefore a `side effect'.) | |
12481 | ||
12482 | Like @code{search-forward}, the @code{re-search-forward} function takes | |
12483 | four arguments: | |
12484 | ||
12485 | @enumerate | |
12486 | @item | |
12487 | The first argument is the regular expression that the function searches | |
7b4b1301 | 12488 | for. The regular expression will be a string between quotation marks. |
8cda6f8f GM |
12489 | |
12490 | @item | |
12491 | The optional second argument limits how far the function will search; it is a | |
12492 | bound, which is specified as a position in the buffer. | |
12493 | ||
12494 | @item | |
12495 | The optional third argument specifies how the function responds to | |
12496 | failure: @code{nil} as the third argument causes the function to | |
12497 | signal an error (and print a message) when the search fails; any other | |
12498 | value causes it to return @code{nil} if the search fails and @code{t} | |
12499 | if the search succeeds. | |
12500 | ||
12501 | @item | |
12502 | The optional fourth argument is the repeat count. A negative repeat | |
12503 | count causes @code{re-search-forward} to search backwards. | |
12504 | @end enumerate | |
12505 | ||
12506 | @need 800 | |
12507 | The template for @code{re-search-forward} looks like this: | |
12508 | ||
12509 | @smallexample | |
12510 | @group | |
12511 | (re-search-forward "@var{regular-expression}" | |
12512 | @var{limit-of-search} | |
12513 | @var{what-to-do-if-search-fails} | |
12514 | @var{repeat-count}) | |
12515 | @end group | |
12516 | @end smallexample | |
12517 | ||
12518 | The second, third, and fourth arguments are optional. However, if you | |
12519 | want to pass a value to either or both of the last two arguments, you | |
12520 | must also pass a value to all the preceding arguments. Otherwise, the | |
12521 | Lisp interpreter will mistake which argument you are passing the value | |
12522 | to. | |
12523 | ||
12524 | @need 1200 | |
12525 | In the @code{forward-sentence} function, the regular expression will be | |
12526 | the value of the variable @code{sentence-end}. In simple form, that is: | |
12527 | ||
12528 | @smallexample | |
12529 | @group | |
12530 | "[.?!][]\"')@}]*\\($\\| \\| \\)[ | |
12531 | ]*" | |
12532 | @end group | |
12533 | @end smallexample | |
12534 | ||
12535 | @noindent | |
12536 | The limit of the search will be the end of the paragraph (since a | |
12537 | sentence cannot go beyond a paragraph). If the search fails, the | |
12538 | function will return @code{nil}; and the repeat count will be provided | |
12539 | by the argument to the @code{forward-sentence} function. | |
12540 | ||
d6adf7e7 | 12541 | @node forward-sentence |
8cda6f8f GM |
12542 | @section @code{forward-sentence} |
12543 | @findex forward-sentence | |
12544 | ||
12545 | The command to move the cursor forward a sentence is a straightforward | |
12546 | illustration of how to use regular expression searches in Emacs Lisp. | |
12547 | Indeed, the function looks longer and more complicated than it is; this | |
12548 | is because the function is designed to go backwards as well as forwards; | |
12549 | and, optionally, over more than one sentence. The function is usually | |
12550 | bound to the key command @kbd{M-e}. | |
12551 | ||
12552 | @menu | |
12553 | * Complete forward-sentence:: | |
12554 | * fwd-sentence while loops:: Two @code{while} loops. | |
12555 | * fwd-sentence re-search:: A regular expression search. | |
12556 | @end menu | |
12557 | ||
8cda6f8f | 12558 | @ifnottex |
d6adf7e7 | 12559 | @node Complete forward-sentence |
8cda6f8f GM |
12560 | @unnumberedsubsec Complete @code{forward-sentence} function definition |
12561 | @end ifnottex | |
12562 | ||
12563 | @need 1250 | |
12564 | Here is the code for @code{forward-sentence}: | |
12565 | ||
12566 | @c in GNU Emacs 22 | |
12567 | @smallexample | |
12568 | @group | |
12569 | (defun forward-sentence (&optional arg) | |
12570 | "Move forward to next `sentence-end'. With argument, repeat. | |
12571 | With negative argument, move backward repeatedly to `sentence-beginning'. | |
12572 | ||
12573 | The variable `sentence-end' is a regular expression that matches ends of | |
12574 | sentences. Also, every paragraph boundary terminates sentences as well." | |
12575 | @end group | |
12576 | @group | |
12577 | (interactive "p") | |
12578 | (or arg (setq arg 1)) | |
12579 | (let ((opoint (point)) | |
12580 | (sentence-end (sentence-end))) | |
12581 | (while (< arg 0) | |
12582 | (let ((pos (point)) | |
12583 | (par-beg (save-excursion (start-of-paragraph-text) (point)))) | |
12584 | (if (and (re-search-backward sentence-end par-beg t) | |
12585 | (or (< (match-end 0) pos) | |
12586 | (re-search-backward sentence-end par-beg t))) | |
12587 | (goto-char (match-end 0)) | |
12588 | (goto-char par-beg))) | |
12589 | (setq arg (1+ arg))) | |
12590 | @end group | |
12591 | @group | |
12592 | (while (> arg 0) | |
12593 | (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) | |
12594 | (if (re-search-forward sentence-end par-end t) | |
12595 | (skip-chars-backward " \t\n") | |
12596 | (goto-char par-end))) | |
12597 | (setq arg (1- arg))) | |
12598 | (constrain-to-field nil opoint t))) | |
12599 | @end group | |
12600 | @end smallexample | |
12601 | ||
12602 | @ignore | |
12603 | GNU Emacs 21 | |
12604 | @smallexample | |
12605 | @group | |
12606 | (defun forward-sentence (&optional arg) | |
12607 | "Move forward to next sentence-end. With argument, repeat. | |
12608 | With negative argument, move backward repeatedly to sentence-beginning. | |
12609 | Sentence ends are identified by the value of sentence-end | |
12610 | treated as a regular expression. Also, every paragraph boundary | |
12611 | terminates sentences as well." | |
12612 | @end group | |
12613 | @group | |
12614 | (interactive "p") | |
12615 | (or arg (setq arg 1)) | |
12616 | (while (< arg 0) | |
12617 | (let ((par-beg | |
12618 | (save-excursion (start-of-paragraph-text) (point)))) | |
12619 | (if (re-search-backward | |
12620 | (concat sentence-end "[^ \t\n]") par-beg t) | |
12621 | (goto-char (1- (match-end 0))) | |
12622 | (goto-char par-beg))) | |
12623 | (setq arg (1+ arg))) | |
12624 | (while (> arg 0) | |
12625 | (let ((par-end | |
12626 | (save-excursion (end-of-paragraph-text) (point)))) | |
12627 | (if (re-search-forward sentence-end par-end t) | |
12628 | (skip-chars-backward " \t\n") | |
12629 | (goto-char par-end))) | |
12630 | (setq arg (1- arg)))) | |
12631 | @end group | |
12632 | @end smallexample | |
12633 | @end ignore | |
12634 | ||
12635 | The function looks long at first sight and it is best to look at its | |
12636 | skeleton first, and then its muscle. The way to see the skeleton is to | |
12637 | look at the expressions that start in the left-most columns: | |
12638 | ||
12639 | @smallexample | |
12640 | @group | |
12641 | (defun forward-sentence (&optional arg) | |
12642 | "@var{documentation}@dots{}" | |
12643 | (interactive "p") | |
12644 | (or arg (setq arg 1)) | |
12645 | (let ((opoint (point)) (sentence-end (sentence-end))) | |
12646 | (while (< arg 0) | |
12647 | (let ((pos (point)) | |
12648 | (par-beg (save-excursion (start-of-paragraph-text) (point)))) | |
12649 | @var{rest-of-body-of-while-loop-when-going-backwards} | |
12650 | (while (> arg 0) | |
12651 | (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) | |
12652 | @var{rest-of-body-of-while-loop-when-going-forwards} | |
12653 | @var{handle-forms-and-equivalent} | |
12654 | @end group | |
12655 | @end smallexample | |
12656 | ||
12657 | This looks much simpler! The function definition consists of | |
12658 | documentation, an @code{interactive} expression, an @code{or} | |
12659 | expression, a @code{let} expression, and @code{while} loops. | |
12660 | ||
12661 | Let's look at each of these parts in turn. | |
12662 | ||
12663 | We note that the documentation is thorough and understandable. | |
12664 | ||
12665 | The function has an @code{interactive "p"} declaration. This means | |
12666 | that the processed prefix argument, if any, is passed to the | |
12667 | function as its argument. (This will be a number.) If the function | |
12668 | is not passed an argument (it is optional) then the argument | |
12669 | @code{arg} will be bound to 1. | |
12670 | ||
12671 | When @code{forward-sentence} is called non-interactively without an | |
12672 | argument, @code{arg} is bound to @code{nil}. The @code{or} expression | |
12673 | handles this. What it does is either leave the value of @code{arg} as | |
12674 | it is, but only if @code{arg} is bound to a value; or it sets the | |
12675 | value of @code{arg} to 1, in the case when @code{arg} is bound to | |
12676 | @code{nil}. | |
12677 | ||
12678 | Next is a @code{let}. That specifies the values of two local | |
12679 | variables, @code{point} and @code{sentence-end}. The local value of | |
12680 | point, from before the search, is used in the | |
12681 | @code{constrain-to-field} function which handles forms and | |
12682 | equivalents. The @code{sentence-end} variable is set by the | |
12683 | @code{sentence-end} function. | |
12684 | ||
d6adf7e7 | 12685 | @node fwd-sentence while loops |
8cda6f8f GM |
12686 | @unnumberedsubsec The @code{while} loops |
12687 | ||
12688 | Two @code{while} loops follow. The first @code{while} has a | |
12689 | true-or-false-test that tests true if the prefix argument for | |
12690 | @code{forward-sentence} is a negative number. This is for going | |
12691 | backwards. The body of this loop is similar to the body of the second | |
12692 | @code{while} clause, but it is not exactly the same. We will skip | |
12693 | this @code{while} loop and concentrate on the second @code{while} | |
12694 | loop. | |
12695 | ||
12696 | @need 1500 | |
12697 | The second @code{while} loop is for moving point forward. Its skeleton | |
12698 | looks like this: | |
12699 | ||
12700 | @smallexample | |
12701 | @group | |
12702 | (while (> arg 0) ; @r{true-or-false-test} | |
12703 | (let @var{varlist} | |
12704 | (if (@var{true-or-false-test}) | |
12705 | @var{then-part} | |
12706 | @var{else-part} | |
12707 | (setq arg (1- arg)))) ; @code{while} @r{loop decrementer} | |
12708 | @end group | |
12709 | @end smallexample | |
12710 | ||
12711 | The @code{while} loop is of the decrementing kind. | |
12712 | (@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It | |
12713 | has a true-or-false-test that tests true so long as the counter (in | |
12714 | this case, the variable @code{arg}) is greater than zero; and it has a | |
12715 | decrementer that subtracts 1 from the value of the counter every time | |
12716 | the loop repeats. | |
12717 | ||
12718 | If no prefix argument is given to @code{forward-sentence}, which is | |
12719 | the most common way the command is used, this @code{while} loop will | |
12720 | run once, since the value of @code{arg} will be 1. | |
12721 | ||
12722 | The body of the @code{while} loop consists of a @code{let} expression, | |
12723 | which creates and binds a local variable, and has, as its body, an | |
12724 | @code{if} expression. | |
12725 | ||
12726 | @need 1250 | |
12727 | The body of the @code{while} loop looks like this: | |
12728 | ||
12729 | @smallexample | |
12730 | @group | |
12731 | (let ((par-end | |
12732 | (save-excursion (end-of-paragraph-text) (point)))) | |
12733 | (if (re-search-forward sentence-end par-end t) | |
12734 | (skip-chars-backward " \t\n") | |
12735 | (goto-char par-end))) | |
12736 | @end group | |
12737 | @end smallexample | |
12738 | ||
12739 | The @code{let} expression creates and binds the local variable | |
12740 | @code{par-end}. As we shall see, this local variable is designed to | |
12741 | provide a bound or limit to the regular expression search. If the | |
12742 | search fails to find a proper sentence ending in the paragraph, it will | |
12743 | stop on reaching the end of the paragraph. | |
12744 | ||
12745 | But first, let us examine how @code{par-end} is bound to the value of | |
12746 | the end of the paragraph. What happens is that the @code{let} sets the | |
12747 | value of @code{par-end} to the value returned when the Lisp interpreter | |
12748 | evaluates the expression | |
12749 | ||
12750 | @smallexample | |
12751 | @group | |
12752 | (save-excursion (end-of-paragraph-text) (point)) | |
12753 | @end group | |
12754 | @end smallexample | |
12755 | ||
12756 | @noindent | |
12757 | In this expression, @code{(end-of-paragraph-text)} moves point to the | |
12758 | end of the paragraph, @code{(point)} returns the value of point, and then | |
12759 | @code{save-excursion} restores point to its original position. Thus, | |
12760 | the @code{let} binds @code{par-end} to the value returned by the | |
12761 | @code{save-excursion} expression, which is the position of the end of | |
12762 | the paragraph. (The @code{end-of-paragraph-text} function uses | |
12763 | @code{forward-paragraph}, which we will discuss shortly.) | |
12764 | ||
12765 | @need 1200 | |
12766 | Emacs next evaluates the body of the @code{let}, which is an @code{if} | |
12767 | expression that looks like this: | |
12768 | ||
12769 | @smallexample | |
12770 | @group | |
12771 | (if (re-search-forward sentence-end par-end t) ; @r{if-part} | |
12772 | (skip-chars-backward " \t\n") ; @r{then-part} | |
12773 | (goto-char par-end))) ; @r{else-part} | |
12774 | @end group | |
12775 | @end smallexample | |
12776 | ||
12777 | The @code{if} tests whether its first argument is true and if so, | |
12778 | evaluates its then-part; otherwise, the Emacs Lisp interpreter | |
12779 | evaluates the else-part. The true-or-false-test of the @code{if} | |
12780 | expression is the regular expression search. | |
12781 | ||
12782 | It may seem odd to have what looks like the `real work' of | |
12783 | the @code{forward-sentence} function buried here, but this is a common | |
12784 | way this kind of operation is carried out in Lisp. | |
12785 | ||
d6adf7e7 | 12786 | @node fwd-sentence re-search |
8cda6f8f GM |
12787 | @unnumberedsubsec The regular expression search |
12788 | ||
12789 | The @code{re-search-forward} function searches for the end of the | |
12790 | sentence, that is, for the pattern defined by the @code{sentence-end} | |
12791 | regular expression. If the pattern is found---if the end of the sentence is | |
12792 | found---then the @code{re-search-forward} function does two things: | |
12793 | ||
12794 | @enumerate | |
12795 | @item | |
12796 | The @code{re-search-forward} function carries out a side effect, which | |
12797 | is to move point to the end of the occurrence found. | |
12798 | ||
12799 | @item | |
12800 | The @code{re-search-forward} function returns a value of true. This is | |
12801 | the value received by the @code{if}, and means that the search was | |
12802 | successful. | |
12803 | @end enumerate | |
12804 | ||
12805 | @noindent | |
12806 | The side effect, the movement of point, is completed before the | |
12807 | @code{if} function is handed the value returned by the successful | |
12808 | conclusion of the search. | |
12809 | ||
12810 | When the @code{if} function receives the value of true from a successful | |
12811 | call to @code{re-search-forward}, the @code{if} evaluates the then-part, | |
12812 | which is the expression @code{(skip-chars-backward " \t\n")}. This | |
12813 | expression moves backwards over any blank spaces, tabs or carriage | |
12814 | returns until a printed character is found and then leaves point after | |
12815 | the character. Since point has already been moved to the end of the | |
12816 | pattern that marks the end of the sentence, this action leaves point | |
12817 | right after the closing printed character of the sentence, which is | |
12818 | usually a period. | |
12819 | ||
12820 | On the other hand, if the @code{re-search-forward} function fails to | |
12821 | find a pattern marking the end of the sentence, the function returns | |
12822 | false. The false then causes the @code{if} to evaluate its third | |
12823 | argument, which is @code{(goto-char par-end)}: it moves point to the | |
12824 | end of the paragraph. | |
12825 | ||
12826 | (And if the text is in a form or equivalent, and point may not move | |
12827 | fully, then the @code{constrain-to-field} function comes into play.) | |
12828 | ||
12829 | Regular expression searches are exceptionally useful and the pattern | |
12830 | illustrated by @code{re-search-forward}, in which the search is the | |
12831 | test of an @code{if} expression, is handy. You will see or write code | |
12832 | incorporating this pattern often. | |
12833 | ||
d6adf7e7 | 12834 | @node forward-paragraph |
8cda6f8f GM |
12835 | @section @code{forward-paragraph}: a Goldmine of Functions |
12836 | @findex forward-paragraph | |
12837 | ||
12838 | @ignore | |
12839 | @c in GNU Emacs 22 | |
12840 | (defun forward-paragraph (&optional arg) | |
12841 | "Move forward to end of paragraph. | |
12842 | With argument ARG, do it ARG times; | |
12843 | a negative argument ARG = -N means move backward N paragraphs. | |
12844 | ||
12845 | A line which `paragraph-start' matches either separates paragraphs | |
12846 | \(if `paragraph-separate' matches it also) or is the first line of a paragraph. | |
12847 | A paragraph end is the beginning of a line which is not part of the paragraph | |
12848 | to which the end of the previous line belongs, or the end of the buffer. | |
12849 | Returns the count of paragraphs left to move." | |
12850 | (interactive "p") | |
12851 | (or arg (setq arg 1)) | |
12852 | (let* ((opoint (point)) | |
12853 | (fill-prefix-regexp | |
12854 | (and fill-prefix (not (equal fill-prefix "")) | |
12855 | (not paragraph-ignore-fill-prefix) | |
12856 | (regexp-quote fill-prefix))) | |
12857 | ;; Remove ^ from paragraph-start and paragraph-sep if they are there. | |
12858 | ;; These regexps shouldn't be anchored, because we look for them | |
12859 | ;; starting at the left-margin. This allows paragraph commands to | |
12860 | ;; work normally with indented text. | |
12861 | ;; This hack will not find problem cases like "whatever\\|^something". | |
12862 | (parstart (if (and (not (equal "" paragraph-start)) | |
12863 | (equal ?^ (aref paragraph-start 0))) | |
12864 | (substring paragraph-start 1) | |
12865 | paragraph-start)) | |
12866 | (parsep (if (and (not (equal "" paragraph-separate)) | |
12867 | (equal ?^ (aref paragraph-separate 0))) | |
12868 | (substring paragraph-separate 1) | |
12869 | paragraph-separate)) | |
12870 | (parsep | |
12871 | (if fill-prefix-regexp | |
12872 | (concat parsep "\\|" | |
12873 | fill-prefix-regexp "[ \t]*$") | |
12874 | parsep)) | |
12875 | ;; This is used for searching. | |
12876 | (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)")) | |
12877 | start found-start) | |
12878 | (while (and (< arg 0) (not (bobp))) | |
12879 | (if (and (not (looking-at parsep)) | |
12880 | (re-search-backward "^\n" (max (1- (point)) (point-min)) t) | |
12881 | (looking-at parsep)) | |
12882 | (setq arg (1+ arg)) | |
12883 | (setq start (point)) | |
12884 | ;; Move back over paragraph-separating lines. | |
12885 | (forward-char -1) (beginning-of-line) | |
12886 | (while (and (not (bobp)) | |
12887 | (progn (move-to-left-margin) | |
12888 | (looking-at parsep))) | |
12889 | (forward-line -1)) | |
12890 | (if (bobp) | |
12891 | nil | |
12892 | (setq arg (1+ arg)) | |
12893 | ;; Go to end of the previous (non-separating) line. | |
12894 | (end-of-line) | |
12895 | ;; Search back for line that starts or separates paragraphs. | |
12896 | (if (if fill-prefix-regexp | |
12897 | ;; There is a fill prefix; it overrides parstart. | |
12898 | (let (multiple-lines) | |
12899 | (while (and (progn (beginning-of-line) (not (bobp))) | |
12900 | (progn (move-to-left-margin) | |
12901 | (not (looking-at parsep))) | |
12902 | (looking-at fill-prefix-regexp)) | |
12903 | (unless (= (point) start) | |
12904 | (setq multiple-lines t)) | |
12905 | (forward-line -1)) | |
12906 | (move-to-left-margin) | |
12907 | ;; This deleted code caused a long hanging-indent line | |
12908 | ;; not to be filled together with the following lines. | |
12909 | ;; ;; Don't move back over a line before the paragraph | |
12910 | ;; ;; which doesn't start with fill-prefix | |
12911 | ;; ;; unless that is the only line we've moved over. | |
12912 | ;; (and (not (looking-at fill-prefix-regexp)) | |
12913 | ;; multiple-lines | |
12914 | ;; (forward-line 1)) | |
12915 | (not (bobp))) | |
12916 | (while (and (re-search-backward sp-parstart nil 1) | |
12917 | (setq found-start t) | |
12918 | ;; Found a candidate, but need to check if it is a | |
12919 | ;; REAL parstart. | |
12920 | (progn (setq start (point)) | |
12921 | (move-to-left-margin) | |
12922 | (not (looking-at parsep))) | |
12923 | (not (and (looking-at parstart) | |
12924 | (or (not use-hard-newlines) | |
12925 | (bobp) | |
12926 | (get-text-property | |
12927 | (1- start) 'hard))))) | |
12928 | (setq found-start nil) | |
12929 | (goto-char start)) | |
12930 | found-start) | |
12931 | ;; Found one. | |
12932 | (progn | |
12933 | ;; Move forward over paragraph separators. | |
12934 | ;; We know this cannot reach the place we started | |
12935 | ;; because we know we moved back over a non-separator. | |
12936 | (while (and (not (eobp)) | |
12937 | (progn (move-to-left-margin) | |
12938 | (looking-at parsep))) | |
12939 | (forward-line 1)) | |
12940 | ;; If line before paragraph is just margin, back up to there. | |
12941 | (end-of-line 0) | |
12942 | (if (> (current-column) (current-left-margin)) | |
12943 | (forward-char 1) | |
12944 | (skip-chars-backward " \t") | |
12945 | (if (not (bolp)) | |
12946 | (forward-line 1)))) | |
12947 | ;; No starter or separator line => use buffer beg. | |
12948 | (goto-char (point-min)))))) | |
12949 | ||
12950 | (while (and (> arg 0) (not (eobp))) | |
12951 | ;; Move forward over separator lines... | |
12952 | (while (and (not (eobp)) | |
12953 | (progn (move-to-left-margin) (not (eobp))) | |
12954 | (looking-at parsep)) | |
12955 | (forward-line 1)) | |
12956 | (unless (eobp) (setq arg (1- arg))) | |
12957 | ;; ... and one more line. | |
12958 | (forward-line 1) | |
12959 | (if fill-prefix-regexp | |
12960 | ;; There is a fill prefix; it overrides parstart. | |
12961 | (while (and (not (eobp)) | |
12962 | (progn (move-to-left-margin) (not (eobp))) | |
12963 | (not (looking-at parsep)) | |
12964 | (looking-at fill-prefix-regexp)) | |
12965 | (forward-line 1)) | |
12966 | (while (and (re-search-forward sp-parstart nil 1) | |
12967 | (progn (setq start (match-beginning 0)) | |
12968 | (goto-char start) | |
12969 | (not (eobp))) | |
12970 | (progn (move-to-left-margin) | |
12971 | (not (looking-at parsep))) | |
12972 | (or (not (looking-at parstart)) | |
12973 | (and use-hard-newlines | |
12974 | (not (get-text-property (1- start) 'hard))))) | |
12975 | (forward-char 1)) | |
12976 | (if (< (point) (point-max)) | |
12977 | (goto-char start)))) | |
12978 | (constrain-to-field nil opoint t) | |
12979 | ;; Return the number of steps that could not be done. | |
12980 | arg)) | |
12981 | @end ignore | |
12982 | ||
12983 | The @code{forward-paragraph} function moves point forward to the end | |
12984 | of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a | |
12985 | number of functions that are important in themselves, including | |
12986 | @code{let*}, @code{match-beginning}, and @code{looking-at}. | |
12987 | ||
12988 | The function definition for @code{forward-paragraph} is considerably | |
12989 | longer than the function definition for @code{forward-sentence} | |
12990 | because it works with a paragraph, each line of which may begin with a | |
12991 | fill prefix. | |
12992 | ||
12993 | A fill prefix consists of a string of characters that are repeated at | |
12994 | the beginning of each line. For example, in Lisp code, it is a | |
12995 | convention to start each line of a paragraph-long comment with | |
12996 | @samp{;;; }. In Text mode, four blank spaces make up another common | |
12997 | fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , , | |
12998 | emacs, The GNU Emacs Manual}, for more information about fill | |
12999 | prefixes.) | |
13000 | ||
13001 | The existence of a fill prefix means that in addition to being able to | |
13002 | find the end of a paragraph whose lines begin on the left-most | |
13003 | column, the @code{forward-paragraph} function must be able to find the | |
13004 | end of a paragraph when all or many of the lines in the buffer begin | |
13005 | with the fill prefix. | |
13006 | ||
13007 | Moreover, it is sometimes practical to ignore a fill prefix that | |
13008 | exists, especially when blank lines separate paragraphs. | |
13009 | This is an added complication. | |
13010 | ||
13011 | @menu | |
13012 | * forward-paragraph in brief:: Key parts of the function definition. | |
13013 | * fwd-para let:: The @code{let*} expression. | |
13014 | * fwd-para while:: The forward motion @code{while} loop. | |
13015 | @end menu | |
13016 | ||
8cda6f8f | 13017 | @ifnottex |
d6adf7e7 | 13018 | @node forward-paragraph in brief |
8cda6f8f GM |
13019 | @unnumberedsubsec Shortened @code{forward-paragraph} function definition |
13020 | @end ifnottex | |
13021 | ||
13022 | Rather than print all of the @code{forward-paragraph} function, we | |
13023 | will only print parts of it. Read without preparation, the function | |
13024 | can be daunting! | |
13025 | ||
13026 | @need 800 | |
13027 | In outline, the function looks like this: | |
13028 | ||
13029 | @smallexample | |
13030 | @group | |
13031 | (defun forward-paragraph (&optional arg) | |
13032 | "@var{documentation}@dots{}" | |
13033 | (interactive "p") | |
13034 | (or arg (setq arg 1)) | |
13035 | (let* | |
13036 | @var{varlist} | |
13037 | (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code} | |
13038 | @dots{} | |
13039 | (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code} | |
13040 | @dots{} | |
13041 | @end group | |
13042 | @end smallexample | |
13043 | ||
13044 | The first parts of the function are routine: the function's argument | |
13045 | list consists of one optional argument. Documentation follows. | |
13046 | ||
13047 | The lower case @samp{p} in the @code{interactive} declaration means | |
13048 | that the processed prefix argument, if any, is passed to the function. | |
13049 | This will be a number, and is the repeat count of how many paragraphs | |
13050 | point will move. The @code{or} expression in the next line handles | |
13051 | the common case when no argument is passed to the function, which occurs | |
13052 | if the function is called from other code rather than interactively. | |
13053 | This case was described earlier. (@xref{forward-sentence, The | |
13054 | @code{forward-sentence} function}.) Now we reach the end of the | |
13055 | familiar part of this function. | |
13056 | ||
d6adf7e7 | 13057 | @node fwd-para let |
8cda6f8f GM |
13058 | @unnumberedsubsec The @code{let*} expression |
13059 | ||
13060 | The next line of the @code{forward-paragraph} function begins a | |
13061 | @code{let*} expression. This is a different than @code{let}. The | |
13062 | symbol is @code{let*} not @code{let}. | |
13063 | ||
13064 | The @code{let*} special form is like @code{let} except that Emacs sets | |
13065 | each variable in sequence, one after another, and variables in the | |
13066 | latter part of the varlist can make use of the values to which Emacs | |
13067 | set variables in the earlier part of the varlist. | |
13068 | ||
13069 | @ignore | |
13070 | ( refappend save-excursion, , code save-excursion in code append-to-buffer .) | |
13071 | @end ignore | |
13072 | ||
13073 | (@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.) | |
13074 | ||
13075 | In the @code{let*} expression in this function, Emacs binds a total of | |
13076 | seven variables: @code{opoint}, @code{fill-prefix-regexp}, | |
13077 | @code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and | |
13078 | @code{found-start}. | |
13079 | ||
13080 | The variable @code{parsep} appears twice, first, to remove instances | |
13081 | of @samp{^}, and second, to handle fill prefixes. | |
13082 | ||
13083 | The variable @code{opoint} is just the value of @code{point}. As you | |
13084 | can guess, it is used in a @code{constrain-to-field} expression, just | |
13085 | as in @code{forward-sentence}. | |
13086 | ||
13087 | The variable @code{fill-prefix-regexp} is set to the value returned by | |
13088 | evaluating the following list: | |
13089 | ||
13090 | @smallexample | |
13091 | @group | |
13092 | (and fill-prefix | |
13093 | (not (equal fill-prefix "")) | |
13094 | (not paragraph-ignore-fill-prefix) | |
13095 | (regexp-quote fill-prefix)) | |
13096 | @end group | |
13097 | @end smallexample | |
13098 | ||
13099 | @noindent | |
13100 | This is an expression whose first element is the @code{and} special form. | |
13101 | ||
13102 | As we learned earlier (@pxref{kill-new function, , The @code{kill-new} | |
13103 | function}), the @code{and} special form evaluates each of its | |
13104 | arguments until one of the arguments returns a value of @code{nil}, in | |
13105 | which case the @code{and} expression returns @code{nil}; however, if | |
13106 | none of the arguments returns a value of @code{nil}, the value | |
13107 | resulting from evaluating the last argument is returned. (Since such | |
13108 | a value is not @code{nil}, it is considered true in Lisp.) In other | |
13109 | words, an @code{and} expression returns a true value only if all its | |
13110 | arguments are true. | |
13111 | @findex and | |
13112 | ||
13113 | In this case, the variable @code{fill-prefix-regexp} is bound to a | |
13114 | non-@code{nil} value only if the following four expressions produce a | |
13115 | true (i.e., a non-@code{nil}) value when they are evaluated; otherwise, | |
13116 | @code{fill-prefix-regexp} is bound to @code{nil}. | |
13117 | ||
13118 | @table @code | |
13119 | @item fill-prefix | |
13120 | When this variable is evaluated, the value of the fill prefix, if any, | |
13121 | is returned. If there is no fill prefix, this variable returns | |
13122 | @code{nil}. | |
13123 | ||
13124 | @item (not (equal fill-prefix "") | |
13125 | This expression checks whether an existing fill prefix is an empty | |
13126 | string, that is, a string with no characters in it. An empty string is | |
13127 | not a useful fill prefix. | |
13128 | ||
13129 | @item (not paragraph-ignore-fill-prefix) | |
13130 | This expression returns @code{nil} if the variable | |
13131 | @code{paragraph-ignore-fill-prefix} has been turned on by being set to a | |
13132 | true value such as @code{t}. | |
13133 | ||
13134 | @item (regexp-quote fill-prefix) | |
13135 | This is the last argument to the @code{and} special form. If all the | |
13136 | arguments to the @code{and} are true, the value resulting from | |
13137 | evaluating this expression will be returned by the @code{and} expression | |
13138 | and bound to the variable @code{fill-prefix-regexp}, | |
13139 | @end table | |
13140 | ||
13141 | @findex regexp-quote | |
13142 | @noindent | |
13143 | The result of evaluating this @code{and} expression successfully is that | |
13144 | @code{fill-prefix-regexp} will be bound to the value of | |
13145 | @code{fill-prefix} as modified by the @code{regexp-quote} function. | |
13146 | What @code{regexp-quote} does is read a string and return a regular | |
13147 | expression that will exactly match the string and match nothing else. | |
13148 | This means that @code{fill-prefix-regexp} will be set to a value that | |
13149 | will exactly match the fill prefix if the fill prefix exists. | |
13150 | Otherwise, the variable will be set to @code{nil}. | |
13151 | ||
13152 | The next two local variables in the @code{let*} expression are | |
13153 | designed to remove instances of @samp{^} from @code{parstart} and | |
13154 | @code{parsep}, the local variables which indicate the paragraph start | |
13155 | and the paragraph separator. The next expression sets @code{parsep} | |
13156 | again. That is to handle fill prefixes. | |
13157 | ||
13158 | This is the setting that requires the definition call @code{let*} | |
13159 | rather than @code{let}. The true-or-false-test for the @code{if} | |
13160 | depends on whether the variable @code{fill-prefix-regexp} evaluates to | |
13161 | @code{nil} or some other value. | |
13162 | ||
13163 | If @code{fill-prefix-regexp} does not have a value, Emacs evaluates | |
13164 | the else-part of the @code{if} expression and binds @code{parsep} to | |
13165 | its local value. (@code{parsep} is a regular expression that matches | |
13166 | what separates paragraphs.) | |
13167 | ||
13168 | But if @code{fill-prefix-regexp} does have a value, Emacs evaluates | |
13169 | the then-part of the @code{if} expression and binds @code{parsep} to a | |
13170 | regular expression that includes the @code{fill-prefix-regexp} as part | |
13171 | of the pattern. | |
13172 | ||
13173 | Specifically, @code{parsep} is set to the original value of the | |
13174 | paragraph separate regular expression concatenated with an alternative | |
13175 | expression that consists of the @code{fill-prefix-regexp} followed by | |
13176 | optional whitespace to the end of the line. The whitespace is defined | |
13177 | by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the | |
13178 | regexp as an alternative to @code{parsep}. | |
13179 | ||
13180 | According to a comment in the code, the next local variable, | |
13181 | @code{sp-parstart}, is used for searching, and then the final two, | |
13182 | @code{start} and @code{found-start}, are set to @code{nil}. | |
13183 | ||
13184 | Now we get into the body of the @code{let*}. The first part of the body | |
13185 | of the @code{let*} deals with the case when the function is given a | |
13186 | negative argument and is therefore moving backwards. We will skip this | |
13187 | section. | |
13188 | ||
d6adf7e7 | 13189 | @node fwd-para while |
8cda6f8f GM |
13190 | @unnumberedsubsec The forward motion @code{while} loop |
13191 | ||
13192 | The second part of the body of the @code{let*} deals with forward | |
13193 | motion. It is a @code{while} loop that repeats itself so long as the | |
13194 | value of @code{arg} is greater than zero. In the most common use of | |
13195 | the function, the value of the argument is 1, so the body of the | |
13196 | @code{while} loop is evaluated exactly once, and the cursor moves | |
13197 | forward one paragraph. | |
13198 | ||
13199 | @ignore | |
13200 | (while (and (> arg 0) (not (eobp))) | |
13201 | ||
13202 | ;; Move forward over separator lines... | |
13203 | (while (and (not (eobp)) | |
13204 | (progn (move-to-left-margin) (not (eobp))) | |
13205 | (looking-at parsep)) | |
13206 | (forward-line 1)) | |
13207 | (unless (eobp) (setq arg (1- arg))) | |
13208 | ;; ... and one more line. | |
13209 | (forward-line 1) | |
13210 | ||
13211 | (if fill-prefix-regexp | |
13212 | ;; There is a fill prefix; it overrides parstart. | |
13213 | (while (and (not (eobp)) | |
13214 | (progn (move-to-left-margin) (not (eobp))) | |
13215 | (not (looking-at parsep)) | |
13216 | (looking-at fill-prefix-regexp)) | |
13217 | (forward-line 1)) | |
13218 | ||
13219 | (while (and (re-search-forward sp-parstart nil 1) | |
13220 | (progn (setq start (match-beginning 0)) | |
13221 | (goto-char start) | |
13222 | (not (eobp))) | |
13223 | (progn (move-to-left-margin) | |
13224 | (not (looking-at parsep))) | |
13225 | (or (not (looking-at parstart)) | |
13226 | (and use-hard-newlines | |
13227 | (not (get-text-property (1- start) 'hard))))) | |
13228 | (forward-char 1)) | |
13229 | ||
13230 | (if (< (point) (point-max)) | |
13231 | (goto-char start)))) | |
13232 | @end ignore | |
13233 | ||
13234 | This part handles three situations: when point is between paragraphs, | |
13235 | when there is a fill prefix and when there is no fill prefix. | |
13236 | ||
13237 | @need 800 | |
13238 | The @code{while} loop looks like this: | |
13239 | ||
13240 | @smallexample | |
13241 | @group | |
13242 | ;; @r{going forwards and not at the end of the buffer} | |
13243 | (while (and (> arg 0) (not (eobp))) | |
13244 | ||
13245 | ;; @r{between paragraphs} | |
13246 | ;; Move forward over separator lines... | |
13247 | (while (and (not (eobp)) | |
13248 | (progn (move-to-left-margin) (not (eobp))) | |
13249 | (looking-at parsep)) | |
13250 | (forward-line 1)) | |
13251 | ;; @r{This decrements the loop} | |
13252 | (unless (eobp) (setq arg (1- arg))) | |
13253 | ;; ... and one more line. | |
13254 | (forward-line 1) | |
13255 | @end group | |
13256 | ||
13257 | @group | |
13258 | (if fill-prefix-regexp | |
13259 | ;; There is a fill prefix; it overrides parstart; | |
13260 | ;; we go forward line by line | |
13261 | (while (and (not (eobp)) | |
13262 | (progn (move-to-left-margin) (not (eobp))) | |
13263 | (not (looking-at parsep)) | |
13264 | (looking-at fill-prefix-regexp)) | |
13265 | (forward-line 1)) | |
13266 | @end group | |
13267 | ||
13268 | @group | |
13269 | ;; There is no fill prefix; | |
13270 | ;; we go forward character by character | |
13271 | (while (and (re-search-forward sp-parstart nil 1) | |
13272 | (progn (setq start (match-beginning 0)) | |
13273 | (goto-char start) | |
13274 | (not (eobp))) | |
13275 | (progn (move-to-left-margin) | |
13276 | (not (looking-at parsep))) | |
13277 | (or (not (looking-at parstart)) | |
13278 | (and use-hard-newlines | |
13279 | (not (get-text-property (1- start) 'hard))))) | |
13280 | (forward-char 1)) | |
13281 | @end group | |
13282 | ||
13283 | @group | |
13284 | ;; and if there is no fill prefix and if we are not at the end, | |
13285 | ;; go to whatever was found in the regular expression search | |
13286 | ;; for sp-parstart | |
13287 | (if (< (point) (point-max)) | |
13288 | (goto-char start)))) | |
13289 | @end group | |
13290 | @end smallexample | |
13291 | ||
13292 | @findex eobp | |
13293 | We can see that this is a decrementing counter @code{while} loop, | |
13294 | using the expression @code{(setq arg (1- arg))} as the decrementer. | |
13295 | That expression is not far from the @code{while}, but is hidden in | |
13296 | another Lisp macro, an @code{unless} macro. Unless we are at the end | |
f99f1641 PE |
13297 | of the buffer---that is what the @code{eobp} function determines; it |
13298 | is an abbreviation of @samp{End Of Buffer P}---we decrease the value | |
8cda6f8f GM |
13299 | of @code{arg} by one. |
13300 | ||
13301 | (If we are at the end of the buffer, we cannot go forward any more and | |
13302 | the next loop of the @code{while} expression will test false since the | |
13303 | test is an @code{and} with @code{(not (eobp))}. The @code{not} | |
13304 | function means exactly as you expect; it is another name for | |
13305 | @code{null}, a function that returns true when its argument is false.) | |
13306 | ||
13307 | Interestingly, the loop count is not decremented until we leave the | |
13308 | space between paragraphs, unless we come to the end of buffer or stop | |
13309 | seeing the local value of the paragraph separator. | |
13310 | ||
13311 | That second @code{while} also has a @code{(move-to-left-margin)} | |
13312 | expression. The function is self-explanatory. It is inside a | |
13313 | @code{progn} expression and not the last element of its body, so it is | |
13314 | only invoked for its side effect, which is to move point to the left | |
13315 | margin of the current line. | |
13316 | ||
13317 | @findex looking-at | |
13318 | The @code{looking-at} function is also self-explanatory; it returns | |
13319 | true if the text after point matches the regular expression given as | |
13320 | its argument. | |
13321 | ||
13322 | The rest of the body of the loop looks difficult at first, but makes | |
13323 | sense as you come to understand it. | |
13324 | ||
13325 | @need 800 | |
13326 | First consider what happens if there is a fill prefix: | |
13327 | ||
13328 | @smallexample | |
13329 | @group | |
13330 | (if fill-prefix-regexp | |
13331 | ;; There is a fill prefix; it overrides parstart; | |
13332 | ;; we go forward line by line | |
13333 | (while (and (not (eobp)) | |
13334 | (progn (move-to-left-margin) (not (eobp))) | |
13335 | (not (looking-at parsep)) | |
13336 | (looking-at fill-prefix-regexp)) | |
13337 | (forward-line 1)) | |
13338 | @end group | |
13339 | @end smallexample | |
13340 | ||
13341 | @noindent | |
13342 | This expression moves point forward line by line so long | |
13343 | as four conditions are true: | |
13344 | ||
13345 | @enumerate | |
13346 | @item | |
13347 | Point is not at the end of the buffer. | |
13348 | ||
13349 | @item | |
13350 | We can move to the left margin of the text and are | |
13351 | not at the end of the buffer. | |
13352 | ||
13353 | @item | |
13354 | The text following point does not separate paragraphs. | |
13355 | ||
13356 | @item | |
13357 | The pattern following point is the fill prefix regular expression. | |
13358 | @end enumerate | |
13359 | ||
13360 | The last condition may be puzzling, until you remember that point was | |
13361 | moved to the beginning of the line early in the @code{forward-paragraph} | |
13362 | function. This means that if the text has a fill prefix, the | |
13363 | @code{looking-at} function will see it. | |
13364 | ||
13365 | @need 1250 | |
13366 | Consider what happens when there is no fill prefix. | |
13367 | ||
13368 | @smallexample | |
13369 | @group | |
13370 | (while (and (re-search-forward sp-parstart nil 1) | |
13371 | (progn (setq start (match-beginning 0)) | |
13372 | (goto-char start) | |
13373 | (not (eobp))) | |
13374 | (progn (move-to-left-margin) | |
13375 | (not (looking-at parsep))) | |
13376 | (or (not (looking-at parstart)) | |
13377 | (and use-hard-newlines | |
13378 | (not (get-text-property (1- start) 'hard))))) | |
13379 | (forward-char 1)) | |
13380 | @end group | |
13381 | @end smallexample | |
13382 | ||
13383 | @noindent | |
13384 | This @code{while} loop has us searching forward for | |
13385 | @code{sp-parstart}, which is the combination of possible whitespace | |
13386 | with a the local value of the start of a paragraph or of a paragraph | |
13387 | separator. (The latter two are within an expression starting | |
13388 | @code{\(?:} so that they are not referenced by the | |
13389 | @code{match-beginning} function.) | |
13390 | ||
13391 | @need 800 | |
13392 | The two expressions, | |
13393 | ||
13394 | @smallexample | |
13395 | @group | |
13396 | (setq start (match-beginning 0)) | |
13397 | (goto-char start) | |
13398 | @end group | |
13399 | @end smallexample | |
13400 | ||
13401 | @noindent | |
13402 | mean go to the start of the text matched by the regular expression | |
13403 | search. | |
13404 | ||
13405 | The @code{(match-beginning 0)} expression is new. It returns a number | |
13406 | specifying the location of the start of the text that was matched by | |
13407 | the last search. | |
13408 | ||
13409 | The @code{match-beginning} function is used here because of a | |
13410 | characteristic of a forward search: a successful forward search, | |
13411 | regardless of whether it is a plain search or a regular expression | |
13412 | search, moves point to the end of the text that is found. In this | |
13413 | case, a successful search moves point to the end of the pattern for | |
13414 | @code{sp-parstart}. | |
13415 | ||
13416 | However, we want to put point at the end of the current paragraph, not | |
13417 | somewhere else. Indeed, since the search possibly includes the | |
13418 | paragraph separator, point may end up at the beginning of the next one | |
13419 | unless we use an expression that includes @code{match-beginning}. | |
13420 | ||
13421 | @findex match-beginning | |
13422 | When given an argument of 0, @code{match-beginning} returns the | |
13423 | position that is the start of the text matched by the most recent | |
13424 | search. In this case, the most recent search looks for | |
13425 | @code{sp-parstart}. The @code{(match-beginning 0)} expression returns | |
13426 | the beginning position of that pattern, rather than the end position | |
13427 | of that pattern. | |
13428 | ||
13429 | (Incidentally, when passed a positive number as an argument, the | |
13430 | @code{match-beginning} function returns the location of point at that | |
13431 | parenthesized expression in the last search unless that parenthesized | |
13432 | expression begins with @code{\(?:}. I don't know why @code{\(?:} | |
13433 | appears here since the argument is 0.) | |
13434 | ||
13435 | @need 1250 | |
13436 | The last expression when there is no fill prefix is | |
13437 | ||
13438 | @smallexample | |
13439 | @group | |
13440 | (if (< (point) (point-max)) | |
13441 | (goto-char start)))) | |
13442 | @end group | |
13443 | @end smallexample | |
13444 | ||
13445 | @noindent | |
13446 | This says that if there is no fill prefix and if we are not at the | |
13447 | end, point should move to the beginning of whatever was found by the | |
13448 | regular expression search for @code{sp-parstart}. | |
13449 | ||
13450 | The full definition for the @code{forward-paragraph} function not only | |
13451 | includes code for going forwards, but also code for going backwards. | |
13452 | ||
13453 | If you are reading this inside of GNU Emacs and you want to see the | |
13454 | whole function, you can type @kbd{C-h f} (@code{describe-function}) | |
13455 | and the name of the function. This gives you the function | |
13456 | documentation and the name of the library containing the function's | |
13457 | source. Place point over the name of the library and press the RET | |
13458 | key; you will be taken directly to the source. (Be sure to install | |
13459 | your sources! Without them, you are like a person who tries to drive | |
13460 | a car with his eyes shut!) | |
13461 | ||
d6adf7e7 | 13462 | @node etags |
8cda6f8f GM |
13463 | @section Create Your Own @file{TAGS} File |
13464 | @findex etags | |
13465 | @cindex @file{TAGS} file, create own | |
13466 | ||
13467 | Besides @kbd{C-h f} (@code{describe-function}), another way to see the | |
13468 | source of a function is to type @kbd{M-.} (@code{find-tag}) and the | |
13469 | name of the function when prompted for it. This is a good habit to | |
13470 | get into. The @kbd{M-.} (@code{find-tag}) command takes you directly | |
13471 | to the source for a function, variable, or node. The function depends | |
13472 | on tags tables to tell it where to go. | |
13473 | ||
13474 | If the @code{find-tag} function first asks you for the name of a | |
13475 | @file{TAGS} table, give it the name of a @file{TAGS} file such as | |
13476 | @file{/usr/local/src/emacs/src/TAGS}. (The exact path to your | |
13477 | @file{TAGS} file depends on how your copy of Emacs was installed. I | |
13478 | just told you the location that provides both my C and my Emacs Lisp | |
13479 | sources.) | |
13480 | ||
13481 | You can also create your own @file{TAGS} file for directories that | |
13482 | lack one. | |
13483 | ||
13484 | You often need to build and install tags tables yourself. They are | |
13485 | not built automatically. A tags table is called a @file{TAGS} file; | |
13486 | the name is in upper case letters. | |
13487 | ||
13488 | You can create a @file{TAGS} file by calling the @code{etags} program | |
13489 | that comes as a part of the Emacs distribution. Usually, @code{etags} | |
13490 | is compiled and installed when Emacs is built. (@code{etags} is not | |
13491 | an Emacs Lisp function or a part of Emacs; it is a C program.) | |
13492 | ||
13493 | @need 1250 | |
13494 | To create a @file{TAGS} file, first switch to the directory in which | |
13495 | you want to create the file. In Emacs you can do this with the | |
13496 | @kbd{M-x cd} command, or by visiting a file in the directory, or by | |
13497 | listing the directory with @kbd{C-x d} (@code{dired}). Then run the | |
13498 | compile command, with @w{@code{etags *.el}} as the command to execute | |
13499 | ||
13500 | @smallexample | |
13501 | M-x compile RET etags *.el RET | |
13502 | @end smallexample | |
13503 | ||
13504 | @noindent | |
13505 | to create a @file{TAGS} file for Emacs Lisp. | |
13506 | ||
13507 | For example, if you have a large number of files in your | |
13508 | @file{~/emacs} directory, as I do---I have 137 @file{.el} files in it, | |
13509 | of which I load 12---you can create a @file{TAGS} file for the Emacs | |
13510 | Lisp files in that directory. | |
13511 | ||
13512 | @need 1250 | |
13513 | The @code{etags} program takes all the usual shell `wildcards'. For | |
13514 | example, if you have two directories for which you want a single | |
13515 | @file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where | |
13516 | @file{../elisp/} is the second directory: | |
13517 | ||
13518 | @smallexample | |
13519 | M-x compile RET etags *.el ../elisp/*.el RET | |
13520 | @end smallexample | |
13521 | ||
13522 | @need 1250 | |
13523 | Type | |
13524 | ||
13525 | @smallexample | |
13526 | M-x compile RET etags --help RET | |
13527 | @end smallexample | |
13528 | ||
13529 | @noindent | |
13530 | to see a list of the options accepted by @code{etags} as well as a | |
13531 | list of supported languages. | |
13532 | ||
13533 | The @code{etags} program handles more than 20 languages, including | |
13534 | Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java, | |
7877f373 | 13535 | LaTeX, Pascal, Perl, PostScript, Python, TeX, Texinfo, makefiles, and |
8cda6f8f GM |
13536 | most assemblers. The program has no switches for specifying the |
13537 | language; it recognizes the language in an input file according to its | |
13538 | file name and contents. | |
13539 | ||
13540 | @file{etags} is very helpful when you are writing code yourself and | |
13541 | want to refer back to functions you have already written. Just run | |
13542 | @code{etags} again at intervals as you write new functions, so they | |
13543 | become part of the @file{TAGS} file. | |
13544 | ||
13545 | If you think an appropriate @file{TAGS} file already exists for what | |
13546 | you want, but do not know where it is, you can use the @code{locate} | |
13547 | program to attempt to find it. | |
13548 | ||
13549 | Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list | |
13550 | for you the full path names of all your @file{TAGS} files. On my | |
13551 | system, this command lists 34 @file{TAGS} files. On the other hand, a | |
13552 | `plain vanilla' system I recently installed did not contain any | |
13553 | @file{TAGS} files. | |
13554 | ||
13555 | If the tags table you want has been created, you can use the @code{M-x | |
13556 | visit-tags-table} command to specify it. Otherwise, you will need to | |
13557 | create the tag table yourself and then use @code{M-x | |
13558 | visit-tags-table}. | |
13559 | ||
13560 | @subsubheading Building Tags in the Emacs sources | |
13561 | @cindex Building Tags in the Emacs sources | |
13562 | @cindex Tags in the Emacs sources | |
13563 | @findex make tags | |
13564 | ||
13565 | The GNU Emacs sources come with a @file{Makefile} that contains a | |
13566 | sophisticated @code{etags} command that creates, collects, and merges | |
13567 | tags tables from all over the Emacs sources and puts the information | |
13568 | into one @file{TAGS} file in the @file{src/} directory. (The | |
13569 | @file{src/} directory is below the top level of your Emacs directory.) | |
13570 | ||
13571 | @need 1250 | |
13572 | To build this @file{TAGS} file, go to the top level of your Emacs | |
13573 | source directory and run the compile command @code{make tags}: | |
13574 | ||
13575 | @smallexample | |
13576 | M-x compile RET make tags RET | |
13577 | @end smallexample | |
13578 | ||
13579 | @noindent | |
13580 | (The @code{make tags} command works well with the GNU Emacs sources, | |
13581 | as well as with some other source packages.) | |
13582 | ||
13583 | For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs | |
13584 | Manual}. | |
13585 | ||
d6adf7e7 | 13586 | @node Regexp Review |
8cda6f8f GM |
13587 | @section Review |
13588 | ||
13589 | Here is a brief summary of some recently introduced functions. | |
13590 | ||
13591 | @table @code | |
13592 | @item while | |
13593 | Repeatedly evaluate the body of the expression so long as the first | |
13594 | element of the body tests true. Then return @code{nil}. (The | |
13595 | expression is evaluated only for its side effects.) | |
13596 | ||
13597 | @need 1250 | |
13598 | For example: | |
13599 | ||
13600 | @smallexample | |
13601 | @group | |
13602 | (let ((foo 2)) | |
13603 | (while (> foo 0) | |
13604 | (insert (format "foo is %d.\n" foo)) | |
13605 | (setq foo (1- foo)))) | |
13606 | ||
13607 | @result{} foo is 2. | |
13608 | foo is 1. | |
13609 | nil | |
13610 | @end group | |
13611 | @end smallexample | |
13612 | ||
13613 | @noindent | |
13614 | (The @code{insert} function inserts its arguments at point; the | |
13615 | @code{format} function returns a string formatted from its arguments | |
13616 | the way @code{message} formats its arguments; @code{\n} produces a new | |
13617 | line.) | |
13618 | ||
13619 | @item re-search-forward | |
13620 | Search for a pattern, and if the pattern is found, move point to rest | |
13621 | just after it. | |
13622 | ||
13623 | @noindent | |
13624 | Takes four arguments, like @code{search-forward}: | |
13625 | ||
13626 | @enumerate | |
13627 | @item | |
13628 | A regular expression that specifies the pattern to search for. | |
13629 | (Remember to put quotation marks around this argument!) | |
13630 | ||
13631 | @item | |
13632 | Optionally, the limit of the search. | |
13633 | ||
13634 | @item | |
13635 | Optionally, what to do if the search fails, return @code{nil} or an | |
13636 | error message. | |
13637 | ||
13638 | @item | |
13639 | Optionally, how many times to repeat the search; if negative, the | |
13640 | search goes backwards. | |
13641 | @end enumerate | |
13642 | ||
13643 | @item let* | |
13644 | Bind some variables locally to particular values, | |
13645 | and then evaluate the remaining arguments, returning the value of the | |
13646 | last one. While binding the local variables, use the local values of | |
13647 | variables bound earlier, if any. | |
13648 | ||
13649 | @need 1250 | |
13650 | For example: | |
13651 | ||
13652 | @smallexample | |
13653 | @group | |
13654 | (let* ((foo 7) | |
13655 | (bar (* 3 foo))) | |
13656 | (message "`bar' is %d." bar)) | |
13657 | @result{} `bar' is 21. | |
13658 | @end group | |
13659 | @end smallexample | |
13660 | ||
13661 | @item match-beginning | |
13662 | Return the position of the start of the text found by the last regular | |
13663 | expression search. | |
13664 | ||
13665 | @item looking-at | |
13666 | Return @code{t} for true if the text after point matches the argument, | |
13667 | which should be a regular expression. | |
13668 | ||
13669 | @item eobp | |
13670 | Return @code{t} for true if point is at the end of the accessible part | |
13671 | of a buffer. The end of the accessible part is the end of the buffer | |
13672 | if the buffer is not narrowed; it is the end of the narrowed part if | |
13673 | the buffer is narrowed. | |
13674 | @end table | |
13675 | ||
13676 | @need 1500 | |
d6adf7e7 | 13677 | @node re-search Exercises |
8cda6f8f GM |
13678 | @section Exercises with @code{re-search-forward} |
13679 | ||
13680 | @itemize @bullet | |
13681 | @item | |
13682 | Write a function to search for a regular expression that matches two | |
13683 | or more blank lines in sequence. | |
13684 | ||
13685 | @item | |
13686 | Write a function to search for duplicated words, such as `the the'. | |
13687 | @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs | |
13688 | Manual}, for information on how to write a regexp (a regular | |
13689 | expression) to match a string that is composed of two identical | |
13690 | halves. You can devise several regexps; some are better than others. | |
13691 | The function I use is described in an appendix, along with several | |
13692 | regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}. | |
13693 | @end itemize | |
13694 | ||
d6adf7e7 | 13695 | @node Counting Words |
8cda6f8f GM |
13696 | @chapter Counting: Repetition and Regexps |
13697 | @cindex Repetition for word counting | |
13698 | @cindex Regular expressions for word counting | |
13699 | ||
13700 | Repetition and regular expression searches are powerful tools that you | |
13701 | often use when you write code in Emacs Lisp. This chapter illustrates | |
13702 | the use of regular expression searches through the construction of | |
13703 | word count commands using @code{while} loops and recursion. | |
13704 | ||
13705 | @menu | |
13706 | * Why Count Words:: | |
ea4f7750 | 13707 | * @value{COUNT-WORDS}:: Use a regexp, but find a problem. |
8cda6f8f GM |
13708 | * recursive-count-words:: Start with case of no words in region. |
13709 | * Counting Exercise:: | |
13710 | @end menu | |
13711 | ||
8cda6f8f | 13712 | @ifnottex |
d6adf7e7 | 13713 | @node Why Count Words |
8cda6f8f GM |
13714 | @unnumberedsec Counting words |
13715 | @end ifnottex | |
13716 | ||
ea4f7750 GM |
13717 | The standard Emacs distribution contains functions for counting the |
13718 | number of lines and words within a region. | |
8cda6f8f GM |
13719 | |
13720 | Certain types of writing ask you to count words. Thus, if you write | |
13721 | an essay, you may be limited to 800 words; if you write a novel, you | |
ea4f7750 GM |
13722 | may discipline yourself to write 1000 words a day. It seems odd, but |
13723 | for a long time, Emacs lacked a word count command. Perhaps people used | |
13724 | Emacs mostly for code or types of documentation that did not require | |
13725 | word counts; or perhaps they restricted themselves to the operating | |
13726 | system word count command, @code{wc}. Alternatively, people may have | |
13727 | followed the publishers' convention and computed a word count by | |
13728 | dividing the number of characters in a document by five. | |
13729 | ||
13730 | There are many ways to implement a command to count words. Here are | |
13731 | some examples, which you may wish to compare with the standard Emacs | |
13732 | command, @code{count-words-region}. | |
13733 | ||
d6adf7e7 | 13734 | @node @value{COUNT-WORDS} |
ea4f7750 GM |
13735 | @section The @code{@value{COUNT-WORDS}} Function |
13736 | @findex @value{COUNT-WORDS} | |
8cda6f8f GM |
13737 | |
13738 | A word count command could count words in a line, paragraph, region, | |
13739 | or buffer. What should the command cover? You could design the | |
13740 | command to count the number of words in a complete buffer. However, | |
13741 | the Emacs tradition encourages flexibility---you may want to count | |
13742 | words in just a section, rather than all of a buffer. So it makes | |
13743 | more sense to design the command to count the number of words in a | |
ea4f7750 | 13744 | region. Once you have a command to count words in a region, you can, |
8cda6f8f GM |
13745 | if you wish, count words in a whole buffer by marking it with |
13746 | @w{@kbd{C-x h}} (@code{mark-whole-buffer}). | |
13747 | ||
13748 | Clearly, counting words is a repetitive act: starting from the | |
13749 | beginning of the region, you count the first word, then the second | |
13750 | word, then the third word, and so on, until you reach the end of the | |
13751 | region. This means that word counting is ideally suited to recursion | |
13752 | or to a @code{while} loop. | |
13753 | ||
13754 | @menu | |
ea4f7750 GM |
13755 | * Design @value{COUNT-WORDS}:: The definition using a @code{while} loop. |
13756 | * Whitespace Bug:: The Whitespace Bug in @code{@value{COUNT-WORDS}}. | |
8cda6f8f GM |
13757 | @end menu |
13758 | ||
8cda6f8f | 13759 | @ifnottex |
d6adf7e7 | 13760 | @node Design @value{COUNT-WORDS} |
ea4f7750 | 13761 | @unnumberedsubsec Designing @code{@value{COUNT-WORDS}} |
8cda6f8f GM |
13762 | @end ifnottex |
13763 | ||
13764 | First, we will implement the word count command with a @code{while} | |
13765 | loop, then with recursion. The command will, of course, be | |
13766 | interactive. | |
13767 | ||
13768 | @need 800 | |
13769 | The template for an interactive function definition is, as always: | |
13770 | ||
13771 | @smallexample | |
13772 | @group | |
13773 | (defun @var{name-of-function} (@var{argument-list}) | |
13774 | "@var{documentation}@dots{}" | |
13775 | (@var{interactive-expression}@dots{}) | |
13776 | @var{body}@dots{}) | |
13777 | @end group | |
13778 | @end smallexample | |
13779 | ||
13780 | What we need to do is fill in the slots. | |
13781 | ||
13782 | The name of the function should be self-explanatory and similar to the | |
13783 | existing @code{count-lines-region} name. This makes the name easier | |
ea4f7750 GM |
13784 | to remember. @code{count-words-region} is the obvious choice. Since |
13785 | that name is now used for the standard Emacs command to count words, we | |
13786 | will name our implementation @code{@value{COUNT-WORDS}}. | |
8cda6f8f GM |
13787 | |
13788 | The function counts words within a region. This means that the | |
13789 | argument list must contain symbols that are bound to the two | |
13790 | positions, the beginning and end of the region. These two positions | |
13791 | can be called @samp{beginning} and @samp{end} respectively. The first | |
13792 | line of the documentation should be a single sentence, since that is | |
13793 | all that is printed as documentation by a command such as | |
13794 | @code{apropos}. The interactive expression will be of the form | |
13795 | @samp{(interactive "r")}, since that will cause Emacs to pass the | |
13796 | beginning and end of the region to the function's argument list. All | |
13797 | this is routine. | |
13798 | ||
13799 | The body of the function needs to be written to do three tasks: | |
13800 | first, to set up conditions under which the @code{while} loop can | |
13801 | count words, second, to run the @code{while} loop, and third, to send | |
13802 | a message to the user. | |
13803 | ||
ea4f7750 | 13804 | When a user calls @code{@value{COUNT-WORDS}}, point may be at the |
8cda6f8f GM |
13805 | beginning or the end of the region. However, the counting process |
13806 | must start at the beginning of the region. This means we will want | |
13807 | to put point there if it is not already there. Executing | |
13808 | @code{(goto-char beginning)} ensures this. Of course, we will want to | |
13809 | return point to its expected position when the function finishes its | |
13810 | work. For this reason, the body must be enclosed in a | |
13811 | @code{save-excursion} expression. | |
13812 | ||
13813 | The central part of the body of the function consists of a | |
13814 | @code{while} loop in which one expression jumps point forward word by | |
13815 | word, and another expression counts those jumps. The true-or-false-test | |
13816 | of the @code{while} loop should test true so long as point should jump | |
13817 | forward, and false when point is at the end of the region. | |
13818 | ||
13819 | We could use @code{(forward-word 1)} as the expression for moving point | |
13820 | forward word by word, but it is easier to see what Emacs identifies as a | |
13821 | `word' if we use a regular expression search. | |
13822 | ||
13823 | A regular expression search that finds the pattern for which it is | |
13824 | searching leaves point after the last character matched. This means | |
13825 | that a succession of successful word searches will move point forward | |
13826 | word by word. | |
13827 | ||
13828 | As a practical matter, we want the regular expression search to jump | |
13829 | over whitespace and punctuation between words as well as over the | |
13830 | words themselves. A regexp that refuses to jump over interword | |
13831 | whitespace would never jump more than one word! This means that | |
13832 | the regexp should include the whitespace and punctuation that follows | |
13833 | a word, if any, as well as the word itself. (A word may end a buffer | |
13834 | and not have any following whitespace or punctuation, so that part of | |
13835 | the regexp must be optional.) | |
13836 | ||
13837 | Thus, what we want for the regexp is a pattern defining one or more | |
13838 | word constituent characters followed, optionally, by one or more | |
13839 | characters that are not word constituents. The regular expression for | |
13840 | this is: | |
13841 | ||
13842 | @smallexample | |
13843 | \w+\W* | |
13844 | @end smallexample | |
13845 | ||
13846 | @noindent | |
13847 | The buffer's syntax table determines which characters are and are not | |
0fd2c9a3 GM |
13848 | word constituents. For more information about syntax, |
13849 | @pxref{Syntax Tables, , Syntax Tables, elisp, The GNU Emacs Lisp | |
13850 | Reference Manual}. | |
8cda6f8f GM |
13851 | |
13852 | @need 800 | |
13853 | The search expression looks like this: | |
13854 | ||
13855 | @smallexample | |
13856 | (re-search-forward "\\w+\\W*") | |
13857 | @end smallexample | |
13858 | ||
13859 | @noindent | |
13860 | (Note that paired backslashes precede the @samp{w} and @samp{W}. A | |
13861 | single backslash has special meaning to the Emacs Lisp interpreter. | |
13862 | It indicates that the following character is interpreted differently | |
13863 | than usual. For example, the two characters, @samp{\n}, stand for | |
13864 | @samp{newline}, rather than for a backslash followed by @samp{n}. Two | |
13865 | backslashes in a row stand for an ordinary, `unspecial' backslash, so | |
13866 | Emacs Lisp interpreter ends of seeing a single backslash followed by a | |
13867 | letter. So it discovers the letter is special.) | |
13868 | ||
13869 | We need a counter to count how many words there are; this variable | |
13870 | must first be set to 0 and then incremented each time Emacs goes | |
13871 | around the @code{while} loop. The incrementing expression is simply: | |
13872 | ||
13873 | @smallexample | |
13874 | (setq count (1+ count)) | |
13875 | @end smallexample | |
13876 | ||
13877 | Finally, we want to tell the user how many words there are in the | |
13878 | region. The @code{message} function is intended for presenting this | |
13879 | kind of information to the user. The message has to be phrased so | |
13880 | that it reads properly regardless of how many words there are in the | |
13881 | region: we don't want to say that ``there are 1 words in the region''. | |
13882 | The conflict between singular and plural is ungrammatical. We can | |
13883 | solve this problem by using a conditional expression that evaluates | |
13884 | different messages depending on the number of words in the region. | |
13885 | There are three possibilities: no words in the region, one word in the | |
13886 | region, and more than one word. This means that the @code{cond} | |
13887 | special form is appropriate. | |
13888 | ||
13889 | @need 1500 | |
13890 | All this leads to the following function definition: | |
13891 | ||
13892 | @smallexample | |
13893 | @group | |
13894 | ;;; @r{First version; has bugs!} | |
ea4f7750 | 13895 | (defun @value{COUNT-WORDS} (beginning end) |
8cda6f8f GM |
13896 | "Print number of words in the region. |
13897 | Words are defined as at least one word-constituent | |
13898 | character followed by at least one character that | |
13899 | is not a word-constituent. The buffer's syntax | |
13900 | table determines which characters these are." | |
13901 | (interactive "r") | |
13902 | (message "Counting words in region ... ") | |
13903 | @end group | |
13904 | ||
13905 | @group | |
13906 | ;;; @r{1. Set up appropriate conditions.} | |
13907 | (save-excursion | |
13908 | (goto-char beginning) | |
13909 | (let ((count 0)) | |
13910 | @end group | |
13911 | ||
13912 | @group | |
13913 | ;;; @r{2. Run the} while @r{loop.} | |
13914 | (while (< (point) end) | |
13915 | (re-search-forward "\\w+\\W*") | |
13916 | (setq count (1+ count))) | |
13917 | @end group | |
13918 | ||
13919 | @group | |
13920 | ;;; @r{3. Send a message to the user.} | |
13921 | (cond ((zerop count) | |
13922 | (message | |
13923 | "The region does NOT have any words.")) | |
13924 | ((= 1 count) | |
13925 | (message | |
13926 | "The region has 1 word.")) | |
13927 | (t | |
13928 | (message | |
13929 | "The region has %d words." count)))))) | |
13930 | @end group | |
13931 | @end smallexample | |
13932 | ||
13933 | @noindent | |
13934 | As written, the function works, but not in all circumstances. | |
13935 | ||
d6adf7e7 | 13936 | @node Whitespace Bug |
ea4f7750 | 13937 | @subsection The Whitespace Bug in @code{@value{COUNT-WORDS}} |
8cda6f8f | 13938 | |
ea4f7750 | 13939 | The @code{@value{COUNT-WORDS}} command described in the preceding |
8cda6f8f GM |
13940 | section has two bugs, or rather, one bug with two manifestations. |
13941 | First, if you mark a region containing only whitespace in the middle | |
ea4f7750 | 13942 | of some text, the @code{@value{COUNT-WORDS}} command tells you that the |
8cda6f8f GM |
13943 | region contains one word! Second, if you mark a region containing |
13944 | only whitespace at the end of the buffer or the accessible portion of | |
13945 | a narrowed buffer, the command displays an error message that looks | |
13946 | like this: | |
13947 | ||
13948 | @smallexample | |
13949 | Search failed: "\\w+\\W*" | |
13950 | @end smallexample | |
13951 | ||
13952 | If you are reading this in Info in GNU Emacs, you can test for these | |
13953 | bugs yourself. | |
13954 | ||
13955 | First, evaluate the function in the usual manner to install it. | |
13956 | @ifinfo | |
13957 | Here is a copy of the definition. Place your cursor after the closing | |
13958 | parenthesis and type @kbd{C-x C-e} to install it. | |
13959 | ||
13960 | @smallexample | |
13961 | @group | |
13962 | ;; @r{First version; has bugs!} | |
ea4f7750 | 13963 | (defun @value{COUNT-WORDS} (beginning end) |
8cda6f8f GM |
13964 | "Print number of words in the region. |
13965 | Words are defined as at least one word-constituent character followed | |
13966 | by at least one character that is not a word-constituent. The buffer's | |
13967 | syntax table determines which characters these are." | |
13968 | @end group | |
13969 | @group | |
13970 | (interactive "r") | |
13971 | (message "Counting words in region ... ") | |
13972 | @end group | |
13973 | ||
13974 | @group | |
13975 | ;;; @r{1. Set up appropriate conditions.} | |
13976 | (save-excursion | |
13977 | (goto-char beginning) | |
13978 | (let ((count 0)) | |
13979 | @end group | |
13980 | ||
13981 | @group | |
13982 | ;;; @r{2. Run the} while @r{loop.} | |
13983 | (while (< (point) end) | |
13984 | (re-search-forward "\\w+\\W*") | |
13985 | (setq count (1+ count))) | |
13986 | @end group | |
13987 | ||
13988 | @group | |
13989 | ;;; @r{3. Send a message to the user.} | |
13990 | (cond ((zerop count) | |
13991 | (message "The region does NOT have any words.")) | |
13992 | ((= 1 count) (message "The region has 1 word.")) | |
13993 | (t (message "The region has %d words." count)))))) | |
13994 | @end group | |
13995 | @end smallexample | |
13996 | @end ifinfo | |
13997 | ||
13998 | @need 1000 | |
13999 | If you wish, you can also install this keybinding by evaluating it: | |
14000 | ||
14001 | @smallexample | |
ea4f7750 | 14002 | (global-set-key "\C-c=" '@value{COUNT-WORDS}) |
8cda6f8f GM |
14003 | @end smallexample |
14004 | ||
14005 | To conduct the first test, set mark and point to the beginning and end | |
14006 | of the following line and then type @kbd{C-c =} (or @kbd{M-x | |
ea4f7750 | 14007 | @value{COUNT-WORDS}} if you have not bound @kbd{C-c =}): |
8cda6f8f GM |
14008 | |
14009 | @smallexample | |
14010 | one two three | |
14011 | @end smallexample | |
14012 | ||
14013 | @noindent | |
14014 | Emacs will tell you, correctly, that the region has three words. | |
14015 | ||
14016 | Repeat the test, but place mark at the beginning of the line and place | |
14017 | point just @emph{before} the word @samp{one}. Again type the command | |
ea4f7750 | 14018 | @kbd{C-c =} (or @kbd{M-x @value{COUNT-WORDS}}). Emacs should tell you |
8cda6f8f GM |
14019 | that the region has no words, since it is composed only of the |
14020 | whitespace at the beginning of the line. But instead Emacs tells you | |
14021 | that the region has one word! | |
14022 | ||
14023 | For the third test, copy the sample line to the end of the | |
14024 | @file{*scratch*} buffer and then type several spaces at the end of the | |
14025 | line. Place mark right after the word @samp{three} and point at the | |
14026 | end of line. (The end of the line will be the end of the buffer.) | |
ea4f7750 | 14027 | Type @kbd{C-c =} (or @kbd{M-x @value{COUNT-WORDS}}) as you did before. |
8cda6f8f GM |
14028 | Again, Emacs should tell you that the region has no words, since it is |
14029 | composed only of the whitespace at the end of the line. Instead, | |
14030 | Emacs displays an error message saying @samp{Search failed}. | |
14031 | ||
14032 | The two bugs stem from the same problem. | |
14033 | ||
14034 | Consider the first manifestation of the bug, in which the command | |
14035 | tells you that the whitespace at the beginning of the line contains | |
ea4f7750 | 14036 | one word. What happens is this: The @code{M-x @value{COUNT-WORDS}} |
8cda6f8f GM |
14037 | command moves point to the beginning of the region. The @code{while} |
14038 | tests whether the value of point is smaller than the value of | |
14039 | @code{end}, which it is. Consequently, the regular expression search | |
14040 | looks for and finds the first word. It leaves point after the word. | |
14041 | @code{count} is set to one. The @code{while} loop repeats; but this | |
14042 | time the value of point is larger than the value of @code{end}, the | |
14043 | loop is exited; and the function displays a message saying the number | |
14044 | of words in the region is one. In brief, the regular expression | |
14045 | search looks for and finds the word even though it is outside | |
14046 | the marked region. | |
14047 | ||
14048 | In the second manifestation of the bug, the region is whitespace at | |
14049 | the end of the buffer. Emacs says @samp{Search failed}. What happens | |
14050 | is that the true-or-false-test in the @code{while} loop tests true, so | |
14051 | the search expression is executed. But since there are no more words | |
14052 | in the buffer, the search fails. | |
14053 | ||
14054 | In both manifestations of the bug, the search extends or attempts to | |
14055 | extend outside of the region. | |
14056 | ||
14057 | The solution is to limit the search to the region---this is a fairly | |
14058 | simple action, but as you may have come to expect, it is not quite as | |
14059 | simple as you might think. | |
14060 | ||
14061 | As we have seen, the @code{re-search-forward} function takes a search | |
14062 | pattern as its first argument. But in addition to this first, | |
14063 | mandatory argument, it accepts three optional arguments. The optional | |
14064 | second argument bounds the search. The optional third argument, if | |
14065 | @code{t}, causes the function to return @code{nil} rather than signal | |
14066 | an error if the search fails. The optional fourth argument is a | |
14067 | repeat count. (In Emacs, you can see a function's documentation by | |
14068 | typing @kbd{C-h f}, the name of the function, and then @key{RET}.) | |
14069 | ||
ea4f7750 | 14070 | In the @code{@value{COUNT-WORDS}} definition, the value of the end of |
8cda6f8f GM |
14071 | the region is held by the variable @code{end} which is passed as an |
14072 | argument to the function. Thus, we can add @code{end} as an argument | |
14073 | to the regular expression search expression: | |
14074 | ||
14075 | @smallexample | |
14076 | (re-search-forward "\\w+\\W*" end) | |
14077 | @end smallexample | |
14078 | ||
ea4f7750 | 14079 | However, if you make only this change to the @code{@value{COUNT-WORDS}} |
8cda6f8f GM |
14080 | definition and then test the new version of the definition on a |
14081 | stretch of whitespace, you will receive an error message saying | |
14082 | @samp{Search failed}. | |
14083 | ||
14084 | What happens is this: the search is limited to the region, and fails | |
14085 | as you expect because there are no word-constituent characters in the | |
14086 | region. Since it fails, we receive an error message. But we do not | |
14087 | want to receive an error message in this case; we want to receive the | |
14088 | message that "The region does NOT have any words." | |
14089 | ||
14090 | The solution to this problem is to provide @code{re-search-forward} | |
14091 | with a third argument of @code{t}, which causes the function to return | |
14092 | @code{nil} rather than signal an error if the search fails. | |
14093 | ||
14094 | However, if you make this change and try it, you will see the message | |
14095 | ``Counting words in region ... '' and @dots{} you will keep on seeing | |
14096 | that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}). | |
14097 | ||
14098 | Here is what happens: the search is limited to the region, as before, | |
14099 | and it fails because there are no word-constituent characters in the | |
14100 | region, as expected. Consequently, the @code{re-search-forward} | |
14101 | expression returns @code{nil}. It does nothing else. In particular, | |
14102 | it does not move point, which it does as a side effect if it finds the | |
14103 | search target. After the @code{re-search-forward} expression returns | |
14104 | @code{nil}, the next expression in the @code{while} loop is evaluated. | |
14105 | This expression increments the count. Then the loop repeats. The | |
14106 | true-or-false-test tests true because the value of point is still less | |
14107 | than the value of end, since the @code{re-search-forward} expression | |
14108 | did not move point. @dots{} and the cycle repeats @dots{} | |
14109 | ||
ea4f7750 | 14110 | The @code{@value{COUNT-WORDS}} definition requires yet another |
8cda6f8f GM |
14111 | modification, to cause the true-or-false-test of the @code{while} loop |
14112 | to test false if the search fails. Put another way, there are two | |
14113 | conditions that must be satisfied in the true-or-false-test before the | |
14114 | word count variable is incremented: point must still be within the | |
14115 | region and the search expression must have found a word to count. | |
14116 | ||
14117 | Since both the first condition and the second condition must be true | |
14118 | together, the two expressions, the region test and the search | |
14119 | expression, can be joined with an @code{and} special form and embedded in | |
14120 | the @code{while} loop as the true-or-false-test, like this: | |
14121 | ||
14122 | @smallexample | |
14123 | (and (< (point) end) (re-search-forward "\\w+\\W*" end t)) | |
14124 | @end smallexample | |
14125 | ||
14126 | @c colon in printed section title causes problem in Info cross reference | |
14127 | @c also trouble with an overfull hbox | |
14128 | @iftex | |
14129 | @noindent | |
14130 | (For information about @code{and}, see | |
14131 | @ref{kill-new function, , The @code{kill-new} function}.) | |
14132 | @end iftex | |
14133 | @ifinfo | |
14134 | @noindent | |
14135 | (@xref{kill-new function, , The @code{kill-new} function}, for | |
14136 | information about @code{and}.) | |
14137 | @end ifinfo | |
14138 | ||
14139 | The @code{re-search-forward} expression returns @code{t} if the search | |
14140 | succeeds and as a side effect moves point. Consequently, as words are | |
14141 | found, point is moved through the region. When the search expression | |
14142 | fails to find another word, or when point reaches the end of the | |
14143 | region, the true-or-false-test tests false, the @code{while} loop | |
ea4f7750 | 14144 | exits, and the @code{@value{COUNT-WORDS}} function displays one or |
8cda6f8f GM |
14145 | other of its messages. |
14146 | ||
ea4f7750 | 14147 | After incorporating these final changes, the @code{@value{COUNT-WORDS}} |
8cda6f8f GM |
14148 | works without bugs (or at least, without bugs that I have found!). |
14149 | Here is what it looks like: | |
14150 | ||
14151 | @smallexample | |
14152 | @group | |
14153 | ;;; @r{Final version:} @code{while} | |
ea4f7750 | 14154 | (defun @value{COUNT-WORDS} (beginning end) |
8cda6f8f GM |
14155 | "Print number of words in the region." |
14156 | (interactive "r") | |
14157 | (message "Counting words in region ... ") | |
14158 | @end group | |
14159 | ||
14160 | @group | |
14161 | ;;; @r{1. Set up appropriate conditions.} | |
14162 | (save-excursion | |
14163 | (let ((count 0)) | |
14164 | (goto-char beginning) | |
14165 | @end group | |
14166 | ||
14167 | @group | |
14168 | ;;; @r{2. Run the} while @r{loop.} | |
14169 | (while (and (< (point) end) | |
14170 | (re-search-forward "\\w+\\W*" end t)) | |
14171 | (setq count (1+ count))) | |
14172 | @end group | |
14173 | ||
14174 | @group | |
14175 | ;;; @r{3. Send a message to the user.} | |
14176 | (cond ((zerop count) | |
14177 | (message | |
14178 | "The region does NOT have any words.")) | |
14179 | ((= 1 count) | |
14180 | (message | |
14181 | "The region has 1 word.")) | |
14182 | (t | |
14183 | (message | |
14184 | "The region has %d words." count)))))) | |
14185 | @end group | |
14186 | @end smallexample | |
14187 | ||
d6adf7e7 | 14188 | @node recursive-count-words |
8cda6f8f GM |
14189 | @section Count Words Recursively |
14190 | @cindex Count words recursively | |
14191 | @cindex Recursively counting words | |
14192 | @cindex Words, counted recursively | |
14193 | ||
14194 | You can write the function for counting words recursively as well as | |
14195 | with a @code{while} loop. Let's see how this is done. | |
14196 | ||
ea4f7750 | 14197 | First, we need to recognize that the @code{@value{COUNT-WORDS}} |
8cda6f8f GM |
14198 | function has three jobs: it sets up the appropriate conditions for |
14199 | counting to occur; it counts the words in the region; and it sends a | |
14200 | message to the user telling how many words there are. | |
14201 | ||
14202 | If we write a single recursive function to do everything, we will | |
14203 | receive a message for every recursive call. If the region contains 13 | |
14204 | words, we will receive thirteen messages, one right after the other. | |
14205 | We don't want this! Instead, we must write two functions to do the | |
14206 | job, one of which (the recursive function) will be used inside of the | |
14207 | other. One function will set up the conditions and display the | |
14208 | message; the other will return the word count. | |
14209 | ||
14210 | Let us start with the function that causes the message to be displayed. | |
ea4f7750 | 14211 | We can continue to call this @code{@value{COUNT-WORDS}}. |
8cda6f8f GM |
14212 | |
14213 | This is the function that the user will call. It will be interactive. | |
14214 | Indeed, it will be similar to our previous versions of this | |
14215 | function, except that it will call @code{recursive-count-words} to | |
14216 | determine how many words are in the region. | |
14217 | ||
14218 | @need 1250 | |
14219 | We can readily construct a template for this function, based on our | |
14220 | previous versions: | |
14221 | ||
14222 | @smallexample | |
14223 | @group | |
14224 | ;; @r{Recursive version; uses regular expression search} | |
ea4f7750 | 14225 | (defun @value{COUNT-WORDS} (beginning end) |
8cda6f8f GM |
14226 | "@var{documentation}@dots{}" |
14227 | (@var{interactive-expression}@dots{}) | |
14228 | @end group | |
14229 | @group | |
14230 | ||
14231 | ;;; @r{1. Set up appropriate conditions.} | |
14232 | (@var{explanatory message}) | |
14233 | (@var{set-up functions}@dots{} | |
14234 | @end group | |
14235 | @group | |
14236 | ||
14237 | ;;; @r{2. Count the words.} | |
14238 | @var{recursive call} | |
14239 | @end group | |
14240 | @group | |
14241 | ||
14242 | ;;; @r{3. Send a message to the user.} | |
14243 | @var{message providing word count})) | |
14244 | @end group | |
14245 | @end smallexample | |
14246 | ||
14247 | The definition looks straightforward, except that somehow the count | |
14248 | returned by the recursive call must be passed to the message | |
14249 | displaying the word count. A little thought suggests that this can be | |
14250 | done by making use of a @code{let} expression: we can bind a variable | |
14251 | in the varlist of a @code{let} expression to the number of words in | |
14252 | the region, as returned by the recursive call; and then the | |
14253 | @code{cond} expression, using binding, can display the value to the | |
14254 | user. | |
14255 | ||
14256 | Often, one thinks of the binding within a @code{let} expression as | |
14257 | somehow secondary to the `primary' work of a function. But in this | |
14258 | case, what you might consider the `primary' job of the function, | |
14259 | counting words, is done within the @code{let} expression. | |
14260 | ||
14261 | @need 1250 | |
14262 | Using @code{let}, the function definition looks like this: | |
14263 | ||
14264 | @smallexample | |
14265 | @group | |
ea4f7750 | 14266 | (defun @value{COUNT-WORDS} (beginning end) |
8cda6f8f GM |
14267 | "Print number of words in the region." |
14268 | (interactive "r") | |
14269 | @end group | |
14270 | ||
14271 | @group | |
14272 | ;;; @r{1. Set up appropriate conditions.} | |
14273 | (message "Counting words in region ... ") | |
14274 | (save-excursion | |
14275 | (goto-char beginning) | |
14276 | @end group | |
14277 | ||
14278 | @group | |
14279 | ;;; @r{2. Count the words.} | |
14280 | (let ((count (recursive-count-words end))) | |
14281 | @end group | |
14282 | ||
14283 | @group | |
14284 | ;;; @r{3. Send a message to the user.} | |
14285 | (cond ((zerop count) | |
14286 | (message | |
14287 | "The region does NOT have any words.")) | |
14288 | ((= 1 count) | |
14289 | (message | |
14290 | "The region has 1 word.")) | |
14291 | (t | |
14292 | (message | |
14293 | "The region has %d words." count)))))) | |
14294 | @end group | |
14295 | @end smallexample | |
14296 | ||
14297 | Next, we need to write the recursive counting function. | |
14298 | ||
14299 | A recursive function has at least three parts: the `do-again-test', the | |
14300 | `next-step-expression', and the recursive call. | |
14301 | ||
14302 | The do-again-test determines whether the function will or will not be | |
14303 | called again. Since we are counting words in a region and can use a | |
14304 | function that moves point forward for every word, the do-again-test | |
14305 | can check whether point is still within the region. The do-again-test | |
14306 | should find the value of point and determine whether point is before, | |
14307 | at, or after the value of the end of the region. We can use the | |
14308 | @code{point} function to locate point. Clearly, we must pass the | |
14309 | value of the end of the region to the recursive counting function as an | |
14310 | argument. | |
14311 | ||
14312 | In addition, the do-again-test should also test whether the search finds a | |
14313 | word. If it does not, the function should not call itself again. | |
14314 | ||
14315 | The next-step-expression changes a value so that when the recursive | |
14316 | function is supposed to stop calling itself, it stops. More | |
14317 | precisely, the next-step-expression changes a value so that at the | |
14318 | right time, the do-again-test stops the recursive function from | |
14319 | calling itself again. In this case, the next-step-expression can be | |
14320 | the expression that moves point forward, word by word. | |
14321 | ||
14322 | The third part of a recursive function is the recursive call. | |
14323 | ||
14324 | Somewhere, also, we also need a part that does the `work' of the | |
14325 | function, a part that does the counting. A vital part! | |
14326 | ||
14327 | @need 1250 | |
14328 | But already, we have an outline of the recursive counting function: | |
14329 | ||
14330 | @smallexample | |
14331 | @group | |
14332 | (defun recursive-count-words (region-end) | |
14333 | "@var{documentation}@dots{}" | |
14334 | @var{do-again-test} | |
14335 | @var{next-step-expression} | |
14336 | @var{recursive call}) | |
14337 | @end group | |
14338 | @end smallexample | |
14339 | ||
14340 | Now we need to fill in the slots. Let's start with the simplest cases | |
14341 | first: if point is at or beyond the end of the region, there cannot | |
14342 | be any words in the region, so the function should return zero. | |
14343 | Likewise, if the search fails, there are no words to count, so the | |
14344 | function should return zero. | |
14345 | ||
14346 | On the other hand, if point is within the region and the search | |
14347 | succeeds, the function should call itself again. | |
14348 | ||
14349 | @need 800 | |
14350 | Thus, the do-again-test should look like this: | |
14351 | ||
14352 | @smallexample | |
14353 | @group | |
14354 | (and (< (point) region-end) | |
14355 | (re-search-forward "\\w+\\W*" region-end t)) | |
14356 | @end group | |
14357 | @end smallexample | |
14358 | ||
14359 | Note that the search expression is part of the do-again-test---the | |
14360 | function returns @code{t} if its search succeeds and @code{nil} if it | |
14361 | fails. (@xref{Whitespace Bug, , The Whitespace Bug in | |
ea4f7750 | 14362 | @code{@value{COUNT-WORDS}}}, for an explanation of how |
8cda6f8f GM |
14363 | @code{re-search-forward} works.) |
14364 | ||
14365 | The do-again-test is the true-or-false test of an @code{if} clause. | |
14366 | Clearly, if the do-again-test succeeds, the then-part of the @code{if} | |
14367 | clause should call the function again; but if it fails, the else-part | |
14368 | should return zero since either point is outside the region or the | |
14369 | search failed because there were no words to find. | |
14370 | ||
14371 | But before considering the recursive call, we need to consider the | |
14372 | next-step-expression. What is it? Interestingly, it is the search | |
14373 | part of the do-again-test. | |
14374 | ||
14375 | In addition to returning @code{t} or @code{nil} for the | |
14376 | do-again-test, @code{re-search-forward} moves point forward as a side | |
14377 | effect of a successful search. This is the action that changes the | |
14378 | value of point so that the recursive function stops calling itself | |
14379 | when point completes its movement through the region. Consequently, | |
14380 | the @code{re-search-forward} expression is the next-step-expression. | |
14381 | ||
14382 | @need 1200 | |
14383 | In outline, then, the body of the @code{recursive-count-words} | |
14384 | function looks like this: | |
14385 | ||
14386 | @smallexample | |
14387 | @group | |
14388 | (if @var{do-again-test-and-next-step-combined} | |
14389 | ;; @r{then} | |
14390 | @var{recursive-call-returning-count} | |
14391 | ;; @r{else} | |
14392 | @var{return-zero}) | |
14393 | @end group | |
14394 | @end smallexample | |
14395 | ||
14396 | How to incorporate the mechanism that counts? | |
14397 | ||
14398 | If you are not used to writing recursive functions, a question like | |
14399 | this can be troublesome. But it can and should be approached | |
14400 | systematically. | |
14401 | ||
14402 | We know that the counting mechanism should be associated in some way | |
14403 | with the recursive call. Indeed, since the next-step-expression moves | |
14404 | point forward by one word, and since a recursive call is made for | |
14405 | each word, the counting mechanism must be an expression that adds one | |
14406 | to the value returned by a call to @code{recursive-count-words}. | |
14407 | ||
14408 | @need 800 | |
14409 | Consider several cases: | |
14410 | ||
14411 | @itemize @bullet | |
14412 | @item | |
14413 | If there are two words in the region, the function should return | |
14414 | a value resulting from adding one to the value returned when it counts | |
14415 | the first word, plus the number returned when it counts the remaining | |
14416 | words in the region, which in this case is one. | |
14417 | ||
14418 | @item | |
14419 | If there is one word in the region, the function should return | |
14420 | a value resulting from adding one to the value returned when it counts | |
14421 | that word, plus the number returned when it counts the remaining | |
14422 | words in the region, which in this case is zero. | |
14423 | ||
14424 | @item | |
14425 | If there are no words in the region, the function should return zero. | |
14426 | @end itemize | |
14427 | ||
14428 | From the sketch we can see that the else-part of the @code{if} returns | |
14429 | zero for the case of no words. This means that the then-part of the | |
14430 | @code{if} must return a value resulting from adding one to the value | |
14431 | returned from a count of the remaining words. | |
14432 | ||
14433 | @need 1200 | |
14434 | The expression will look like this, where @code{1+} is a function that | |
14435 | adds one to its argument. | |
14436 | ||
14437 | @smallexample | |
14438 | (1+ (recursive-count-words region-end)) | |
14439 | @end smallexample | |
14440 | ||
14441 | @need 1200 | |
14442 | The whole @code{recursive-count-words} function will then look like | |
14443 | this: | |
14444 | ||
14445 | @smallexample | |
14446 | @group | |
14447 | (defun recursive-count-words (region-end) | |
14448 | "@var{documentation}@dots{}" | |
14449 | ||
14450 | ;;; @r{1. do-again-test} | |
14451 | (if (and (< (point) region-end) | |
14452 | (re-search-forward "\\w+\\W*" region-end t)) | |
14453 | @end group | |
14454 | ||
14455 | @group | |
14456 | ;;; @r{2. then-part: the recursive call} | |
14457 | (1+ (recursive-count-words region-end)) | |
14458 | ||
14459 | ;;; @r{3. else-part} | |
14460 | 0)) | |
14461 | @end group | |
14462 | @end smallexample | |
14463 | ||
14464 | @need 1250 | |
14465 | Let's examine how this works: | |
14466 | ||
14467 | If there are no words in the region, the else part of the @code{if} | |
14468 | expression is evaluated and consequently the function returns zero. | |
14469 | ||
14470 | If there is one word in the region, the value of point is less than | |
14471 | the value of @code{region-end} and the search succeeds. In this case, | |
14472 | the true-or-false-test of the @code{if} expression tests true, and the | |
14473 | then-part of the @code{if} expression is evaluated. The counting | |
14474 | expression is evaluated. This expression returns a value (which will | |
14475 | be the value returned by the whole function) that is the sum of one | |
14476 | added to the value returned by a recursive call. | |
14477 | ||
14478 | Meanwhile, the next-step-expression has caused point to jump over the | |
14479 | first (and in this case only) word in the region. This means that | |
14480 | when @code{(recursive-count-words region-end)} is evaluated a second | |
14481 | time, as a result of the recursive call, the value of point will be | |
14482 | equal to or greater than the value of region end. So this time, | |
14483 | @code{recursive-count-words} will return zero. The zero will be added | |
14484 | to one, and the original evaluation of @code{recursive-count-words} | |
14485 | will return one plus zero, which is one, which is the correct amount. | |
14486 | ||
14487 | Clearly, if there are two words in the region, the first call to | |
14488 | @code{recursive-count-words} returns one added to the value returned | |
14489 | by calling @code{recursive-count-words} on a region containing the | |
14490 | remaining word---that is, it adds one to one, producing two, which is | |
14491 | the correct amount. | |
14492 | ||
14493 | Similarly, if there are three words in the region, the first call to | |
14494 | @code{recursive-count-words} returns one added to the value returned | |
14495 | by calling @code{recursive-count-words} on a region containing the | |
14496 | remaining two words---and so on and so on. | |
14497 | ||
14498 | @need 1250 | |
14499 | @noindent | |
14500 | With full documentation the two functions look like this: | |
14501 | ||
14502 | @need 1250 | |
14503 | @noindent | |
14504 | The recursive function: | |
14505 | ||
14506 | @findex recursive-count-words | |
14507 | @smallexample | |
14508 | @group | |
14509 | (defun recursive-count-words (region-end) | |
14510 | "Number of words between point and REGION-END." | |
14511 | @end group | |
14512 | ||
14513 | @group | |
14514 | ;;; @r{1. do-again-test} | |
14515 | (if (and (< (point) region-end) | |
14516 | (re-search-forward "\\w+\\W*" region-end t)) | |
14517 | @end group | |
14518 | ||
14519 | @group | |
14520 | ;;; @r{2. then-part: the recursive call} | |
14521 | (1+ (recursive-count-words region-end)) | |
14522 | ||
14523 | ;;; @r{3. else-part} | |
14524 | 0)) | |
14525 | @end group | |
14526 | @end smallexample | |
14527 | ||
14528 | @need 800 | |
14529 | @noindent | |
14530 | The wrapper: | |
14531 | ||
14532 | @smallexample | |
14533 | @group | |
14534 | ;;; @r{Recursive version} | |
ea4f7750 | 14535 | (defun @value{COUNT-WORDS} (beginning end) |
8cda6f8f GM |
14536 | "Print number of words in the region. |
14537 | @end group | |
14538 | ||
14539 | @group | |
14540 | Words are defined as at least one word-constituent | |
14541 | character followed by at least one character that is | |
14542 | not a word-constituent. The buffer's syntax table | |
14543 | determines which characters these are." | |
14544 | @end group | |
14545 | @group | |
14546 | (interactive "r") | |
14547 | (message "Counting words in region ... ") | |
14548 | (save-excursion | |
14549 | (goto-char beginning) | |
14550 | (let ((count (recursive-count-words end))) | |
14551 | @end group | |
14552 | @group | |
14553 | (cond ((zerop count) | |
14554 | (message | |
14555 | "The region does NOT have any words.")) | |
14556 | @end group | |
14557 | @group | |
14558 | ((= 1 count) | |
14559 | (message "The region has 1 word.")) | |
14560 | (t | |
14561 | (message | |
14562 | "The region has %d words." count)))))) | |
14563 | @end group | |
14564 | @end smallexample | |
14565 | ||
d6adf7e7 | 14566 | @node Counting Exercise |
8cda6f8f GM |
14567 | @section Exercise: Counting Punctuation |
14568 | ||
14569 | Using a @code{while} loop, write a function to count the number of | |
14570 | punctuation marks in a region---period, comma, semicolon, colon, | |
14571 | exclamation mark, and question mark. Do the same using recursion. | |
14572 | ||
d6adf7e7 | 14573 | @node Words in a defun |
8cda6f8f GM |
14574 | @chapter Counting Words in a @code{defun} |
14575 | @cindex Counting words in a @code{defun} | |
14576 | @cindex Word counting in a @code{defun} | |
14577 | ||
14578 | Our next project is to count the number of words in a function | |
14579 | definition. Clearly, this can be done using some variant of | |
ea4f7750 | 14580 | @code{@value{COUNT-WORDS}}. @xref{Counting Words, , Counting Words: |
8cda6f8f GM |
14581 | Repetition and Regexps}. If we are just going to count the words in |
14582 | one definition, it is easy enough to mark the definition with the | |
14583 | @kbd{C-M-h} (@code{mark-defun}) command, and then call | |
ea4f7750 | 14584 | @code{@value{COUNT-WORDS}}. |
8cda6f8f GM |
14585 | |
14586 | However, I am more ambitious: I want to count the words and symbols in | |
14587 | every definition in the Emacs sources and then print a graph that | |
14588 | shows how many functions there are of each length: how many contain 40 | |
14589 | to 49 words or symbols, how many contain 50 to 59 words or symbols, | |
14590 | and so on. I have often been curious how long a typical function is, | |
14591 | and this will tell. | |
14592 | ||
14593 | @menu | |
14594 | * Divide and Conquer:: | |
14595 | * Words and Symbols:: What to count? | |
14596 | * Syntax:: What constitutes a word or symbol? | |
ea4f7750 | 14597 | * count-words-in-defun:: Very like @code{@value{COUNT-WORDS}}. |
8cda6f8f GM |
14598 | * Several defuns:: Counting several defuns in a file. |
14599 | * Find a File:: Do you want to look at a file? | |
14600 | * lengths-list-file:: A list of the lengths of many definitions. | |
14601 | * Several files:: Counting in definitions in different files. | |
14602 | * Several files recursively:: Recursively counting in different files. | |
14603 | * Prepare the data:: Prepare the data for display in a graph. | |
14604 | @end menu | |
14605 | ||
8cda6f8f | 14606 | @ifnottex |
d6adf7e7 | 14607 | @node Divide and Conquer |
8cda6f8f GM |
14608 | @unnumberedsec Divide and Conquer |
14609 | @end ifnottex | |
14610 | ||
14611 | Described in one phrase, the histogram project is daunting; but | |
14612 | divided into numerous small steps, each of which we can take one at a | |
14613 | time, the project becomes less fearsome. Let us consider what the | |
14614 | steps must be: | |
14615 | ||
14616 | @itemize @bullet | |
14617 | @item | |
14618 | First, write a function to count the words in one definition. This | |
14619 | includes the problem of handling symbols as well as words. | |
14620 | ||
14621 | @item | |
14622 | Second, write a function to list the numbers of words in each function | |
14623 | in a file. This function can use the @code{count-words-in-defun} | |
14624 | function. | |
14625 | ||
14626 | @item | |
14627 | Third, write a function to list the numbers of words in each function | |
14628 | in each of several files. This entails automatically finding the | |
14629 | various files, switching to them, and counting the words in the | |
14630 | definitions within them. | |
14631 | ||
14632 | @item | |
14633 | Fourth, write a function to convert the list of numbers that we | |
14634 | created in step three to a form that will be suitable for printing as | |
14635 | a graph. | |
14636 | ||
14637 | @item | |
14638 | Fifth, write a function to print the results as a graph. | |
14639 | @end itemize | |
14640 | ||
14641 | This is quite a project! But if we take each step slowly, it will not | |
14642 | be difficult. | |
14643 | ||
d6adf7e7 | 14644 | @node Words and Symbols |
8cda6f8f GM |
14645 | @section What to Count? |
14646 | @cindex Words and symbols in defun | |
14647 | ||
14648 | When we first start thinking about how to count the words in a | |
14649 | function definition, the first question is (or ought to be) what are | |
14650 | we going to count? When we speak of `words' with respect to a Lisp | |
14651 | function definition, we are actually speaking, in large part, of | |
14652 | `symbols'. For example, the following @code{multiply-by-seven} | |
14653 | function contains the five symbols @code{defun}, | |
14654 | @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In | |
14655 | addition, in the documentation string, it contains the four words | |
14656 | @samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The | |
14657 | symbol @samp{number} is repeated, so the definition contains a total | |
14658 | of ten words and symbols. | |
14659 | ||
14660 | @smallexample | |
14661 | @group | |
14662 | (defun multiply-by-seven (number) | |
14663 | "Multiply NUMBER by seven." | |
14664 | (* 7 number)) | |
14665 | @end group | |
14666 | @end smallexample | |
14667 | ||
14668 | @noindent | |
14669 | However, if we mark the @code{multiply-by-seven} definition with | |
14670 | @kbd{C-M-h} (@code{mark-defun}), and then call | |
ea4f7750 GM |
14671 | @code{@value{COUNT-WORDS}} on it, we will find that |
14672 | @code{@value{COUNT-WORDS}} claims the definition has eleven words, not | |
8cda6f8f GM |
14673 | ten! Something is wrong! |
14674 | ||
ea4f7750 | 14675 | The problem is twofold: @code{@value{COUNT-WORDS}} does not count the |
8cda6f8f GM |
14676 | @samp{*} as a word, and it counts the single symbol, |
14677 | @code{multiply-by-seven}, as containing three words. The hyphens are | |
14678 | treated as if they were interword spaces rather than intraword | |
14679 | connectors: @samp{multiply-by-seven} is counted as if it were written | |
14680 | @samp{multiply by seven}. | |
14681 | ||
14682 | The cause of this confusion is the regular expression search within | |
ea4f7750 GM |
14683 | the @code{@value{COUNT-WORDS}} definition that moves point forward word |
14684 | by word. In the canonical version of @code{@value{COUNT-WORDS}}, the | |
8cda6f8f GM |
14685 | regexp is: |
14686 | ||
14687 | @smallexample | |
14688 | "\\w+\\W*" | |
14689 | @end smallexample | |
14690 | ||
14691 | @noindent | |
14692 | This regular expression is a pattern defining one or more word | |
14693 | constituent characters possibly followed by one or more characters | |
14694 | that are not word constituents. What is meant by `word constituent | |
14695 | characters' brings us to the issue of syntax, which is worth a section | |
14696 | of its own. | |
14697 | ||
d6adf7e7 | 14698 | @node Syntax |
8cda6f8f GM |
14699 | @section What Constitutes a Word or Symbol? |
14700 | @cindex Syntax categories and tables | |
14701 | ||
14702 | Emacs treats different characters as belonging to different | |
14703 | @dfn{syntax categories}. For example, the regular expression, | |
14704 | @samp{\\w+}, is a pattern specifying one or more @emph{word | |
14705 | constituent} characters. Word constituent characters are members of | |
14706 | one syntax category. Other syntax categories include the class of | |
14707 | punctuation characters, such as the period and the comma, and the | |
14708 | class of whitespace characters, such as the blank space and the tab | |
0fd2c9a3 | 14709 | character. (For more information, @pxref{Syntax Tables, , Syntax |
8cda6f8f GM |
14710 | Tables, elisp, The GNU Emacs Lisp Reference Manual}.) |
14711 | ||
14712 | Syntax tables specify which characters belong to which categories. | |
14713 | Usually, a hyphen is not specified as a `word constituent character'. | |
14714 | Instead, it is specified as being in the `class of characters that are | |
14715 | part of symbol names but not words.' This means that the | |
ea4f7750 GM |
14716 | @code{@value{COUNT-WORDS}} function treats it in the same way it treats |
14717 | an interword white space, which is why @code{@value{COUNT-WORDS}} | |
8cda6f8f GM |
14718 | counts @samp{multiply-by-seven} as three words. |
14719 | ||
14720 | There are two ways to cause Emacs to count @samp{multiply-by-seven} as | |
14721 | one symbol: modify the syntax table or modify the regular expression. | |
14722 | ||
14723 | We could redefine a hyphen as a word constituent character by | |
14724 | modifying the syntax table that Emacs keeps for each mode. This | |
14725 | action would serve our purpose, except that a hyphen is merely the | |
14726 | most common character within symbols that is not typically a word | |
14727 | constituent character; there are others, too. | |
14728 | ||
52af8e0a | 14729 | Alternatively, we can redefine the regexp used in the |
ea4f7750 | 14730 | @code{@value{COUNT-WORDS}} definition so as to include symbols. This |
8cda6f8f GM |
14731 | procedure has the merit of clarity, but the task is a little tricky. |
14732 | ||
14733 | @need 1200 | |
14734 | The first part is simple enough: the pattern must match ``at least one | |
14735 | character that is a word or symbol constituent''. Thus: | |
14736 | ||
14737 | @smallexample | |
14738 | "\\(\\w\\|\\s_\\)+" | |
14739 | @end smallexample | |
14740 | ||
14741 | @noindent | |
14742 | The @samp{\\(} is the first part of the grouping construct that | |
14743 | includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated | |
14744 | by the @samp{\\|}. The @samp{\\w} matches any word-constituent | |
14745 | character and the @samp{\\s_} matches any character that is part of a | |
14746 | symbol name but not a word-constituent character. The @samp{+} | |
14747 | following the group indicates that the word or symbol constituent | |
14748 | characters must be matched at least once. | |
14749 | ||
14750 | However, the second part of the regexp is more difficult to design. | |
14751 | What we want is to follow the first part with ``optionally one or more | |
14752 | characters that are not constituents of a word or symbol''. At first, | |
14753 | I thought I could define this with the following: | |
14754 | ||
14755 | @smallexample | |
14756 | "\\(\\W\\|\\S_\\)*" | |
14757 | @end smallexample | |
14758 | ||
14759 | @noindent | |
14760 | The upper case @samp{W} and @samp{S} match characters that are | |
14761 | @emph{not} word or symbol constituents. Unfortunately, this | |
14762 | expression matches any character that is either not a word constituent | |
14763 | or not a symbol constituent. This matches any character! | |
14764 | ||
14765 | I then noticed that every word or symbol in my test region was | |
14766 | followed by white space (blank space, tab, or newline). So I tried | |
14767 | placing a pattern to match one or more blank spaces after the pattern | |
14768 | for one or more word or symbol constituents. This failed, too. Words | |
14769 | and symbols are often separated by whitespace, but in actual code | |
14770 | parentheses may follow symbols and punctuation may follow words. So | |
14771 | finally, I designed a pattern in which the word or symbol constituents | |
14772 | are followed optionally by characters that are not white space and | |
14773 | then followed optionally by white space. | |
14774 | ||
14775 | @need 800 | |
14776 | Here is the full regular expression: | |
14777 | ||
14778 | @smallexample | |
14779 | "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" | |
14780 | @end smallexample | |
14781 | ||
d6adf7e7 | 14782 | @node count-words-in-defun |
8cda6f8f GM |
14783 | @section The @code{count-words-in-defun} Function |
14784 | @cindex Counting words in a @code{defun} | |
14785 | ||
14786 | We have seen that there are several ways to write a | |
ea4f7750 | 14787 | @code{count-words-region} function. To write a |
8cda6f8f GM |
14788 | @code{count-words-in-defun}, we need merely adapt one of these |
14789 | versions. | |
14790 | ||
14791 | The version that uses a @code{while} loop is easy to understand, so I | |
14792 | am going to adapt that. Because @code{count-words-in-defun} will be | |
14793 | part of a more complex program, it need not be interactive and it need | |
14794 | not display a message but just return the count. These considerations | |
14795 | simplify the definition a little. | |
14796 | ||
14797 | On the other hand, @code{count-words-in-defun} will be used within a | |
14798 | buffer that contains function definitions. Consequently, it is | |
14799 | reasonable to ask that the function determine whether it is called | |
14800 | when point is within a function definition, and if it is, to return | |
14801 | the count for that definition. This adds complexity to the | |
14802 | definition, but saves us from needing to pass arguments to the | |
14803 | function. | |
14804 | ||
14805 | @need 1250 | |
14806 | These considerations lead us to prepare the following template: | |
14807 | ||
14808 | @smallexample | |
14809 | @group | |
14810 | (defun count-words-in-defun () | |
14811 | "@var{documentation}@dots{}" | |
14812 | (@var{set up}@dots{} | |
14813 | (@var{while loop}@dots{}) | |
14814 | @var{return count}) | |
14815 | @end group | |
14816 | @end smallexample | |
14817 | ||
14818 | @noindent | |
14819 | As usual, our job is to fill in the slots. | |
14820 | ||
14821 | First, the set up. | |
14822 | ||
14823 | We are presuming that this function will be called within a buffer | |
14824 | containing function definitions. Point will either be within a | |
14825 | function definition or not. For @code{count-words-in-defun} to work, | |
14826 | point must move to the beginning of the definition, a counter must | |
14827 | start at zero, and the counting loop must stop when point reaches the | |
14828 | end of the definition. | |
14829 | ||
14830 | The @code{beginning-of-defun} function searches backwards for an | |
14831 | opening delimiter such as a @samp{(} at the beginning of a line, and | |
14832 | moves point to that position, or else to the limit of the search. In | |
14833 | practice, this means that @code{beginning-of-defun} moves point to the | |
14834 | beginning of an enclosing or preceding function definition, or else to | |
14835 | the beginning of the buffer. We can use @code{beginning-of-defun} to | |
14836 | place point where we wish to start. | |
14837 | ||
14838 | The @code{while} loop requires a counter to keep track of the words or | |
14839 | symbols being counted. A @code{let} expression can be used to create | |
14840 | a local variable for this purpose, and bind it to an initial value of zero. | |
14841 | ||
14842 | The @code{end-of-defun} function works like @code{beginning-of-defun} | |
14843 | except that it moves point to the end of the definition. | |
14844 | @code{end-of-defun} can be used as part of an expression that | |
14845 | determines the position of the end of the definition. | |
14846 | ||
14847 | The set up for @code{count-words-in-defun} takes shape rapidly: first | |
14848 | we move point to the beginning of the definition, then we create a | |
14849 | local variable to hold the count, and finally, we record the position | |
14850 | of the end of the definition so the @code{while} loop will know when to stop | |
14851 | looping. | |
14852 | ||
14853 | @need 1250 | |
14854 | The code looks like this: | |
14855 | ||
14856 | @smallexample | |
14857 | @group | |
14858 | (beginning-of-defun) | |
14859 | (let ((count 0) | |
14860 | (end (save-excursion (end-of-defun) (point)))) | |
14861 | @end group | |
14862 | @end smallexample | |
14863 | ||
14864 | @noindent | |
14865 | The code is simple. The only slight complication is likely to concern | |
14866 | @code{end}: it is bound to the position of the end of the definition | |
14867 | by a @code{save-excursion} expression that returns the value of point | |
14868 | after @code{end-of-defun} temporarily moves it to the end of the | |
14869 | definition. | |
14870 | ||
14871 | The second part of the @code{count-words-in-defun}, after the set up, | |
14872 | is the @code{while} loop. | |
14873 | ||
14874 | The loop must contain an expression that jumps point forward word by | |
14875 | word and symbol by symbol, and another expression that counts the | |
14876 | jumps. The true-or-false-test for the @code{while} loop should test | |
14877 | true so long as point should jump forward, and false when point is at | |
14878 | the end of the definition. We have already redefined the regular | |
0fd2c9a3 | 14879 | expression for this, so the loop is straightforward: |
8cda6f8f GM |
14880 | |
14881 | @smallexample | |
14882 | @group | |
14883 | (while (and (< (point) end) | |
14884 | (re-search-forward | |
1ef17681 | 14885 | "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t)) |
8cda6f8f GM |
14886 | (setq count (1+ count))) |
14887 | @end group | |
14888 | @end smallexample | |
14889 | ||
14890 | The third part of the function definition returns the count of words | |
14891 | and symbols. This part is the last expression within the body of the | |
14892 | @code{let} expression, and can be, very simply, the local variable | |
14893 | @code{count}, which when evaluated returns the count. | |
14894 | ||
14895 | @need 1250 | |
14896 | Put together, the @code{count-words-in-defun} definition looks like this: | |
14897 | ||
14898 | @findex count-words-in-defun | |
14899 | @smallexample | |
14900 | @group | |
14901 | (defun count-words-in-defun () | |
14902 | "Return the number of words and symbols in a defun." | |
14903 | (beginning-of-defun) | |
14904 | (let ((count 0) | |
14905 | (end (save-excursion (end-of-defun) (point)))) | |
14906 | @end group | |
14907 | @group | |
14908 | (while | |
14909 | (and (< (point) end) | |
14910 | (re-search-forward | |
14911 | "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" | |
14912 | end t)) | |
14913 | (setq count (1+ count))) | |
14914 | count)) | |
14915 | @end group | |
14916 | @end smallexample | |
14917 | ||
14918 | How to test this? The function is not interactive, but it is easy to | |
14919 | put a wrapper around the function to make it interactive; we can use | |
14920 | almost the same code as for the recursive version of | |
ea4f7750 | 14921 | @code{@value{COUNT-WORDS}}: |
8cda6f8f GM |
14922 | |
14923 | @smallexample | |
14924 | @group | |
14925 | ;;; @r{Interactive version.} | |
14926 | (defun count-words-defun () | |
14927 | "Number of words and symbols in a function definition." | |
14928 | (interactive) | |
14929 | (message | |
14930 | "Counting words and symbols in function definition ... ") | |
14931 | @end group | |
14932 | @group | |
14933 | (let ((count (count-words-in-defun))) | |
14934 | (cond | |
14935 | ((zerop count) | |
14936 | (message | |
14937 | "The definition does NOT have any words or symbols.")) | |
14938 | @end group | |
14939 | @group | |
14940 | ((= 1 count) | |
14941 | (message | |
14942 | "The definition has 1 word or symbol.")) | |
14943 | (t | |
14944 | (message | |
14945 | "The definition has %d words or symbols." count))))) | |
14946 | @end group | |
14947 | @end smallexample | |
14948 | ||
14949 | @need 800 | |
14950 | @noindent | |
14951 | Let's re-use @kbd{C-c =} as a convenient keybinding: | |
14952 | ||
14953 | @smallexample | |
14954 | (global-set-key "\C-c=" 'count-words-defun) | |
14955 | @end smallexample | |
14956 | ||
14957 | Now we can try out @code{count-words-defun}: install both | |
14958 | @code{count-words-in-defun} and @code{count-words-defun}, and set the | |
14959 | keybinding, and then place the cursor within the following definition: | |
14960 | ||
14961 | @smallexample | |
14962 | @group | |
14963 | (defun multiply-by-seven (number) | |
14964 | "Multiply NUMBER by seven." | |
14965 | (* 7 number)) | |
14966 | @result{} 10 | |
14967 | @end group | |
14968 | @end smallexample | |
14969 | ||
14970 | @noindent | |
14971 | Success! The definition has 10 words and symbols. | |
14972 | ||
14973 | The next problem is to count the numbers of words and symbols in | |
14974 | several definitions within a single file. | |
14975 | ||
d6adf7e7 | 14976 | @node Several defuns |
8cda6f8f GM |
14977 | @section Count Several @code{defuns} Within a File |
14978 | ||
14979 | A file such as @file{simple.el} may have a hundred or more function | |
14980 | definitions within it. Our long term goal is to collect statistics on | |
14981 | many files, but as a first step, our immediate goal is to collect | |
14982 | statistics on one file. | |
14983 | ||
14984 | The information will be a series of numbers, each number being the | |
14985 | length of a function definition. We can store the numbers in a list. | |
14986 | ||
14987 | We know that we will want to incorporate the information regarding one | |
14988 | file with information about many other files; this means that the | |
14989 | function for counting definition lengths within one file need only | |
14990 | return the list of lengths. It need not and should not display any | |
14991 | messages. | |
14992 | ||
14993 | The word count commands contain one expression to jump point forward | |
14994 | word by word and another expression to count the jumps. The function | |
14995 | to return the lengths of definitions can be designed to work the same | |
14996 | way, with one expression to jump point forward definition by | |
14997 | definition and another expression to construct the lengths' list. | |
14998 | ||
14999 | This statement of the problem makes it elementary to write the | |
15000 | function definition. Clearly, we will start the count at the | |
15001 | beginning of the file, so the first command will be @code{(goto-char | |
15002 | (point-min))}. Next, we start the @code{while} loop; and the | |
15003 | true-or-false test of the loop can be a regular expression search for | |
15004 | the next function definition---so long as the search succeeds, point | |
15005 | is moved forward and then the body of the loop is evaluated. The body | |
15006 | needs an expression that constructs the lengths' list. @code{cons}, | |
15007 | the list construction command, can be used to create the list. That | |
15008 | is almost all there is to it. | |
15009 | ||
15010 | @need 800 | |
15011 | Here is what this fragment of code looks like: | |
15012 | ||
15013 | @smallexample | |
15014 | @group | |
15015 | (goto-char (point-min)) | |
15016 | (while (re-search-forward "^(defun" nil t) | |
15017 | (setq lengths-list | |
15018 | (cons (count-words-in-defun) lengths-list))) | |
15019 | @end group | |
15020 | @end smallexample | |
15021 | ||
15022 | What we have left out is the mechanism for finding the file that | |
15023 | contains the function definitions. | |
15024 | ||
15025 | In previous examples, we either used this, the Info file, or we | |
15026 | switched back and forth to some other buffer, such as the | |
15027 | @file{*scratch*} buffer. | |
15028 | ||
15029 | Finding a file is a new process that we have not yet discussed. | |
15030 | ||
d6adf7e7 | 15031 | @node Find a File |
8cda6f8f GM |
15032 | @section Find a File |
15033 | @cindex Find a File | |
15034 | ||
15035 | To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file}) | |
15036 | command. This command is almost, but not quite right for the lengths | |
15037 | problem. | |
15038 | ||
15039 | @need 1200 | |
15040 | Let's look at the source for @code{find-file}: | |
15041 | ||
15042 | @smallexample | |
15043 | @group | |
15044 | (defun find-file (filename) | |
15045 | "Edit file FILENAME. | |
15046 | Switch to a buffer visiting file FILENAME, | |
15047 | creating one if none already exists." | |
15048 | (interactive "FFind file: ") | |
15049 | (switch-to-buffer (find-file-noselect filename))) | |
15050 | @end group | |
15051 | @end smallexample | |
15052 | ||
15053 | @noindent | |
15054 | (The most recent version of the @code{find-file} function definition | |
15055 | permits you to specify optional wildcards to visit multiple files; that | |
15056 | makes the definition more complex and we will not discuss it here, | |
15057 | since it is not relevant. You can see its source using either | |
15058 | @kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).) | |
15059 | ||
15060 | @ignore | |
15061 | In Emacs 22 | |
15062 | (defun find-file (filename &optional wildcards) | |
15063 | "Edit file FILENAME. | |
15064 | Switch to a buffer visiting file FILENAME, | |
15065 | creating one if none already exists. | |
15066 | Interactively, the default if you just type RET is the current directory, | |
15067 | but the visited file name is available through the minibuffer history: | |
15068 | type M-n to pull it into the minibuffer. | |
15069 | ||
15070 | Interactively, or if WILDCARDS is non-nil in a call from Lisp, | |
15071 | expand wildcards (if any) and visit multiple files. You can | |
15072 | suppress wildcard expansion by setting `find-file-wildcards' to nil. | |
15073 | ||
15074 | To visit a file without any kind of conversion and without | |
15075 | automatically choosing a major mode, use \\[find-file-literally]." | |
15076 | (interactive (find-file-read-args "Find file: " nil)) | |
15077 | (let ((value (find-file-noselect filename nil nil wildcards))) | |
15078 | (if (listp value) | |
15079 | (mapcar 'switch-to-buffer (nreverse value)) | |
15080 | (switch-to-buffer value)))) | |
15081 | @end ignore | |
15082 | ||
15083 | The definition I am showing possesses short but complete documentation | |
15084 | and an interactive specification that prompts you for a file name when | |
15085 | you use the command interactively. The body of the definition | |
15086 | contains two functions, @code{find-file-noselect} and | |
15087 | @code{switch-to-buffer}. | |
15088 | ||
15089 | According to its documentation as shown by @kbd{C-h f} (the | |
15090 | @code{describe-function} command), the @code{find-file-noselect} | |
15091 | function reads the named file into a buffer and returns the buffer. | |
15092 | (Its most recent version includes an optional wildcards argument, | |
15093 | too, as well as another to read a file literally and an other you | |
15094 | suppress warning messages. These optional arguments are irrelevant.) | |
15095 | ||
15096 | However, the @code{find-file-noselect} function does not select the | |
15097 | buffer in which it puts the file. Emacs does not switch its attention | |
15098 | (or yours if you are using @code{find-file-noselect}) to the selected | |
15099 | buffer. That is what @code{switch-to-buffer} does: it switches the | |
15100 | buffer to which Emacs attention is directed; and it switches the | |
15101 | buffer displayed in the window to the new buffer. We have discussed | |
15102 | buffer switching elsewhere. (@xref{Switching Buffers}.) | |
15103 | ||
15104 | In this histogram project, we do not need to display each file on the | |
15105 | screen as the program determines the length of each definition within | |
15106 | it. Instead of employing @code{switch-to-buffer}, we can work with | |
15107 | @code{set-buffer}, which redirects the attention of the computer | |
15108 | program to a different buffer but does not redisplay it on the screen. | |
15109 | So instead of calling on @code{find-file} to do the job, we must write | |
15110 | our own expression. | |
15111 | ||
15112 | The task is easy: use @code{find-file-noselect} and @code{set-buffer}. | |
15113 | ||
d6adf7e7 | 15114 | @node lengths-list-file |
8cda6f8f GM |
15115 | @section @code{lengths-list-file} in Detail |
15116 | ||
15117 | The core of the @code{lengths-list-file} function is a @code{while} | |
15118 | loop containing a function to move point forward `defun by defun' and | |
15119 | a function to count the number of words and symbols in each defun. | |
15120 | This core must be surrounded by functions that do various other tasks, | |
15121 | including finding the file, and ensuring that point starts out at the | |
15122 | beginning of the file. The function definition looks like this: | |
15123 | @findex lengths-list-file | |
15124 | ||
15125 | @smallexample | |
15126 | @group | |
15127 | (defun lengths-list-file (filename) | |
15128 | "Return list of definitions' lengths within FILE. | |
15129 | The returned list is a list of numbers. | |
15130 | Each number is the number of words or | |
15131 | symbols in one function definition." | |
15132 | @end group | |
15133 | @group | |
15134 | (message "Working on `%s' ... " filename) | |
15135 | (save-excursion | |
15136 | (let ((buffer (find-file-noselect filename)) | |
15137 | (lengths-list)) | |
15138 | (set-buffer buffer) | |
15139 | (setq buffer-read-only t) | |
15140 | (widen) | |
15141 | (goto-char (point-min)) | |
15142 | (while (re-search-forward "^(defun" nil t) | |
15143 | (setq lengths-list | |
15144 | (cons (count-words-in-defun) lengths-list))) | |
15145 | (kill-buffer buffer) | |
15146 | lengths-list))) | |
15147 | @end group | |
15148 | @end smallexample | |
15149 | ||
15150 | @noindent | |
15151 | The function is passed one argument, the name of the file on which it | |
15152 | will work. It has four lines of documentation, but no interactive | |
15153 | specification. Since people worry that a computer is broken if they | |
15154 | don't see anything going on, the first line of the body is a | |
15155 | message. | |
15156 | ||
44e97401 | 15157 | The next line contains a @code{save-excursion} that returns Emacs's |
8cda6f8f GM |
15158 | attention to the current buffer when the function completes. This is |
15159 | useful in case you embed this function in another function that | |
15160 | presumes point is restored to the original buffer. | |
15161 | ||
15162 | In the varlist of the @code{let} expression, Emacs finds the file and | |
15163 | binds the local variable @code{buffer} to the buffer containing the | |
15164 | file. At the same time, Emacs creates @code{lengths-list} as a local | |
15165 | variable. | |
15166 | ||
15167 | Next, Emacs switches its attention to the buffer. | |
15168 | ||
15169 | In the following line, Emacs makes the buffer read-only. Ideally, | |
15170 | this line is not necessary. None of the functions for counting words | |
15171 | and symbols in a function definition should change the buffer. | |
15172 | Besides, the buffer is not going to be saved, even if it were changed. | |
15173 | This line is entirely the consequence of great, perhaps excessive, | |
15174 | caution. The reason for the caution is that this function and those | |
15175 | it calls work on the sources for Emacs and it is inconvenient if they | |
15176 | are inadvertently modified. It goes without saying that I did not | |
15177 | realize a need for this line until an experiment went awry and started | |
15178 | to modify my Emacs source files @dots{} | |
15179 | ||
15180 | Next comes a call to widen the buffer if it is narrowed. This | |
15181 | function is usually not needed---Emacs creates a fresh buffer if none | |
15182 | already exists; but if a buffer visiting the file already exists Emacs | |
15183 | returns that one. In this case, the buffer may be narrowed and must | |
15184 | be widened. If we wanted to be fully `user-friendly', we would | |
15185 | arrange to save the restriction and the location of point, but we | |
15186 | won't. | |
15187 | ||
15188 | The @code{(goto-char (point-min))} expression moves point to the | |
15189 | beginning of the buffer. | |
15190 | ||
15191 | Then comes a @code{while} loop in which the `work' of the function is | |
15192 | carried out. In the loop, Emacs determines the length of each | |
15193 | definition and constructs a lengths' list containing the information. | |
15194 | ||
15195 | Emacs kills the buffer after working through it. This is to save | |
15196 | space inside of Emacs. My version of GNU Emacs 19 contained over 300 | |
15197 | source files of interest; GNU Emacs 22 contains over a thousand source | |
15198 | files. Another function will apply @code{lengths-list-file} to each | |
15199 | of the files. | |
15200 | ||
15201 | Finally, the last expression within the @code{let} expression is the | |
15202 | @code{lengths-list} variable; its value is returned as the value of | |
15203 | the whole function. | |
15204 | ||
15205 | You can try this function by installing it in the usual fashion. Then | |
15206 | place your cursor after the following expression and type @kbd{C-x | |
15207 | C-e} (@code{eval-last-sexp}). | |
15208 | ||
15209 | @c !!! 22.1.1 lisp sources location here | |
15210 | @smallexample | |
15211 | (lengths-list-file | |
15212 | "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el") | |
15213 | @end smallexample | |
15214 | ||
15215 | @noindent | |
15216 | (You may need to change the pathname of the file; the one here is for | |
15217 | GNU Emacs version 22.1.1. To change the expression, copy it to | |
15218 | the @file{*scratch*} buffer and edit it. | |
15219 | ||
15220 | @need 1200 | |
15221 | @noindent | |
15222 | (Also, to see the full length of the list, rather than a truncated | |
15223 | version, you may have to evaluate the following: | |
15224 | ||
15225 | @smallexample | |
15226 | (custom-set-variables '(eval-expression-print-length nil)) | |
15227 | @end smallexample | |
15228 | ||
15229 | @noindent | |
15230 | (@xref{defcustom, , Specifying Variables using @code{defcustom}}. | |
15231 | Then evaluate the @code{lengths-list-file} expression.) | |
15232 | ||
15233 | @need 1200 | |
15234 | The lengths' list for @file{debug.el} takes less than a second to | |
15235 | produce and looks like this in GNU Emacs 22: | |
15236 | ||
15237 | @smallexample | |
15238 | (83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587) | |
15239 | @end smallexample | |
15240 | ||
15241 | @need 1500 | |
15242 | (Using my old machine, the version 19 lengths' list for @file{debug.el} | |
15243 | took seven seconds to produce and looked like this: | |
15244 | ||
15245 | @smallexample | |
15246 | (75 41 80 62 20 45 44 68 45 12 34 235) | |
15247 | @end smallexample | |
15248 | ||
15249 | (The newer version of @file{debug.el} contains more defuns than the | |
15250 | earlier one; and my new machine is much faster than the old one.) | |
15251 | ||
15252 | Note that the length of the last definition in the file is first in | |
15253 | the list. | |
15254 | ||
d6adf7e7 | 15255 | @node Several files |
8cda6f8f GM |
15256 | @section Count Words in @code{defuns} in Different Files |
15257 | ||
15258 | In the previous section, we created a function that returns a list of | |
15259 | the lengths of each definition in a file. Now, we want to define a | |
15260 | function to return a master list of the lengths of the definitions in | |
15261 | a list of files. | |
15262 | ||
15263 | Working on each of a list of files is a repetitious act, so we can use | |
15264 | either a @code{while} loop or recursion. | |
15265 | ||
15266 | @menu | |
15267 | * lengths-list-many-files:: Return a list of the lengths of defuns. | |
15268 | * append:: Attach one list to another. | |
15269 | @end menu | |
15270 | ||
8cda6f8f | 15271 | @ifnottex |
d6adf7e7 | 15272 | @node lengths-list-many-files |
8cda6f8f GM |
15273 | @unnumberedsubsec Determine the lengths of @code{defuns} |
15274 | @end ifnottex | |
15275 | ||
15276 | The design using a @code{while} loop is routine. The argument passed | |
15277 | the function is a list of files. As we saw earlier (@pxref{Loop | |
15278 | Example}), you can write a @code{while} loop so that the body of the | |
15279 | loop is evaluated if such a list contains elements, but to exit the | |
15280 | loop if the list is empty. For this design to work, the body of the | |
15281 | loop must contain an expression that shortens the list each time the | |
15282 | body is evaluated, so that eventually the list is empty. The usual | |
15283 | technique is to set the value of the list to the value of the @sc{cdr} | |
15284 | of the list each time the body is evaluated. | |
15285 | ||
15286 | @need 800 | |
15287 | The template looks like this: | |
15288 | ||
15289 | @smallexample | |
15290 | @group | |
15291 | (while @var{test-whether-list-is-empty} | |
15292 | @var{body}@dots{} | |
15293 | @var{set-list-to-cdr-of-list}) | |
15294 | @end group | |
15295 | @end smallexample | |
15296 | ||
15297 | Also, we remember that a @code{while} loop returns @code{nil} (the | |
15298 | result of evaluating the true-or-false-test), not the result of any | |
15299 | evaluation within its body. (The evaluations within the body of the | |
15300 | loop are done for their side effects.) However, the expression that | |
15301 | sets the lengths' list is part of the body---and that is the value | |
15302 | that we want returned by the function as a whole. To do this, we | |
15303 | enclose the @code{while} loop within a @code{let} expression, and | |
15304 | arrange that the last element of the @code{let} expression contains | |
15305 | the value of the lengths' list. (@xref{Incrementing Example, , Loop | |
15306 | Example with an Incrementing Counter}.) | |
15307 | ||
15308 | @findex lengths-list-many-files | |
15309 | @need 1250 | |
15310 | These considerations lead us directly to the function itself: | |
15311 | ||
15312 | @smallexample | |
15313 | @group | |
15314 | ;;; @r{Use @code{while} loop.} | |
15315 | (defun lengths-list-many-files (list-of-files) | |
15316 | "Return list of lengths of defuns in LIST-OF-FILES." | |
15317 | @end group | |
15318 | @group | |
15319 | (let (lengths-list) | |
15320 | ||
15321 | ;;; @r{true-or-false-test} | |
15322 | (while list-of-files | |
15323 | (setq lengths-list | |
15324 | (append | |
15325 | lengths-list | |
15326 | ||
15327 | ;;; @r{Generate a lengths' list.} | |
15328 | (lengths-list-file | |
15329 | (expand-file-name (car list-of-files))))) | |
15330 | @end group | |
15331 | ||
15332 | @group | |
15333 | ;;; @r{Make files' list shorter.} | |
15334 | (setq list-of-files (cdr list-of-files))) | |
15335 | ||
15336 | ;;; @r{Return final value of lengths' list.} | |
15337 | lengths-list)) | |
15338 | @end group | |
15339 | @end smallexample | |
15340 | ||
15341 | @code{expand-file-name} is a built-in function that converts a file | |
15342 | name to the absolute, long, path name form. The function employs the | |
15343 | name of the directory in which the function is called. | |
15344 | ||
15345 | @c !!! 22.1.1 lisp sources location here | |
15346 | @need 1500 | |
15347 | Thus, if @code{expand-file-name} is called on @code{debug.el} when | |
15348 | Emacs is visiting the | |
15349 | @file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory, | |
15350 | ||
15351 | @smallexample | |
15352 | debug.el | |
15353 | @end smallexample | |
15354 | ||
15355 | @need 800 | |
15356 | @noindent | |
15357 | becomes | |
15358 | ||
15359 | @c !!! 22.1.1 lisp sources location here | |
15360 | @smallexample | |
15361 | /usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el | |
15362 | @end smallexample | |
15363 | ||
15364 | The only other new element of this function definition is the as yet | |
15365 | unstudied function @code{append}, which merits a short section for | |
15366 | itself. | |
15367 | ||
d6adf7e7 | 15368 | @node append |
8cda6f8f GM |
15369 | @subsection The @code{append} Function |
15370 | ||
15371 | @need 800 | |
15372 | The @code{append} function attaches one list to another. Thus, | |
15373 | ||
15374 | @smallexample | |
15375 | (append '(1 2 3 4) '(5 6 7 8)) | |
15376 | @end smallexample | |
15377 | ||
15378 | @need 800 | |
15379 | @noindent | |
15380 | produces the list | |
15381 | ||
15382 | @smallexample | |
15383 | (1 2 3 4 5 6 7 8) | |
15384 | @end smallexample | |
15385 | ||
15386 | This is exactly how we want to attach two lengths' lists produced by | |
15387 | @code{lengths-list-file} to each other. The results contrast with | |
15388 | @code{cons}, | |
15389 | ||
15390 | @smallexample | |
15391 | (cons '(1 2 3 4) '(5 6 7 8)) | |
15392 | @end smallexample | |
15393 | ||
15394 | @need 1250 | |
15395 | @noindent | |
15396 | which constructs a new list in which the first argument to @code{cons} | |
15397 | becomes the first element of the new list: | |
15398 | ||
15399 | @smallexample | |
15400 | ((1 2 3 4) 5 6 7 8) | |
15401 | @end smallexample | |
15402 | ||
d6adf7e7 | 15403 | @node Several files recursively |
8cda6f8f GM |
15404 | @section Recursively Count Words in Different Files |
15405 | ||
15406 | Besides a @code{while} loop, you can work on each of a list of files | |
15407 | with recursion. A recursive version of @code{lengths-list-many-files} | |
15408 | is short and simple. | |
15409 | ||
15410 | The recursive function has the usual parts: the `do-again-test', the | |
15411 | `next-step-expression', and the recursive call. The `do-again-test' | |
15412 | determines whether the function should call itself again, which it | |
15413 | will do if the @code{list-of-files} contains any remaining elements; | |
15414 | the `next-step-expression' resets the @code{list-of-files} to the | |
15415 | @sc{cdr} of itself, so eventually the list will be empty; and the | |
15416 | recursive call calls itself on the shorter list. The complete | |
15417 | function is shorter than this description! | |
15418 | @findex recursive-lengths-list-many-files | |
15419 | ||
15420 | @smallexample | |
15421 | @group | |
15422 | (defun recursive-lengths-list-many-files (list-of-files) | |
15423 | "Return list of lengths of each defun in LIST-OF-FILES." | |
15424 | (if list-of-files ; @r{do-again-test} | |
15425 | (append | |
15426 | (lengths-list-file | |
15427 | (expand-file-name (car list-of-files))) | |
15428 | (recursive-lengths-list-many-files | |
15429 | (cdr list-of-files))))) | |
15430 | @end group | |
15431 | @end smallexample | |
15432 | ||
15433 | @noindent | |
15434 | In a sentence, the function returns the lengths' list for the first of | |
15435 | the @code{list-of-files} appended to the result of calling itself on | |
15436 | the rest of the @code{list-of-files}. | |
15437 | ||
15438 | Here is a test of @code{recursive-lengths-list-many-files}, along with | |
15439 | the results of running @code{lengths-list-file} on each of the files | |
15440 | individually. | |
15441 | ||
15442 | Install @code{recursive-lengths-list-many-files} and | |
15443 | @code{lengths-list-file}, if necessary, and then evaluate the | |
15444 | following expressions. You may need to change the files' pathnames; | |
15445 | those here work when this Info file and the Emacs sources are located | |
15446 | in their customary places. To change the expressions, copy them to | |
15447 | the @file{*scratch*} buffer, edit them, and then evaluate them. | |
15448 | ||
15449 | The results are shown after the @samp{@result{}}. (These results are | |
15450 | for files from Emacs version 22.1.1; files from other versions of | |
15451 | Emacs may produce different results.) | |
15452 | ||
15453 | @c !!! 22.1.1 lisp sources location here | |
15454 | @smallexample | |
15455 | @group | |
15456 | (cd "/usr/local/share/emacs/22.1.1/") | |
15457 | ||
15458 | (lengths-list-file "./lisp/macros.el") | |
15459 | @result{} (283 263 480 90) | |
15460 | @end group | |
15461 | ||
15462 | @group | |
15463 | (lengths-list-file "./lisp/mail/mailalias.el") | |
15464 | @result{} (38 32 29 95 178 180 321 218 324) | |
15465 | @end group | |
15466 | ||
15467 | @group | |
15468 | (lengths-list-file "./lisp/makesum.el") | |
15469 | @result{} (85 181) | |
15470 | @end group | |
15471 | ||
15472 | @group | |
15473 | (recursive-lengths-list-many-files | |
15474 | '("./lisp/macros.el" | |
15475 | "./lisp/mail/mailalias.el" | |
15476 | "./lisp/makesum.el")) | |
15477 | @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181) | |
15478 | @end group | |
15479 | @end smallexample | |
15480 | ||
15481 | The @code{recursive-lengths-list-many-files} function produces the | |
15482 | output we want. | |
15483 | ||
15484 | The next step is to prepare the data in the list for display in a graph. | |
15485 | ||
d6adf7e7 | 15486 | @node Prepare the data |
8cda6f8f GM |
15487 | @section Prepare the Data for Display in a Graph |
15488 | ||
15489 | The @code{recursive-lengths-list-many-files} function returns a list | |
15490 | of numbers. Each number records the length of a function definition. | |
15491 | What we need to do now is transform this data into a list of numbers | |
15492 | suitable for generating a graph. The new list will tell how many | |
15493 | functions definitions contain less than 10 words and | |
15494 | symbols, how many contain between 10 and 19 words and symbols, how | |
15495 | many contain between 20 and 29 words and symbols, and so on. | |
15496 | ||
15497 | In brief, we need to go through the lengths' list produced by the | |
15498 | @code{recursive-lengths-list-many-files} function and count the number | |
15499 | of defuns within each range of lengths, and produce a list of those | |
15500 | numbers. | |
15501 | ||
15502 | @menu | |
15503 | * Data for Display in Detail:: | |
15504 | * Sorting:: Sorting lists. | |
15505 | * Files List:: Making a list of files. | |
15506 | * Counting function definitions:: | |
15507 | @end menu | |
15508 | ||
8cda6f8f | 15509 | @ifnottex |
d6adf7e7 | 15510 | @node Data for Display in Detail |
8cda6f8f GM |
15511 | @unnumberedsubsec The Data for Display in Detail |
15512 | @end ifnottex | |
15513 | ||
15514 | Based on what we have done before, we can readily foresee that it | |
15515 | should not be too hard to write a function that `@sc{cdr}s' down the | |
15516 | lengths' list, looks at each element, determines which length range it | |
15517 | is in, and increments a counter for that range. | |
15518 | ||
15519 | However, before beginning to write such a function, we should consider | |
15520 | the advantages of sorting the lengths' list first, so the numbers are | |
15521 | ordered from smallest to largest. First, sorting will make it easier | |
15522 | to count the numbers in each range, since two adjacent numbers will | |
15523 | either be in the same length range or in adjacent ranges. Second, by | |
15524 | inspecting a sorted list, we can discover the highest and lowest | |
15525 | number, and thereby determine the largest and smallest length range | |
15526 | that we will need. | |
15527 | ||
d6adf7e7 | 15528 | @node Sorting |
8cda6f8f GM |
15529 | @subsection Sorting Lists |
15530 | @findex sort | |
15531 | ||
15532 | Emacs contains a function to sort lists, called (as you might guess) | |
15533 | @code{sort}. The @code{sort} function takes two arguments, the list | |
15534 | to be sorted, and a predicate that determines whether the first of | |
15535 | two list elements is ``less'' than the second. | |
15536 | ||
15537 | As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong | |
15538 | Type Object as an Argument}), a predicate is a function that | |
15539 | determines whether some property is true or false. The @code{sort} | |
15540 | function will reorder a list according to whatever property the | |
15541 | predicate uses; this means that @code{sort} can be used to sort | |
15542 | non-numeric lists by non-numeric criteria---it can, for example, | |
15543 | alphabetize a list. | |
15544 | ||
15545 | @need 1250 | |
15546 | The @code{<} function is used when sorting a numeric list. For example, | |
15547 | ||
15548 | @smallexample | |
15549 | (sort '(4 8 21 17 33 7 21 7) '<) | |
15550 | @end smallexample | |
15551 | ||
15552 | @need 800 | |
15553 | @noindent | |
15554 | produces this: | |
15555 | ||
15556 | @smallexample | |
15557 | (4 7 7 8 17 21 21 33) | |
15558 | @end smallexample | |
15559 | ||
15560 | @noindent | |
15561 | (Note that in this example, both the arguments are quoted so that the | |
15562 | symbols are not evaluated before being passed to @code{sort} as | |
15563 | arguments.) | |
15564 | ||
15565 | Sorting the list returned by the | |
15566 | @code{recursive-lengths-list-many-files} function is straightforward; | |
15567 | it uses the @code{<} function: | |
15568 | ||
15569 | @ignore | |
15570 | 2006 Oct 29 | |
15571 | In GNU Emacs 22, eval | |
15572 | (progn | |
15573 | (cd "/usr/local/share/emacs/22.0.50/") | |
15574 | (sort | |
15575 | (recursive-lengths-list-many-files | |
15576 | '("./lisp/macros.el" | |
15577 | "./lisp/mail/mailalias.el" | |
15578 | "./lisp/makesum.el")) | |
15579 | '<)) | |
15580 | ||
15581 | @end ignore | |
15582 | ||
15583 | @smallexample | |
15584 | @group | |
15585 | (sort | |
15586 | (recursive-lengths-list-many-files | |
15587 | '("./lisp/macros.el" | |
15588 | "./lisp/mailalias.el" | |
15589 | "./lisp/makesum.el")) | |
15590 | '<) | |
15591 | @end group | |
15592 | @end smallexample | |
15593 | ||
15594 | @need 800 | |
15595 | @noindent | |
15596 | which produces: | |
15597 | ||
15598 | @smallexample | |
15599 | (29 32 38 85 90 95 178 180 181 218 263 283 321 324 480) | |
15600 | @end smallexample | |
15601 | ||
15602 | @noindent | |
15603 | (Note that in this example, the first argument to @code{sort} is not | |
15604 | quoted, since the expression must be evaluated so as to produce the | |
15605 | list that is passed to @code{sort}.) | |
15606 | ||
d6adf7e7 | 15607 | @node Files List |
8cda6f8f GM |
15608 | @subsection Making a List of Files |
15609 | ||
15610 | The @code{recursive-lengths-list-many-files} function requires a list | |
15611 | of files as its argument. For our test examples, we constructed such | |
15612 | a list by hand; but the Emacs Lisp source directory is too large for | |
15613 | us to do for that. Instead, we will write a function to do the job | |
15614 | for us. In this function, we will use both a @code{while} loop and a | |
15615 | recursive call. | |
15616 | ||
15617 | @findex directory-files | |
15618 | We did not have to write a function like this for older versions of | |
15619 | GNU Emacs, since they placed all the @samp{.el} files in one | |
15620 | directory. Instead, we were able to use the @code{directory-files} | |
15621 | function, which lists the names of files that match a specified | |
15622 | pattern within a single directory. | |
15623 | ||
15624 | However, recent versions of Emacs place Emacs Lisp files in | |
15625 | sub-directories of the top level @file{lisp} directory. This | |
15626 | re-arrangement eases navigation. For example, all the mail related | |
15627 | files are in a @file{lisp} sub-directory called @file{mail}. But at | |
15628 | the same time, this arrangement forces us to create a file listing | |
15629 | function that descends into the sub-directories. | |
15630 | ||
15631 | @findex files-in-below-directory | |
15632 | We can create this function, called @code{files-in-below-directory}, | |
15633 | using familiar functions such as @code{car}, @code{nthcdr}, and | |
15634 | @code{substring} in conjunction with an existing function called | |
15635 | @code{directory-files-and-attributes}. This latter function not only | |
15636 | lists all the filenames in a directory, including the names | |
15637 | of sub-directories, but also their attributes. | |
15638 | ||
15639 | To restate our goal: to create a function that will enable us | |
15640 | to feed filenames to @code{recursive-lengths-list-many-files} | |
15641 | as a list that looks like this (but with more elements): | |
15642 | ||
15643 | @smallexample | |
15644 | @group | |
15645 | ("./lisp/macros.el" | |
15646 | "./lisp/mail/rmail.el" | |
15647 | "./lisp/makesum.el") | |
15648 | @end group | |
15649 | @end smallexample | |
15650 | ||
15651 | The @code{directory-files-and-attributes} function returns a list of | |
15652 | lists. Each of the lists within the main list consists of 13 | |
15653 | elements. The first element is a string that contains the name of the | |
f99f1641 | 15654 | file---which, in GNU/Linux, may be a `directory file', that is to |
8cda6f8f GM |
15655 | say, a file with the special attributes of a directory. The second |
15656 | element of the list is @code{t} for a directory, a string | |
15657 | for symbolic link (the string is the name linked to), or @code{nil}. | |
15658 | ||
15659 | For example, the first @samp{.el} file in the @file{lisp/} directory | |
15660 | is @file{abbrev.el}. Its name is | |
15661 | @file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a | |
15662 | directory or a symbolic link. | |
15663 | ||
15664 | @need 1000 | |
15665 | This is how @code{directory-files-and-attributes} lists that file and | |
15666 | its attributes: | |
15667 | ||
15668 | @smallexample | |
15669 | @group | |
15670 | ("abbrev.el" | |
15671 | nil | |
15672 | 1 | |
15673 | 1000 | |
15674 | 100 | |
15675 | @end group | |
15676 | @group | |
72ec96fb PE |
15677 | (20615 27034 579989 697000) |
15678 | (17905 55681 0 0) | |
15679 | (20615 26327 734791 805000) | |
15680 | 13188 | |
15681 | "-rw-r--r--" | |
8cda6f8f GM |
15682 | @end group |
15683 | @group | |
97976f9f | 15684 | t |
8cda6f8f GM |
15685 | 2971624 |
15686 | 773) | |
15687 | @end group | |
15688 | @end smallexample | |
15689 | ||
15690 | @need 1200 | |
15691 | On the other hand, @file{mail/} is a directory within the @file{lisp/} | |
15692 | directory. The beginning of its listing looks like this: | |
15693 | ||
15694 | @smallexample | |
15695 | @group | |
15696 | ("mail" | |
15697 | t | |
15698 | @dots{} | |
15699 | ) | |
15700 | @end group | |
15701 | @end smallexample | |
15702 | ||
15703 | (To learn about the different attributes, look at the documentation of | |
15704 | @code{file-attributes}. Bear in mind that the @code{file-attributes} | |
15705 | function does not list the filename, so its first element is | |
15706 | @code{directory-files-and-attributes}'s second element.) | |
15707 | ||
15708 | We will want our new function, @code{files-in-below-directory}, to | |
15709 | list the @samp{.el} files in the directory it is told to check, and in | |
15710 | any directories below that directory. | |
15711 | ||
15712 | This gives us a hint on how to construct | |
15713 | @code{files-in-below-directory}: within a directory, the function | |
15714 | should add @samp{.el} filenames to a list; and if, within a directory, | |
15715 | the function comes upon a sub-directory, it should go into that | |
15716 | sub-directory and repeat its actions. | |
15717 | ||
15718 | However, we should note that every directory contains a name that | |
15719 | refers to itself, called @file{.}, (``dot'') and a name that refers to | |
15720 | its parent directory, called @file{..} (``double dot''). (In | |
15721 | @file{/}, the root directory, @file{..} refers to itself, since | |
15722 | @file{/} has no parent.) Clearly, we do not want our | |
15723 | @code{files-in-below-directory} function to enter those directories, | |
15724 | since they always lead us, directly or indirectly, to the current | |
15725 | directory. | |
15726 | ||
15727 | Consequently, our @code{files-in-below-directory} function must do | |
15728 | several tasks: | |
15729 | ||
15730 | @itemize @bullet | |
15731 | @item | |
15732 | Check to see whether it is looking at a filename that ends in | |
15733 | @samp{.el}; and if so, add its name to a list. | |
15734 | ||
15735 | @item | |
15736 | Check to see whether it is looking at a filename that is the name of a | |
15737 | directory; and if so, | |
15738 | ||
15739 | @itemize @minus | |
15740 | @item | |
15741 | Check to see whether it is looking at @file{.} or @file{..}; and if | |
15742 | so skip it. | |
15743 | ||
15744 | @item | |
15745 | Or else, go into that directory and repeat the process. | |
15746 | @end itemize | |
15747 | @end itemize | |
15748 | ||
15749 | Let's write a function definition to do these tasks. We will use a | |
15750 | @code{while} loop to move from one filename to another within a | |
15751 | directory, checking what needs to be done; and we will use a recursive | |
15752 | call to repeat the actions on each sub-directory. The recursive | |
15753 | pattern is `accumulate' | |
15754 | (@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}), | |
15755 | using @code{append} as the combiner. | |
15756 | ||
15757 | @ignore | |
15758 | (directory-files "/usr/local/src/emacs/lisp/" t "\\.el$") | |
15759 | (shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'") | |
15760 | ||
15761 | (directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$") | |
15762 | (shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'") | |
15763 | @end ignore | |
15764 | ||
15765 | @c /usr/local/share/emacs/22.1.1/lisp/ | |
15766 | ||
15767 | @need 800 | |
15768 | Here is the function: | |
15769 | ||
15770 | @smallexample | |
15771 | @group | |
15772 | (defun files-in-below-directory (directory) | |
15773 | "List the .el files in DIRECTORY and in its sub-directories." | |
15774 | ;; Although the function will be used non-interactively, | |
15775 | ;; it will be easier to test if we make it interactive. | |
15776 | ;; The directory will have a name such as | |
15777 | ;; "/usr/local/share/emacs/22.1.1/lisp/" | |
15778 | (interactive "DDirectory name: ") | |
15779 | @end group | |
15780 | @group | |
15781 | (let (el-files-list | |
15782 | (current-directory-list | |
15783 | (directory-files-and-attributes directory t))) | |
15784 | ;; while we are in the current directory | |
15785 | (while current-directory-list | |
15786 | @end group | |
15787 | @group | |
15788 | (cond | |
15789 | ;; check to see whether filename ends in `.el' | |
15790 | ;; and if so, append its name to a list. | |
15791 | ((equal ".el" (substring (car (car current-directory-list)) -3)) | |
15792 | (setq el-files-list | |
15793 | (cons (car (car current-directory-list)) el-files-list))) | |
15794 | @end group | |
15795 | @group | |
15796 | ;; check whether filename is that of a directory | |
15797 | ((eq t (car (cdr (car current-directory-list)))) | |
15798 | ;; decide whether to skip or recurse | |
15799 | (if | |
15800 | (equal "." | |
15801 | (substring (car (car current-directory-list)) -1)) | |
15802 | ;; then do nothing since filename is that of | |
15803 | ;; current directory or parent, "." or ".." | |
15804 | () | |
15805 | @end group | |
15806 | @group | |
15807 | ;; else descend into the directory and repeat the process | |
15808 | (setq el-files-list | |
15809 | (append | |
15810 | (files-in-below-directory | |
15811 | (car (car current-directory-list))) | |
15812 | el-files-list))))) | |
15813 | ;; move to the next filename in the list; this also | |
15814 | ;; shortens the list so the while loop eventually comes to an end | |
15815 | (setq current-directory-list (cdr current-directory-list))) | |
15816 | ;; return the filenames | |
15817 | el-files-list)) | |
15818 | @end group | |
15819 | @end smallexample | |
15820 | ||
15821 | @c (files-in-below-directory "/usr/local/src/emacs/lisp/") | |
15822 | @c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") | |
15823 | ||
15824 | The @code{files-in-below-directory} @code{directory-files} function | |
15825 | takes one argument, the name of a directory. | |
15826 | ||
15827 | @need 1250 | |
15828 | Thus, on my system, | |
15829 | ||
15830 | @c (length (files-in-below-directory "/usr/local/src/emacs/lisp/")) | |
15831 | ||
15832 | @c !!! 22.1.1 lisp sources location here | |
15833 | @smallexample | |
15834 | @group | |
15835 | (length | |
15836 | (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")) | |
15837 | @end group | |
15838 | @end smallexample | |
15839 | ||
15840 | @noindent | |
15841 | tells me that in and below my Lisp sources directory are 1031 | |
15842 | @samp{.el} files. | |
15843 | ||
15844 | @code{files-in-below-directory} returns a list in reverse alphabetical | |
15845 | order. An expression to sort the list in alphabetical order looks | |
15846 | like this: | |
15847 | ||
15848 | @smallexample | |
15849 | @group | |
15850 | (sort | |
15851 | (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") | |
15852 | 'string-lessp) | |
15853 | @end group | |
15854 | @end smallexample | |
15855 | ||
15856 | @ignore | |
15857 | (defun test () | |
15858 | "Test how long it takes to find lengths of all sorted elisp defuns." | |
15859 | (insert "\n" (current-time-string) "\n") | |
15860 | (sit-for 0) | |
15861 | (sort | |
15862 | (recursive-lengths-list-many-files | |
15863 | (files-in-below-directory "/usr/local/src/emacs/lisp/")) | |
15864 | '<) | |
15865 | (insert (format "%s" (current-time-string)))) | |
15866 | @end ignore | |
15867 | ||
d6adf7e7 | 15868 | @node Counting function definitions |
8cda6f8f GM |
15869 | @subsection Counting function definitions |
15870 | ||
15871 | Our immediate goal is to generate a list that tells us how many | |
15872 | function definitions contain fewer than 10 words and symbols, how many | |
15873 | contain between 10 and 19 words and symbols, how many contain between | |
15874 | 20 and 29 words and symbols, and so on. | |
15875 | ||
15876 | With a sorted list of numbers, this is easy: count how many elements | |
15877 | of the list are smaller than 10, then, after moving past the numbers | |
15878 | just counted, count how many are smaller than 20, then, after moving | |
15879 | past the numbers just counted, count how many are smaller than 30, and | |
15880 | so on. Each of the numbers, 10, 20, 30, 40, and the like, is one | |
15881 | larger than the top of that range. We can call the list of such | |
15882 | numbers the @code{top-of-ranges} list. | |
15883 | ||
15884 | @need 1200 | |
15885 | If we wished, we could generate this list automatically, but it is | |
15886 | simpler to write a list manually. Here it is: | |
15887 | @vindex top-of-ranges | |
15888 | ||
15889 | @smallexample | |
15890 | @group | |
15891 | (defvar top-of-ranges | |
15892 | '(10 20 30 40 50 | |
15893 | 60 70 80 90 100 | |
15894 | 110 120 130 140 150 | |
15895 | 160 170 180 190 200 | |
15896 | 210 220 230 240 250 | |
15897 | 260 270 280 290 300) | |
15898 | "List specifying ranges for `defuns-per-range'.") | |
15899 | @end group | |
15900 | @end smallexample | |
15901 | ||
15902 | To change the ranges, we edit this list. | |
15903 | ||
15904 | Next, we need to write the function that creates the list of the | |
15905 | number of definitions within each range. Clearly, this function must | |
15906 | take the @code{sorted-lengths} and the @code{top-of-ranges} lists | |
15907 | as arguments. | |
15908 | ||
15909 | The @code{defuns-per-range} function must do two things again and | |
15910 | again: it must count the number of definitions within a range | |
15911 | specified by the current top-of-range value; and it must shift to the | |
15912 | next higher value in the @code{top-of-ranges} list after counting the | |
15913 | number of definitions in the current range. Since each of these | |
15914 | actions is repetitive, we can use @code{while} loops for the job. | |
15915 | One loop counts the number of definitions in the range defined by the | |
15916 | current top-of-range value, and the other loop selects each of the | |
15917 | top-of-range values in turn. | |
15918 | ||
15919 | Several entries of the @code{sorted-lengths} list are counted for each | |
15920 | range; this means that the loop for the @code{sorted-lengths} list | |
15921 | will be inside the loop for the @code{top-of-ranges} list, like a | |
15922 | small gear inside a big gear. | |
15923 | ||
15924 | The inner loop counts the number of definitions within the range. It | |
15925 | is a simple counting loop of the type we have seen before. | |
15926 | (@xref{Incrementing Loop, , A loop with an incrementing counter}.) | |
15927 | The true-or-false test of the loop tests whether the value from the | |
15928 | @code{sorted-lengths} list is smaller than the current value of the | |
15929 | top of the range. If it is, the function increments the counter and | |
15930 | tests the next value from the @code{sorted-lengths} list. | |
15931 | ||
15932 | @need 1250 | |
15933 | The inner loop looks like this: | |
15934 | ||
15935 | @smallexample | |
15936 | @group | |
15937 | (while @var{length-element-smaller-than-top-of-range} | |
15938 | (setq number-within-range (1+ number-within-range)) | |
15939 | (setq sorted-lengths (cdr sorted-lengths))) | |
15940 | @end group | |
15941 | @end smallexample | |
15942 | ||
15943 | The outer loop must start with the lowest value of the | |
15944 | @code{top-of-ranges} list, and then be set to each of the succeeding | |
15945 | higher values in turn. This can be done with a loop like this: | |
15946 | ||
15947 | @smallexample | |
15948 | @group | |
15949 | (while top-of-ranges | |
15950 | @var{body-of-loop}@dots{} | |
15951 | (setq top-of-ranges (cdr top-of-ranges))) | |
15952 | @end group | |
15953 | @end smallexample | |
15954 | ||
15955 | @need 1200 | |
15956 | Put together, the two loops look like this: | |
15957 | ||
15958 | @smallexample | |
15959 | @group | |
15960 | (while top-of-ranges | |
15961 | ||
15962 | ;; @r{Count the number of elements within the current range.} | |
15963 | (while @var{length-element-smaller-than-top-of-range} | |
15964 | (setq number-within-range (1+ number-within-range)) | |
15965 | (setq sorted-lengths (cdr sorted-lengths))) | |
15966 | ||
15967 | ;; @r{Move to next range.} | |
15968 | (setq top-of-ranges (cdr top-of-ranges))) | |
15969 | @end group | |
15970 | @end smallexample | |
15971 | ||
15972 | In addition, in each circuit of the outer loop, Emacs should record | |
15973 | the number of definitions within that range (the value of | |
15974 | @code{number-within-range}) in a list. We can use @code{cons} for | |
15975 | this purpose. (@xref{cons, , @code{cons}}.) | |
15976 | ||
15977 | The @code{cons} function works fine, except that the list it | |
15978 | constructs will contain the number of definitions for the highest | |
15979 | range at its beginning and the number of definitions for the lowest | |
15980 | range at its end. This is because @code{cons} attaches new elements | |
15981 | of the list to the beginning of the list, and since the two loops are | |
15982 | working their way through the lengths' list from the lower end first, | |
15983 | the @code{defuns-per-range-list} will end up largest number first. | |
15984 | But we will want to print our graph with smallest values first and the | |
15985 | larger later. The solution is to reverse the order of the | |
15986 | @code{defuns-per-range-list}. We can do this using the | |
15987 | @code{nreverse} function, which reverses the order of a list. | |
15988 | @findex nreverse | |
15989 | ||
15990 | @need 800 | |
15991 | For example, | |
15992 | ||
15993 | @smallexample | |
15994 | (nreverse '(1 2 3 4)) | |
15995 | @end smallexample | |
15996 | ||
15997 | @need 800 | |
15998 | @noindent | |
15999 | produces: | |
16000 | ||
16001 | @smallexample | |
16002 | (4 3 2 1) | |
16003 | @end smallexample | |
16004 | ||
16005 | Note that the @code{nreverse} function is ``destructive''---that is, | |
16006 | it changes the list to which it is applied; this contrasts with the | |
16007 | @code{car} and @code{cdr} functions, which are non-destructive. In | |
16008 | this case, we do not want the original @code{defuns-per-range-list}, | |
16009 | so it does not matter that it is destroyed. (The @code{reverse} | |
16010 | function provides a reversed copy of a list, leaving the original list | |
16011 | as is.) | |
16012 | @findex reverse | |
16013 | ||
16014 | @need 1250 | |
16015 | Put all together, the @code{defuns-per-range} looks like this: | |
16016 | ||
16017 | @smallexample | |
16018 | @group | |
16019 | (defun defuns-per-range (sorted-lengths top-of-ranges) | |
16020 | "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." | |
16021 | (let ((top-of-range (car top-of-ranges)) | |
16022 | (number-within-range 0) | |
16023 | defuns-per-range-list) | |
16024 | @end group | |
16025 | ||
16026 | @group | |
16027 | ;; @r{Outer loop.} | |
16028 | (while top-of-ranges | |
16029 | @end group | |
16030 | ||
16031 | @group | |
16032 | ;; @r{Inner loop.} | |
16033 | (while (and | |
16034 | ;; @r{Need number for numeric test.} | |
16035 | (car sorted-lengths) | |
16036 | (< (car sorted-lengths) top-of-range)) | |
16037 | @end group | |
16038 | ||
16039 | @group | |
16040 | ;; @r{Count number of definitions within current range.} | |
16041 | (setq number-within-range (1+ number-within-range)) | |
16042 | (setq sorted-lengths (cdr sorted-lengths))) | |
16043 | ||
16044 | ;; @r{Exit inner loop but remain within outer loop.} | |
16045 | @end group | |
16046 | ||
16047 | @group | |
16048 | (setq defuns-per-range-list | |
16049 | (cons number-within-range defuns-per-range-list)) | |
16050 | (setq number-within-range 0) ; @r{Reset count to zero.} | |
16051 | @end group | |
16052 | ||
16053 | @group | |
16054 | ;; @r{Move to next range.} | |
16055 | (setq top-of-ranges (cdr top-of-ranges)) | |
16056 | ;; @r{Specify next top of range value.} | |
16057 | (setq top-of-range (car top-of-ranges))) | |
16058 | @end group | |
16059 | ||
16060 | @group | |
16061 | ;; @r{Exit outer loop and count the number of defuns larger than} | |
16062 | ;; @r{ the largest top-of-range value.} | |
16063 | (setq defuns-per-range-list | |
16064 | (cons | |
16065 | (length sorted-lengths) | |
16066 | defuns-per-range-list)) | |
16067 | @end group | |
16068 | ||
16069 | @group | |
16070 | ;; @r{Return a list of the number of definitions within each range,} | |
16071 | ;; @r{ smallest to largest.} | |
16072 | (nreverse defuns-per-range-list))) | |
16073 | @end group | |
16074 | @end smallexample | |
16075 | ||
16076 | @need 1200 | |
16077 | @noindent | |
16078 | The function is straightforward except for one subtle feature. The | |
16079 | true-or-false test of the inner loop looks like this: | |
16080 | ||
16081 | @smallexample | |
16082 | @group | |
16083 | (and (car sorted-lengths) | |
16084 | (< (car sorted-lengths) top-of-range)) | |
16085 | @end group | |
16086 | @end smallexample | |
16087 | ||
16088 | @need 800 | |
16089 | @noindent | |
16090 | instead of like this: | |
16091 | ||
16092 | @smallexample | |
16093 | (< (car sorted-lengths) top-of-range) | |
16094 | @end smallexample | |
16095 | ||
16096 | The purpose of the test is to determine whether the first item in the | |
16097 | @code{sorted-lengths} list is less than the value of the top of the | |
16098 | range. | |
16099 | ||
16100 | The simple version of the test works fine unless the | |
16101 | @code{sorted-lengths} list has a @code{nil} value. In that case, the | |
16102 | @code{(car sorted-lengths)} expression function returns | |
16103 | @code{nil}. The @code{<} function cannot compare a number to | |
16104 | @code{nil}, which is an empty list, so Emacs signals an error and | |
16105 | stops the function from attempting to continue to execute. | |
16106 | ||
16107 | The @code{sorted-lengths} list always becomes @code{nil} when the | |
16108 | counter reaches the end of the list. This means that any attempt to | |
16109 | use the @code{defuns-per-range} function with the simple version of | |
16110 | the test will fail. | |
16111 | ||
16112 | We solve the problem by using the @code{(car sorted-lengths)} | |
16113 | expression in conjunction with the @code{and} expression. The | |
16114 | @code{(car sorted-lengths)} expression returns a non-@code{nil} | |
16115 | value so long as the list has at least one number within it, but | |
16116 | returns @code{nil} if the list is empty. The @code{and} expression | |
16117 | first evaluates the @code{(car sorted-lengths)} expression, and | |
16118 | if it is @code{nil}, returns false @emph{without} evaluating the | |
16119 | @code{<} expression. But if the @code{(car sorted-lengths)} | |
16120 | expression returns a non-@code{nil} value, the @code{and} expression | |
16121 | evaluates the @code{<} expression, and returns that value as the value | |
16122 | of the @code{and} expression. | |
16123 | ||
16124 | @c colon in printed section title causes problem in Info cross reference | |
16125 | This way, we avoid an error. | |
16126 | @iftex | |
16127 | @noindent | |
16128 | (For information about @code{and}, see | |
16129 | @ref{kill-new function, , The @code{kill-new} function}.) | |
16130 | @end iftex | |
16131 | @ifinfo | |
16132 | @noindent | |
16133 | (@xref{kill-new function, , The @code{kill-new} function}, for | |
16134 | information about @code{and}.) | |
16135 | @end ifinfo | |
16136 | ||
16137 | Here is a short test of the @code{defuns-per-range} function. First, | |
16138 | evaluate the expression that binds (a shortened) | |
16139 | @code{top-of-ranges} list to the list of values, then evaluate the | |
16140 | expression for binding the @code{sorted-lengths} list, and then | |
16141 | evaluate the @code{defuns-per-range} function. | |
16142 | ||
16143 | @smallexample | |
16144 | @group | |
16145 | ;; @r{(Shorter list than we will use later.)} | |
16146 | (setq top-of-ranges | |
16147 | '(110 120 130 140 150 | |
16148 | 160 170 180 190 200)) | |
16149 | ||
16150 | (setq sorted-lengths | |
16151 | '(85 86 110 116 122 129 154 176 179 200 265 300 300)) | |
16152 | ||
16153 | (defuns-per-range sorted-lengths top-of-ranges) | |
16154 | @end group | |
16155 | @end smallexample | |
16156 | ||
16157 | @need 800 | |
16158 | @noindent | |
16159 | The list returned looks like this: | |
16160 | ||
16161 | @smallexample | |
16162 | (2 2 2 0 0 1 0 2 0 0 4) | |
16163 | @end smallexample | |
16164 | ||
16165 | @noindent | |
16166 | Indeed, there are two elements of the @code{sorted-lengths} list | |
16167 | smaller than 110, two elements between 110 and 119, two elements | |
16168 | between 120 and 129, and so on. There are four elements with a value | |
16169 | of 200 or larger. | |
16170 | ||
16171 | @c The next step is to turn this numbers' list into a graph. | |
d6adf7e7 | 16172 | @node Readying a Graph |
8cda6f8f GM |
16173 | @chapter Readying a Graph |
16174 | @cindex Readying a graph | |
16175 | @cindex Graph prototype | |
16176 | @cindex Prototype graph | |
16177 | @cindex Body of graph | |
16178 | ||
16179 | Our goal is to construct a graph showing the numbers of function | |
16180 | definitions of various lengths in the Emacs lisp sources. | |
16181 | ||
16182 | As a practical matter, if you were creating a graph, you would | |
16183 | probably use a program such as @code{gnuplot} to do the job. | |
16184 | (@code{gnuplot} is nicely integrated into GNU Emacs.) In this case, | |
16185 | however, we create one from scratch, and in the process we will | |
16186 | re-acquaint ourselves with some of what we learned before and learn | |
16187 | more. | |
16188 | ||
16189 | In this chapter, we will first write a simple graph printing function. | |
16190 | This first definition will be a @dfn{prototype}, a rapidly written | |
16191 | function that enables us to reconnoiter this unknown graph-making | |
16192 | territory. We will discover dragons, or find that they are myth. | |
16193 | After scouting the terrain, we will feel more confident and enhance | |
16194 | the function to label the axes automatically. | |
16195 | ||
16196 | @menu | |
16197 | * Columns of a graph:: | |
16198 | * graph-body-print:: How to print the body of a graph. | |
16199 | * recursive-graph-body-print:: | |
16200 | * Printed Axes:: | |
16201 | * Line Graph Exercise:: | |
16202 | @end menu | |
16203 | ||
8cda6f8f | 16204 | @ifnottex |
d6adf7e7 | 16205 | @node Columns of a graph |
8cda6f8f GM |
16206 | @unnumberedsec Printing the Columns of a Graph |
16207 | @end ifnottex | |
16208 | ||
16209 | Since Emacs is designed to be flexible and work with all kinds of | |
16210 | terminals, including character-only terminals, the graph will need to | |
16211 | be made from one of the `typewriter' symbols. An asterisk will do; as | |
16212 | we enhance the graph-printing function, we can make the choice of | |
16213 | symbol a user option. | |
16214 | ||
16215 | We can call this function @code{graph-body-print}; it will take a | |
16216 | @code{numbers-list} as its only argument. At this stage, we will not | |
16217 | label the graph, but only print its body. | |
16218 | ||
16219 | The @code{graph-body-print} function inserts a vertical column of | |
16220 | asterisks for each element in the @code{numbers-list}. The height of | |
16221 | each line is determined by the value of that element of the | |
16222 | @code{numbers-list}. | |
16223 | ||
16224 | Inserting columns is a repetitive act; that means that this function can | |
16225 | be written either with a @code{while} loop or recursively. | |
16226 | ||
16227 | Our first challenge is to discover how to print a column of asterisks. | |
16228 | Usually, in Emacs, we print characters onto a screen horizontally, | |
16229 | line by line, by typing. We have two routes we can follow: write our | |
16230 | own column-insertion function or discover whether one exists in Emacs. | |
16231 | ||
16232 | To see whether there is one in Emacs, we can use the @kbd{M-x apropos} | |
16233 | command. This command is like the @kbd{C-h a} (@code{command-apropos}) | |
16234 | command, except that the latter finds only those functions that are | |
16235 | commands. The @kbd{M-x apropos} command lists all symbols that match | |
16236 | a regular expression, including functions that are not interactive. | |
16237 | @findex apropos | |
16238 | ||
16239 | What we want to look for is some command that prints or inserts | |
16240 | columns. Very likely, the name of the function will contain either | |
16241 | the word `print' or the word `insert' or the word `column'. | |
16242 | Therefore, we can simply type @kbd{M-x apropos RET | |
16243 | print\|insert\|column RET} and look at the result. On my system, this | |
16244 | command once too takes quite some time, and then produced a list of 79 | |
16245 | functions and variables. Now it does not take much time at all and | |
16246 | produces a list of 211 functions and variables. Scanning down the | |
16247 | list, the only function that looks as if it might do the job is | |
16248 | @code{insert-rectangle}. | |
16249 | ||
16250 | @need 1200 | |
16251 | Indeed, this is the function we want; its documentation says: | |
16252 | ||
16253 | @smallexample | |
16254 | @group | |
16255 | insert-rectangle: | |
16256 | Insert text of RECTANGLE with upper left corner at point. | |
16257 | RECTANGLE's first line is inserted at point, | |
16258 | its second line is inserted at a point vertically under point, etc. | |
16259 | RECTANGLE should be a list of strings. | |
16260 | After this command, the mark is at the upper left corner | |
16261 | and point is at the lower right corner. | |
16262 | @end group | |
16263 | @end smallexample | |
16264 | ||
16265 | We can run a quick test, to make sure it does what we expect of it. | |
16266 | ||
16267 | Here is the result of placing the cursor after the | |
16268 | @code{insert-rectangle} expression and typing @kbd{C-u C-x C-e} | |
16269 | (@code{eval-last-sexp}). The function inserts the strings | |
16270 | @samp{"first"}, @samp{"second"}, and @samp{"third"} at and below | |
16271 | point. Also the function returns @code{nil}. | |
16272 | ||
16273 | @smallexample | |
16274 | @group | |
16275 | (insert-rectangle '("first" "second" "third"))first | |
16276 | second | |
16277 | thirdnil | |
16278 | @end group | |
16279 | @end smallexample | |
16280 | ||
16281 | @noindent | |
16282 | Of course, we won't be inserting the text of the | |
16283 | @code{insert-rectangle} expression itself into the buffer in which we | |
16284 | are making the graph, but will call the function from our program. We | |
16285 | shall, however, have to make sure that point is in the buffer at the | |
16286 | place where the @code{insert-rectangle} function will insert its | |
16287 | column of strings. | |
16288 | ||
16289 | If you are reading this in Info, you can see how this works by | |
16290 | switching to another buffer, such as the @file{*scratch*} buffer, | |
16291 | placing point somewhere in the buffer, typing @kbd{M-:}, typing the | |
16292 | @code{insert-rectangle} expression into the minibuffer at the prompt, | |
16293 | and then typing @key{RET}. This causes Emacs to evaluate the | |
16294 | expression in the minibuffer, but to use as the value of point the | |
16295 | position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the | |
16296 | keybinding for @code{eval-expression}. Also, @code{nil} does not | |
16297 | appear in the @file{*scratch*} buffer since the expression is | |
16298 | evaluated in the minibuffer.) | |
16299 | ||
16300 | We find when we do this that point ends up at the end of the last | |
16301 | inserted line---that is to say, this function moves point as a | |
16302 | side-effect. If we were to repeat the command, with point at this | |
16303 | position, the next insertion would be below and to the right of the | |
16304 | previous insertion. We don't want this! If we are going to make a | |
16305 | bar graph, the columns need to be beside each other. | |
16306 | ||
16307 | So we discover that each cycle of the column-inserting @code{while} | |
16308 | loop must reposition point to the place we want it, and that place | |
16309 | will be at the top, not the bottom, of the column. Moreover, we | |
16310 | remember that when we print a graph, we do not expect all the columns | |
16311 | to be the same height. This means that the top of each column may be | |
16312 | at a different height from the previous one. We cannot simply | |
16313 | reposition point to the same line each time, but moved over to the | |
16314 | right---or perhaps we can@dots{} | |
16315 | ||
16316 | We are planning to make the columns of the bar graph out of asterisks. | |
16317 | The number of asterisks in the column is the number specified by the | |
16318 | current element of the @code{numbers-list}. We need to construct a | |
16319 | list of asterisks of the right length for each call to | |
16320 | @code{insert-rectangle}. If this list consists solely of the requisite | |
16321 | number of asterisks, then we will have position point the right number | |
16322 | of lines above the base for the graph to print correctly. This could | |
16323 | be difficult. | |
16324 | ||
16325 | Alternatively, if we can figure out some way to pass | |
16326 | @code{insert-rectangle} a list of the same length each time, then we | |
16327 | can place point on the same line each time, but move it over one | |
16328 | column to the right for each new column. If we do this, however, some | |
16329 | of the entries in the list passed to @code{insert-rectangle} must be | |
16330 | blanks rather than asterisks. For example, if the maximum height of | |
16331 | the graph is 5, but the height of the column is 3, then | |
16332 | @code{insert-rectangle} requires an argument that looks like this: | |
16333 | ||
16334 | @smallexample | |
16335 | (" " " " "*" "*" "*") | |
16336 | @end smallexample | |
16337 | ||
16338 | This last proposal is not so difficult, so long as we can determine | |
16339 | the column height. There are two ways for us to specify the column | |
16340 | height: we can arbitrarily state what it will be, which would work | |
16341 | fine for graphs of that height; or we can search through the list of | |
16342 | numbers and use the maximum height of the list as the maximum height | |
16343 | of the graph. If the latter operation were difficult, then the former | |
16344 | procedure would be easiest, but there is a function built into Emacs | |
16345 | that determines the maximum of its arguments. We can use that | |
16346 | function. The function is called @code{max} and it returns the | |
16347 | largest of all its arguments, which must be numbers. Thus, for | |
16348 | example, | |
16349 | ||
16350 | @smallexample | |
16351 | (max 3 4 6 5 7 3) | |
16352 | @end smallexample | |
16353 | ||
16354 | @noindent | |
16355 | returns 7. (A corresponding function called @code{min} returns the | |
16356 | smallest of all its arguments.) | |
16357 | @findex max | |
16358 | @findex min | |
16359 | ||
16360 | However, we cannot simply call @code{max} on the @code{numbers-list}; | |
16361 | the @code{max} function expects numbers as its argument, not a list of | |
16362 | numbers. Thus, the following expression, | |
16363 | ||
16364 | @smallexample | |
16365 | (max '(3 4 6 5 7 3)) | |
16366 | @end smallexample | |
16367 | ||
16368 | @need 800 | |
16369 | @noindent | |
16370 | produces the following error message; | |
16371 | ||
16372 | @smallexample | |
16373 | Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3) | |
16374 | @end smallexample | |
16375 | ||
16376 | @findex apply | |
16377 | We need a function that passes a list of arguments to a function. | |
16378 | This function is @code{apply}. This function `applies' its first | |
16379 | argument (a function) to its remaining arguments, the last of which | |
16380 | may be a list. | |
16381 | ||
16382 | @need 1250 | |
16383 | For example, | |
16384 | ||
16385 | @smallexample | |
16386 | (apply 'max 3 4 7 3 '(4 8 5)) | |
16387 | @end smallexample | |
16388 | ||
16389 | @noindent | |
16390 | returns 8. | |
16391 | ||
16392 | (Incidentally, I don't know how you would learn of this function | |
16393 | without a book such as this. It is possible to discover other | |
16394 | functions, like @code{search-forward} or @code{insert-rectangle}, by | |
16395 | guessing at a part of their names and then using @code{apropos}. Even | |
16396 | though its base in metaphor is clear---`apply' its first argument to | |
16397 | the rest---I doubt a novice would come up with that particular word | |
16398 | when using @code{apropos} or other aid. Of course, I could be wrong; | |
16399 | after all, the function was first named by someone who had to invent | |
16400 | it.) | |
16401 | ||
16402 | The second and subsequent arguments to @code{apply} are optional, so | |
16403 | we can use @code{apply} to call a function and pass the elements of a | |
16404 | list to it, like this, which also returns 8: | |
16405 | ||
16406 | @smallexample | |
16407 | (apply 'max '(4 8 5)) | |
16408 | @end smallexample | |
16409 | ||
16410 | This latter way is how we will use @code{apply}. The | |
16411 | @code{recursive-lengths-list-many-files} function returns a numbers' | |
16412 | list to which we can apply @code{max} (we could also apply @code{max} to | |
16413 | the sorted numbers' list; it does not matter whether the list is | |
16414 | sorted or not.) | |
16415 | ||
16416 | @need 800 | |
16417 | Hence, the operation for finding the maximum height of the graph is this: | |
16418 | ||
16419 | @smallexample | |
16420 | (setq max-graph-height (apply 'max numbers-list)) | |
16421 | @end smallexample | |
16422 | ||
16423 | Now we can return to the question of how to create a list of strings | |
16424 | for a column of the graph. Told the maximum height of the graph | |
16425 | and the number of asterisks that should appear in the column, the | |
16426 | function should return a list of strings for the | |
16427 | @code{insert-rectangle} command to insert. | |
16428 | ||
16429 | Each column is made up of asterisks or blanks. Since the function is | |
16430 | passed the value of the height of the column and the number of | |
16431 | asterisks in the column, the number of blanks can be found by | |
16432 | subtracting the number of asterisks from the height of the column. | |
16433 | Given the number of blanks and the number of asterisks, two | |
16434 | @code{while} loops can be used to construct the list: | |
16435 | ||
16436 | @smallexample | |
16437 | @group | |
16438 | ;;; @r{First version.} | |
16439 | (defun column-of-graph (max-graph-height actual-height) | |
16440 | "Return list of strings that is one column of a graph." | |
16441 | (let ((insert-list nil) | |
16442 | (number-of-top-blanks | |
16443 | (- max-graph-height actual-height))) | |
16444 | @end group | |
16445 | ||
16446 | @group | |
16447 | ;; @r{Fill in asterisks.} | |
16448 | (while (> actual-height 0) | |
16449 | (setq insert-list (cons "*" insert-list)) | |
16450 | (setq actual-height (1- actual-height))) | |
16451 | @end group | |
16452 | ||
16453 | @group | |
16454 | ;; @r{Fill in blanks.} | |
16455 | (while (> number-of-top-blanks 0) | |
16456 | (setq insert-list (cons " " insert-list)) | |
16457 | (setq number-of-top-blanks | |
16458 | (1- number-of-top-blanks))) | |
16459 | @end group | |
16460 | ||
16461 | @group | |
16462 | ;; @r{Return whole list.} | |
16463 | insert-list)) | |
16464 | @end group | |
16465 | @end smallexample | |
16466 | ||
16467 | If you install this function and then evaluate the following | |
16468 | expression you will see that it returns the list as desired: | |
16469 | ||
16470 | @smallexample | |
16471 | (column-of-graph 5 3) | |
16472 | @end smallexample | |
16473 | ||
16474 | @need 800 | |
16475 | @noindent | |
16476 | returns | |
16477 | ||
16478 | @smallexample | |
16479 | (" " " " "*" "*" "*") | |
16480 | @end smallexample | |
16481 | ||
16482 | As written, @code{column-of-graph} contains a major flaw: the symbols | |
16483 | used for the blank and for the marked entries in the column are | |
16484 | `hard-coded' as a space and asterisk. This is fine for a prototype, | |
16485 | but you, or another user, may wish to use other symbols. For example, | |
16486 | in testing the graph function, you many want to use a period in place | |
16487 | of the space, to make sure the point is being repositioned properly | |
16488 | each time the @code{insert-rectangle} function is called; or you might | |
16489 | want to substitute a @samp{+} sign or other symbol for the asterisk. | |
16490 | You might even want to make a graph-column that is more than one | |
16491 | display column wide. The program should be more flexible. The way to | |
16492 | do that is to replace the blank and the asterisk with two variables | |
16493 | that we can call @code{graph-blank} and @code{graph-symbol} and define | |
16494 | those variables separately. | |
16495 | ||
16496 | Also, the documentation is not well written. These considerations | |
16497 | lead us to the second version of the function: | |
16498 | ||
16499 | @smallexample | |
16500 | @group | |
16501 | (defvar graph-symbol "*" | |
16502 | "String used as symbol in graph, usually an asterisk.") | |
16503 | @end group | |
16504 | ||
16505 | @group | |
16506 | (defvar graph-blank " " | |
16507 | "String used as blank in graph, usually a blank space. | |
16508 | graph-blank must be the same number of columns wide | |
16509 | as graph-symbol.") | |
16510 | @end group | |
16511 | @end smallexample | |
16512 | ||
16513 | @noindent | |
16514 | (For an explanation of @code{defvar}, see | |
16515 | @ref{defvar, , Initializing a Variable with @code{defvar}}.) | |
16516 | ||
16517 | @smallexample | |
16518 | @group | |
16519 | ;;; @r{Second version.} | |
16520 | (defun column-of-graph (max-graph-height actual-height) | |
16521 | "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols. | |
16522 | ||
16523 | @end group | |
16524 | @group | |
16525 | The graph-symbols are contiguous entries at the end | |
16526 | of the list. | |
16527 | The list will be inserted as one column of a graph. | |
16528 | The strings are either graph-blank or graph-symbol." | |
16529 | @end group | |
16530 | ||
16531 | @group | |
16532 | (let ((insert-list nil) | |
16533 | (number-of-top-blanks | |
16534 | (- max-graph-height actual-height))) | |
16535 | @end group | |
16536 | ||
16537 | @group | |
16538 | ;; @r{Fill in @code{graph-symbols}.} | |
16539 | (while (> actual-height 0) | |
16540 | (setq insert-list (cons graph-symbol insert-list)) | |
16541 | (setq actual-height (1- actual-height))) | |
16542 | @end group | |
16543 | ||
16544 | @group | |
16545 | ;; @r{Fill in @code{graph-blanks}.} | |
16546 | (while (> number-of-top-blanks 0) | |
16547 | (setq insert-list (cons graph-blank insert-list)) | |
16548 | (setq number-of-top-blanks | |
16549 | (1- number-of-top-blanks))) | |
16550 | ||
16551 | ;; @r{Return whole list.} | |
16552 | insert-list)) | |
16553 | @end group | |
16554 | @end smallexample | |
16555 | ||
16556 | If we wished, we could rewrite @code{column-of-graph} a third time to | |
16557 | provide optionally for a line graph as well as for a bar graph. This | |
16558 | would not be hard to do. One way to think of a line graph is that it | |
16559 | is no more than a bar graph in which the part of each bar that is | |
16560 | below the top is blank. To construct a column for a line graph, the | |
16561 | function first constructs a list of blanks that is one shorter than | |
16562 | the value, then it uses @code{cons} to attach a graph symbol to the | |
16563 | list; then it uses @code{cons} again to attach the `top blanks' to | |
16564 | the list. | |
16565 | ||
16566 | It is easy to see how to write such a function, but since we don't | |
16567 | need it, we will not do it. But the job could be done, and if it were | |
16568 | done, it would be done with @code{column-of-graph}. Even more | |
16569 | important, it is worth noting that few changes would have to be made | |
16570 | anywhere else. The enhancement, if we ever wish to make it, is | |
16571 | simple. | |
16572 | ||
16573 | Now, finally, we come to our first actual graph printing function. | |
16574 | This prints the body of a graph, not the labels for the vertical and | |
16575 | horizontal axes, so we can call this @code{graph-body-print}. | |
16576 | ||
d6adf7e7 | 16577 | @node graph-body-print |
8cda6f8f GM |
16578 | @section The @code{graph-body-print} Function |
16579 | @findex graph-body-print | |
16580 | ||
16581 | After our preparation in the preceding section, the | |
16582 | @code{graph-body-print} function is straightforward. The function | |
16583 | will print column after column of asterisks and blanks, using the | |
16584 | elements of a numbers' list to specify the number of asterisks in each | |
16585 | column. This is a repetitive act, which means we can use a | |
16586 | decrementing @code{while} loop or recursive function for the job. In | |
16587 | this section, we will write the definition using a @code{while} loop. | |
16588 | ||
16589 | The @code{column-of-graph} function requires the height of the graph | |
16590 | as an argument, so we should determine and record that as a local variable. | |
16591 | ||
16592 | This leads us to the following template for the @code{while} loop | |
16593 | version of this function: | |
16594 | ||
16595 | @smallexample | |
16596 | @group | |
16597 | (defun graph-body-print (numbers-list) | |
16598 | "@var{documentation}@dots{}" | |
16599 | (let ((height @dots{} | |
16600 | @dots{})) | |
16601 | @end group | |
16602 | ||
16603 | @group | |
16604 | (while numbers-list | |
16605 | @var{insert-columns-and-reposition-point} | |
16606 | (setq numbers-list (cdr numbers-list))))) | |
16607 | @end group | |
16608 | @end smallexample | |
16609 | ||
16610 | @noindent | |
16611 | We need to fill in the slots of the template. | |
16612 | ||
16613 | Clearly, we can use the @code{(apply 'max numbers-list)} expression to | |
16614 | determine the height of the graph. | |
16615 | ||
16616 | The @code{while} loop will cycle through the @code{numbers-list} one | |
16617 | element at a time. As it is shortened by the @code{(setq numbers-list | |
16618 | (cdr numbers-list))} expression, the @sc{car} of each instance of the | |
16619 | list is the value of the argument for @code{column-of-graph}. | |
16620 | ||
16621 | At each cycle of the @code{while} loop, the @code{insert-rectangle} | |
16622 | function inserts the list returned by @code{column-of-graph}. Since | |
16623 | the @code{insert-rectangle} function moves point to the lower right of | |
16624 | the inserted rectangle, we need to save the location of point at the | |
16625 | time the rectangle is inserted, move back to that position after the | |
16626 | rectangle is inserted, and then move horizontally to the next place | |
16627 | from which @code{insert-rectangle} is called. | |
16628 | ||
16629 | If the inserted columns are one character wide, as they will be if | |
16630 | single blanks and asterisks are used, the repositioning command is | |
16631 | simply @code{(forward-char 1)}; however, the width of a column may be | |
16632 | greater than one. This means that the repositioning command should be | |
16633 | written @code{(forward-char symbol-width)}. The @code{symbol-width} | |
16634 | itself is the length of a @code{graph-blank} and can be found using | |
16635 | the expression @code{(length graph-blank)}. The best place to bind | |
16636 | the @code{symbol-width} variable to the value of the width of graph | |
16637 | column is in the varlist of the @code{let} expression. | |
16638 | ||
16639 | @need 1250 | |
16640 | These considerations lead to the following function definition: | |
16641 | ||
16642 | @smallexample | |
16643 | @group | |
16644 | (defun graph-body-print (numbers-list) | |
16645 | "Print a bar graph of the NUMBERS-LIST. | |
16646 | The numbers-list consists of the Y-axis values." | |
16647 | ||
16648 | (let ((height (apply 'max numbers-list)) | |
16649 | (symbol-width (length graph-blank)) | |
16650 | from-position) | |
16651 | @end group | |
16652 | ||
16653 | @group | |
16654 | (while numbers-list | |
16655 | (setq from-position (point)) | |
16656 | (insert-rectangle | |
16657 | (column-of-graph height (car numbers-list))) | |
16658 | (goto-char from-position) | |
16659 | (forward-char symbol-width) | |
16660 | @end group | |
16661 | @group | |
16662 | ;; @r{Draw graph column by column.} | |
16663 | (sit-for 0) | |
16664 | (setq numbers-list (cdr numbers-list))) | |
16665 | @end group | |
16666 | @group | |
16667 | ;; @r{Place point for X axis labels.} | |
16668 | (forward-line height) | |
16669 | (insert "\n") | |
16670 | )) | |
16671 | @end group | |
16672 | @end smallexample | |
16673 | ||
16674 | @noindent | |
16675 | The one unexpected expression in this function is the | |
16676 | @w{@code{(sit-for 0)}} expression in the @code{while} loop. This | |
16677 | expression makes the graph printing operation more interesting to | |
16678 | watch than it would be otherwise. The expression causes Emacs to | |
16679 | `sit' or do nothing for a zero length of time and then redraw the | |
16680 | screen. Placed here, it causes Emacs to redraw the screen column by | |
16681 | column. Without it, Emacs would not redraw the screen until the | |
16682 | function exits. | |
16683 | ||
16684 | We can test @code{graph-body-print} with a short list of numbers. | |
16685 | ||
16686 | @enumerate | |
16687 | @item | |
16688 | Install @code{graph-symbol}, @code{graph-blank}, | |
16689 | @code{column-of-graph}, which are in | |
16690 | @iftex | |
16691 | @ref{Readying a Graph, , Readying a Graph}, | |
16692 | @end iftex | |
16693 | @ifinfo | |
16694 | @ref{Columns of a graph}, | |
16695 | @end ifinfo | |
16696 | and @code{graph-body-print}. | |
16697 | ||
16698 | @need 800 | |
16699 | @item | |
16700 | Copy the following expression: | |
16701 | ||
16702 | @smallexample | |
16703 | (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3)) | |
16704 | @end smallexample | |
16705 | ||
16706 | @item | |
16707 | Switch to the @file{*scratch*} buffer and place the cursor where you | |
16708 | want the graph to start. | |
16709 | ||
16710 | @item | |
16711 | Type @kbd{M-:} (@code{eval-expression}). | |
16712 | ||
16713 | @item | |
16714 | Yank the @code{graph-body-print} expression into the minibuffer | |
16715 | with @kbd{C-y} (@code{yank)}. | |
16716 | ||
16717 | @item | |
16718 | Press @key{RET} to evaluate the @code{graph-body-print} expression. | |
16719 | @end enumerate | |
16720 | ||
16721 | @need 800 | |
16722 | Emacs will print a graph like this: | |
16723 | ||
16724 | @smallexample | |
16725 | @group | |
16726 | * | |
16727 | * ** | |
16728 | * **** | |
16729 | *** **** | |
16730 | ********* * | |
16731 | ************ | |
16732 | ************* | |
16733 | @end group | |
16734 | @end smallexample | |
16735 | ||
d6adf7e7 | 16736 | @node recursive-graph-body-print |
8cda6f8f GM |
16737 | @section The @code{recursive-graph-body-print} Function |
16738 | @findex recursive-graph-body-print | |
16739 | ||
16740 | The @code{graph-body-print} function may also be written recursively. | |
16741 | The recursive solution is divided into two parts: an outside `wrapper' | |
16742 | that uses a @code{let} expression to determine the values of several | |
16743 | variables that need only be found once, such as the maximum height of | |
16744 | the graph, and an inside function that is called recursively to print | |
16745 | the graph. | |
16746 | ||
16747 | @need 1250 | |
16748 | The `wrapper' is uncomplicated: | |
16749 | ||
16750 | @smallexample | |
16751 | @group | |
16752 | (defun recursive-graph-body-print (numbers-list) | |
16753 | "Print a bar graph of the NUMBERS-LIST. | |
16754 | The numbers-list consists of the Y-axis values." | |
16755 | (let ((height (apply 'max numbers-list)) | |
16756 | (symbol-width (length graph-blank)) | |
16757 | from-position) | |
16758 | (recursive-graph-body-print-internal | |
16759 | numbers-list | |
16760 | height | |
16761 | symbol-width))) | |
16762 | @end group | |
16763 | @end smallexample | |
16764 | ||
16765 | The recursive function is a little more difficult. It has four parts: | |
16766 | the `do-again-test', the printing code, the recursive call, and the | |
16767 | `next-step-expression'. The `do-again-test' is a @code{when} | |
16768 | expression that determines whether the @code{numbers-list} contains | |
16769 | any remaining elements; if it does, the function prints one column of | |
16770 | the graph using the printing code and calls itself again. The | |
16771 | function calls itself again according to the value produced by the | |
16772 | `next-step-expression' which causes the call to act on a shorter | |
16773 | version of the @code{numbers-list}. | |
16774 | ||
16775 | @smallexample | |
16776 | @group | |
16777 | (defun recursive-graph-body-print-internal | |
16778 | (numbers-list height symbol-width) | |
16779 | "Print a bar graph. | |
16780 | Used within recursive-graph-body-print function." | |
16781 | @end group | |
16782 | ||
16783 | @group | |
16784 | (when numbers-list | |
16785 | (setq from-position (point)) | |
16786 | (insert-rectangle | |
16787 | (column-of-graph height (car numbers-list))) | |
16788 | @end group | |
16789 | @group | |
16790 | (goto-char from-position) | |
16791 | (forward-char symbol-width) | |
16792 | (sit-for 0) ; @r{Draw graph column by column.} | |
16793 | (recursive-graph-body-print-internal | |
16794 | (cdr numbers-list) height symbol-width))) | |
16795 | @end group | |
16796 | @end smallexample | |
16797 | ||
16798 | @need 1250 | |
16799 | After installation, this expression can be tested; here is a sample: | |
16800 | ||
16801 | @smallexample | |
16802 | (recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1)) | |
16803 | @end smallexample | |
16804 | ||
16805 | @need 800 | |
16806 | Here is what @code{recursive-graph-body-print} produces: | |
16807 | ||
16808 | @smallexample | |
16809 | @group | |
16810 | * | |
16811 | ** * | |
16812 | **** * | |
16813 | **** *** | |
16814 | * ********* | |
16815 | ************ | |
16816 | ************* | |
16817 | @end group | |
16818 | @end smallexample | |
16819 | ||
16820 | Either of these two functions, @code{graph-body-print} or | |
16821 | @code{recursive-graph-body-print}, create the body of a graph. | |
16822 | ||
d6adf7e7 | 16823 | @node Printed Axes |
8cda6f8f GM |
16824 | @section Need for Printed Axes |
16825 | ||
16826 | A graph needs printed axes, so you can orient yourself. For a do-once | |
44e97401 | 16827 | project, it may be reasonable to draw the axes by hand using Emacs's |
8cda6f8f GM |
16828 | Picture mode; but a graph drawing function may be used more than once. |
16829 | ||
16830 | For this reason, I have written enhancements to the basic | |
16831 | @code{print-graph-body} function that automatically print labels for | |
16832 | the horizontal and vertical axes. Since the label printing functions | |
16833 | do not contain much new material, I have placed their description in | |
09e80d9f | 16834 | an appendix. @xref{Full Graph, , A Graph with Labeled Axes}. |
8cda6f8f | 16835 | |
d6adf7e7 | 16836 | @node Line Graph Exercise |
8cda6f8f GM |
16837 | @section Exercise |
16838 | ||
16839 | Write a line graph version of the graph printing functions. | |
16840 | ||
d6adf7e7 | 16841 | @node Emacs Initialization |
8cda6f8f GM |
16842 | @chapter Your @file{.emacs} File |
16843 | @cindex @file{.emacs} file | |
16844 | @cindex Customizing your @file{.emacs} file | |
16845 | @cindex Initialization file | |
16846 | ||
f99f1641 | 16847 | ``You don't have to like Emacs to like it''---this seemingly |
8cda6f8f GM |
16848 | paradoxical statement is the secret of GNU Emacs. The plain, `out of |
16849 | the box' Emacs is a generic tool. Most people who use it, customize | |
16850 | it to suit themselves. | |
16851 | ||
16852 | GNU Emacs is mostly written in Emacs Lisp; this means that by writing | |
16853 | expressions in Emacs Lisp you can change or extend Emacs. | |
16854 | ||
16855 | @menu | |
16856 | * Default Configuration:: | |
16857 | * Site-wide Init:: You can write site-wide init files. | |
16858 | * defcustom:: Emacs will write code for you. | |
16859 | * Beginning a .emacs File:: How to write a @code{.emacs file}. | |
16860 | * Text and Auto-fill:: Automatically wrap lines. | |
16861 | * Mail Aliases:: Use abbreviations for email addresses. | |
16862 | * Indent Tabs Mode:: Don't use tabs with @TeX{} | |
16863 | * Keybindings:: Create some personal keybindings. | |
16864 | * Keymaps:: More about key binding. | |
16865 | * Loading Files:: Load (i.e., evaluate) files automatically. | |
16866 | * Autoload:: Make functions available. | |
16867 | * Simple Extension:: Define a function; bind it to a key. | |
16868 | * X11 Colors:: Colors in X. | |
16869 | * Miscellaneous:: | |
16870 | * Mode Line:: How to customize your mode line. | |
16871 | @end menu | |
16872 | ||
8cda6f8f | 16873 | @ifnottex |
d6adf7e7 | 16874 | @node Default Configuration |
44e97401 | 16875 | @unnumberedsec Emacs's Default Configuration |
8cda6f8f GM |
16876 | @end ifnottex |
16877 | ||
44e97401 | 16878 | There are those who appreciate Emacs's default configuration. After |
8cda6f8f GM |
16879 | all, Emacs starts you in C mode when you edit a C file, starts you in |
16880 | Fortran mode when you edit a Fortran file, and starts you in | |
16881 | Fundamental mode when you edit an unadorned file. This all makes | |
16882 | sense, if you do not know who is going to use Emacs. Who knows what a | |
16883 | person hopes to do with an unadorned file? Fundamental mode is the | |
16884 | right default for such a file, just as C mode is the right default for | |
16885 | editing C code. (Enough programming languages have syntaxes | |
16886 | that enable them to share or nearly share features, so C mode is | |
6bd6c2fa | 16887 | now provided by CC mode, the `C Collection'.) |
8cda6f8f GM |
16888 | |
16889 | But when you do know who is going to use Emacs---you, | |
16890 | yourself---then it makes sense to customize Emacs. | |
16891 | ||
16892 | For example, I seldom want Fundamental mode when I edit an | |
16893 | otherwise undistinguished file; I want Text mode. This is why I | |
16894 | customize Emacs: so it suits me. | |
16895 | ||
16896 | You can customize and extend Emacs by writing or adapting a | |
16897 | @file{~/.emacs} file. This is your personal initialization file; its | |
16898 | contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You | |
16899 | may also add @file{.el} to @file{~/.emacs} and call it a | |
16900 | @file{~/.emacs.el} file. In the past, you were forbidden to type the | |
16901 | extra keystrokes that the name @file{~/.emacs.el} requires, but now | |
16902 | you may. The new format is consistent with the Emacs Lisp file | |
16903 | naming conventions; the old format saves typing.} | |
16904 | ||
16905 | A @file{~/.emacs} file contains Emacs Lisp code. You can write this | |
44e97401 | 16906 | code yourself; or you can use Emacs's @code{customize} feature to write |
8cda6f8f GM |
16907 | the code for you. You can combine your own expressions and |
16908 | auto-written Customize expressions in your @file{.emacs} file. | |
16909 | ||
16910 | (I myself prefer to write my own expressions, except for those, | |
16911 | particularly fonts, that I find easier to manipulate using the | |
16912 | @code{customize} command. I combine the two methods.) | |
16913 | ||
16914 | Most of this chapter is about writing expressions yourself. It | |
16915 | describes a simple @file{.emacs} file; for more information, see | |
16916 | @ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and | |
16917 | @ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference | |
16918 | Manual}. | |
16919 | ||
d6adf7e7 | 16920 | @node Site-wide Init |
8cda6f8f GM |
16921 | @section Site-wide Initialization Files |
16922 | ||
16923 | @cindex @file{default.el} init file | |
16924 | @cindex @file{site-init.el} init file | |
16925 | @cindex @file{site-load.el} init file | |
16926 | In addition to your personal initialization file, Emacs automatically | |
16927 | loads various site-wide initialization files, if they exist. These | |
16928 | have the same form as your @file{.emacs} file, but are loaded by | |
16929 | everyone. | |
16930 | ||
16931 | Two site-wide initialization files, @file{site-load.el} and | |
16932 | @file{site-init.el}, are loaded into Emacs and then `dumped' if a | |
16933 | `dumped' version of Emacs is created, as is most common. (Dumped | |
16934 | copies of Emacs load more quickly. However, once a file is loaded and | |
16935 | dumped, a change to it does not lead to a change in Emacs unless you | |
16936 | load it yourself or re-dump Emacs. @xref{Building Emacs, , Building | |
16937 | Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the | |
16938 | @file{INSTALL} file.) | |
16939 | ||
16940 | Three other site-wide initialization files are loaded automatically | |
16941 | each time you start Emacs, if they exist. These are | |
16942 | @file{site-start.el}, which is loaded @emph{before} your @file{.emacs} | |
16943 | file, and @file{default.el}, and the terminal type file, which are both | |
16944 | loaded @emph{after} your @file{.emacs} file. | |
16945 | ||
16946 | Settings and definitions in your @file{.emacs} file will overwrite | |
16947 | conflicting settings and definitions in a @file{site-start.el} file, | |
16948 | if it exists; but the settings and definitions in a @file{default.el} | |
16949 | or terminal type file will overwrite those in your @file{.emacs} file. | |
16950 | (You can prevent interference from a terminal type file by setting | |
16951 | @code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A | |
16952 | Simple Extension}.) | |
16953 | ||
16954 | @c Rewritten to avoid overfull hbox. | |
16955 | The @file{INSTALL} file that comes in the distribution contains | |
16956 | descriptions of the @file{site-init.el} and @file{site-load.el} files. | |
16957 | ||
16958 | The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files | |
16959 | control loading. These files are in the @file{lisp} directory of the | |
16960 | Emacs distribution and are worth perusing. | |
16961 | ||
16962 | The @file{loaddefs.el} file contains a good many suggestions as to | |
16963 | what to put into your own @file{.emacs} file, or into a site-wide | |
16964 | initialization file. | |
16965 | ||
d6adf7e7 | 16966 | @node defcustom |
8cda6f8f GM |
16967 | @section Specifying Variables using @code{defcustom} |
16968 | @findex defcustom | |
16969 | ||
16970 | You can specify variables using @code{defcustom} so that you and | |
44e97401 | 16971 | others can then use Emacs's @code{customize} feature to set their |
8cda6f8f GM |
16972 | values. (You cannot use @code{customize} to write function |
16973 | definitions; but you can write @code{defuns} in your @file{.emacs} | |
16974 | file. Indeed, you can write any Lisp expression in your @file{.emacs} | |
16975 | file.) | |
16976 | ||
767b8eae XF |
16977 | The @code{customize} feature depends on the @code{defcustom} macro. |
16978 | Although you can use @code{defvar} or @code{setq} for variables that | |
16979 | users set, the @code{defcustom} macro is designed for the job. | |
8cda6f8f GM |
16980 | |
16981 | You can use your knowledge of @code{defvar} for writing the | |
16982 | first three arguments for @code{defcustom}. The first argument to | |
16983 | @code{defcustom} is the name of the variable. The second argument is | |
16984 | the variable's initial value, if any; and this value is set only if | |
16985 | the value has not already been set. The third argument is the | |
16986 | documentation. | |
16987 | ||
16988 | The fourth and subsequent arguments to @code{defcustom} specify types | |
16989 | and options; these are not featured in @code{defvar}. (These | |
16990 | arguments are optional.) | |
16991 | ||
16992 | Each of these arguments consists of a keyword followed by a value. | |
16993 | Each keyword starts with the colon character @samp{:}. | |
16994 | ||
16995 | @need 1250 | |
16996 | For example, the customizable user option variable | |
16997 | @code{text-mode-hook} looks like this: | |
16998 | ||
16999 | @smallexample | |
17000 | @group | |
17001 | (defcustom text-mode-hook nil | |
17002 | "Normal hook run when entering Text mode and many related modes." | |
17003 | :type 'hook | |
17004 | :options '(turn-on-auto-fill flyspell-mode) | |
cfe1c0af | 17005 | :group 'wp) |
8cda6f8f GM |
17006 | @end group |
17007 | @end smallexample | |
17008 | ||
17009 | @noindent | |
17010 | The name of the variable is @code{text-mode-hook}; it has no default | |
17011 | value; and its documentation string tells you what it does. | |
17012 | ||
17013 | The @code{:type} keyword tells Emacs the kind of data to which | |
17014 | @code{text-mode-hook} should be set and how to display the value in a | |
17015 | Customization buffer. | |
17016 | ||
17017 | The @code{:options} keyword specifies a suggested list of values for | |
17018 | the variable. Usually, @code{:options} applies to a hook. | |
17019 | The list is only a suggestion; it is not exclusive; a person who sets | |
17020 | the variable may set it to other values; the list shown following the | |
17021 | @code{:options} keyword is intended to offer convenient choices to a | |
17022 | user. | |
17023 | ||
17024 | Finally, the @code{:group} keyword tells the Emacs Customization | |
17025 | command in which group the variable is located. This tells where to | |
17026 | find it. | |
17027 | ||
17028 | The @code{defcustom} function recognizes more than a dozen keywords. | |
17029 | For more information, see @ref{Customization, , Writing Customization | |
17030 | Definitions, elisp, The GNU Emacs Lisp Reference Manual}. | |
17031 | ||
17032 | Consider @code{text-mode-hook} as an example. | |
17033 | ||
17034 | There are two ways to customize this variable. You can use the | |
17035 | customization command or write the appropriate expressions yourself. | |
17036 | ||
17037 | @need 800 | |
17038 | Using the customization command, you can type: | |
17039 | ||
17040 | @smallexample | |
17041 | M-x customize | |
17042 | @end smallexample | |
17043 | ||
17044 | @noindent | |
17045 | and find that the group for editing files of data is called `data'. | |
17046 | Enter that group. Text Mode Hook is the first member. You can click | |
17047 | on its various options, such as @code{turn-on-auto-fill}, to set the | |
17048 | values. After you click on the button to | |
17049 | ||
17050 | @smallexample | |
17051 | Save for Future Sessions | |
17052 | @end smallexample | |
17053 | ||
17054 | @noindent | |
17055 | Emacs will write an expression into your @file{.emacs} file. | |
17056 | It will look like this: | |
17057 | ||
17058 | @smallexample | |
17059 | @group | |
17060 | (custom-set-variables | |
17061 | ;; custom-set-variables was added by Custom. | |
17062 | ;; If you edit it by hand, you could mess it up, so be careful. | |
17063 | ;; Your init file should contain only one such instance. | |
17064 | ;; If there is more than one, they won't work right. | |
17065 | '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify)))) | |
17066 | @end group | |
17067 | @end smallexample | |
17068 | ||
17069 | @noindent | |
17070 | (The @code{text-mode-hook-identify} function tells | |
17071 | @code{toggle-text-mode-auto-fill} which buffers are in Text mode. | |
17072 | It comes on automatically.) | |
17073 | ||
17074 | The @code{custom-set-variables} function works somewhat differently | |
17075 | than a @code{setq}. While I have never learned the differences, I | |
17076 | modify the @code{custom-set-variables} expressions in my @file{.emacs} | |
17077 | file by hand: I make the changes in what appears to me to be a | |
17078 | reasonable manner and have not had any problems. Others prefer to use | |
17079 | the Customization command and let Emacs do the work for them. | |
17080 | ||
17081 | Another @code{custom-set-@dots{}} function is @code{custom-set-faces}. | |
17082 | This function sets the various font faces. Over time, I have set a | |
17083 | considerable number of faces. Some of the time, I re-set them using | |
17084 | @code{customize}; other times, I simply edit the | |
17085 | @code{custom-set-faces} expression in my @file{.emacs} file itself. | |
17086 | ||
17087 | The second way to customize your @code{text-mode-hook} is to set it | |
17088 | yourself in your @file{.emacs} file using code that has nothing to do | |
17089 | with the @code{custom-set-@dots{}} functions. | |
17090 | ||
17091 | @need 800 | |
17092 | When you do this, and later use @code{customize}, you will see a | |
17093 | message that says | |
17094 | ||
17095 | @smallexample | |
17096 | CHANGED outside Customize; operating on it here may be unreliable. | |
17097 | @end smallexample | |
17098 | ||
17099 | @need 800 | |
17100 | This message is only a warning. If you click on the button to | |
17101 | ||
17102 | @smallexample | |
17103 | Save for Future Sessions | |
17104 | @end smallexample | |
17105 | ||
17106 | @noindent | |
17107 | Emacs will write a @code{custom-set-@dots{}} expression near the end | |
17108 | of your @file{.emacs} file that will be evaluated after your | |
17109 | hand-written expression. It will, therefore, overrule your | |
17110 | hand-written expression. No harm will be done. When you do this, | |
17111 | however, be careful to remember which expression is active; if you | |
17112 | forget, you may confuse yourself. | |
17113 | ||
17114 | So long as you remember where the values are set, you will have no | |
17115 | trouble. In any event, the values are always set in your | |
17116 | initialization file, which is usually called @file{.emacs}. | |
17117 | ||
17118 | I myself use @code{customize} for hardly anything. Mostly, I write | |
17119 | expressions myself. | |
17120 | ||
17121 | @findex defsubst | |
17122 | @findex defconst | |
17123 | Incidentally, to be more complete concerning defines: @code{defsubst} | |
17124 | defines an inline function. The syntax is just like that of | |
17125 | @code{defun}. @code{defconst} defines a symbol as a constant. The | |
17126 | intent is that neither programs nor users should ever change a value | |
17127 | set by @code{defconst}. (You can change it; the value set is a | |
17128 | variable; but please do not.) | |
17129 | ||
d6adf7e7 | 17130 | @node Beginning a .emacs File |
8cda6f8f GM |
17131 | @section Beginning a @file{.emacs} File |
17132 | @cindex @file{.emacs} file, beginning of | |
17133 | ||
17134 | When you start Emacs, it loads your @file{.emacs} file unless you tell | |
17135 | it not to by specifying @samp{-q} on the command line. (The | |
17136 | @code{emacs -q} command gives you a plain, out-of-the-box Emacs.) | |
17137 | ||
17138 | A @file{.emacs} file contains Lisp expressions. Often, these are no | |
17139 | more than expressions to set values; sometimes they are function | |
17140 | definitions. | |
17141 | ||
17142 | @xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs | |
17143 | Manual}, for a short description of initialization files. | |
17144 | ||
17145 | This chapter goes over some of the same ground, but is a walk among | |
17146 | extracts from a complete, long-used @file{.emacs} file---my own. | |
17147 | ||
17148 | The first part of the file consists of comments: reminders to myself. | |
17149 | By now, of course, I remember these things, but when I started, I did | |
17150 | not. | |
17151 | ||
17152 | @need 1200 | |
17153 | @smallexample | |
17154 | @group | |
17155 | ;;;; Bob's .emacs file | |
17156 | ; Robert J. Chassell | |
17157 | ; 26 September 1985 | |
17158 | @end group | |
17159 | @end smallexample | |
17160 | ||
17161 | @noindent | |
17162 | Look at that date! I started this file a long time ago. I have been | |
17163 | adding to it ever since. | |
17164 | ||
17165 | @smallexample | |
17166 | @group | |
17167 | ; Each section in this file is introduced by a | |
17168 | ; line beginning with four semicolons; and each | |
17169 | ; entry is introduced by a line beginning with | |
17170 | ; three semicolons. | |
17171 | @end group | |
17172 | @end smallexample | |
17173 | ||
17174 | @noindent | |
17175 | This describes the usual conventions for comments in Emacs Lisp. | |
17176 | Everything on a line that follows a semicolon is a comment. Two, | |
17177 | three, and four semicolons are used as subsection and section markers. | |
17178 | (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for | |
17179 | more about comments.) | |
17180 | ||
17181 | @smallexample | |
17182 | @group | |
17183 | ;;;; The Help Key | |
17184 | ; Control-h is the help key; | |
17185 | ; after typing control-h, type a letter to | |
17186 | ; indicate the subject about which you want help. | |
17187 | ; For an explanation of the help facility, | |
17188 | ; type control-h two times in a row. | |
17189 | @end group | |
17190 | @end smallexample | |
17191 | ||
17192 | @noindent | |
17193 | Just remember: type @kbd{C-h} two times for help. | |
17194 | ||
17195 | @smallexample | |
17196 | @group | |
17197 | ; To find out about any mode, type control-h m | |
17198 | ; while in that mode. For example, to find out | |
17199 | ; about mail mode, enter mail mode and then type | |
17200 | ; control-h m. | |
17201 | @end group | |
17202 | @end smallexample | |
17203 | ||
17204 | @noindent | |
17205 | `Mode help', as I call this, is very helpful. Usually, it tells you | |
17206 | all you need to know. | |
17207 | ||
17208 | Of course, you don't need to include comments like these in your | |
17209 | @file{.emacs} file. I included them in mine because I kept forgetting | |
17210 | about Mode help or the conventions for comments---but I was able to | |
17211 | remember to look here to remind myself. | |
17212 | ||
d6adf7e7 | 17213 | @node Text and Auto-fill |
8cda6f8f GM |
17214 | @section Text and Auto Fill Mode |
17215 | ||
17216 | Now we come to the part that `turns on' Text mode and | |
17217 | Auto Fill mode. | |
17218 | ||
17219 | @smallexample | |
17220 | @group | |
17221 | ;;; Text mode and Auto Fill mode | |
cd61af01 SM |
17222 | ;; The next two lines put Emacs into Text mode |
17223 | ;; and Auto Fill mode, and are for writers who | |
17224 | ;; want to start writing prose rather than code. | |
17225 | (setq-default major-mode 'text-mode) | |
8cda6f8f GM |
17226 | (add-hook 'text-mode-hook 'turn-on-auto-fill) |
17227 | @end group | |
17228 | @end smallexample | |
17229 | ||
17230 | Here is the first part of this @file{.emacs} file that does something | |
17231 | besides remind a forgetful human! | |
17232 | ||
17233 | The first of the two lines in parentheses tells Emacs to turn on Text | |
17234 | mode when you find a file, @emph{unless} that file should go into some | |
17235 | other mode, such as C mode. | |
17236 | ||
17237 | @cindex Per-buffer, local variables list | |
17238 | @cindex Local variables list, per-buffer, | |
17239 | @cindex Automatic mode selection | |
17240 | @cindex Mode selection, automatic | |
17241 | When Emacs reads a file, it looks at the extension to the file name, | |
17242 | if any. (The extension is the part that comes after a @samp{.}.) If | |
17243 | the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns | |
17244 | on C mode. Also, Emacs looks at first nonblank line of the file; if | |
17245 | the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs | |
17246 | possesses a list of extensions and specifications that it uses | |
17247 | automatically. In addition, Emacs looks near the last page for a | |
17248 | per-buffer, ``local variables list'', if any. | |
17249 | ||
17250 | @ifinfo | |
17251 | @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU | |
17252 | Emacs Manual}. | |
17253 | ||
17254 | @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs | |
17255 | Manual}. | |
17256 | @end ifinfo | |
17257 | @iftex | |
17258 | See sections ``How Major Modes are Chosen'' and ``Local Variables in | |
17259 | Files'' in @cite{The GNU Emacs Manual}. | |
17260 | @end iftex | |
17261 | ||
17262 | Now, back to the @file{.emacs} file. | |
17263 | ||
17264 | @need 800 | |
17265 | Here is the line again; how does it work? | |
17266 | ||
17267 | @cindex Text Mode turned on | |
17268 | @smallexample | |
4e3b4528 | 17269 | (setq major-mode 'text-mode) |
8cda6f8f GM |
17270 | @end smallexample |
17271 | ||
17272 | @noindent | |
17273 | This line is a short, but complete Emacs Lisp expression. | |
17274 | ||
17275 | We are already familiar with @code{setq}. It sets the following variable, | |
4e3b4528 SM |
17276 | @code{major-mode}, to the subsequent value, which is @code{text-mode}. |
17277 | The single quote mark before @code{text-mode} tells Emacs to deal directly | |
17278 | with the @code{text-mode} symbol, not with whatever it might stand for. | |
17279 | @xref{set & setq, , Setting the Value of a Variable}, | |
17280 | for a reminder of how @code{setq} works. | |
17281 | The main point is that there is no difference between the procedure you | |
17282 | use to set a value in your @file{.emacs} file and the procedure you use | |
17283 | anywhere else in Emacs. | |
8cda6f8f GM |
17284 | |
17285 | @need 800 | |
17286 | Here is the next line: | |
17287 | ||
17288 | @cindex Auto Fill mode turned on | |
17289 | @findex add-hook | |
17290 | @smallexample | |
17291 | (add-hook 'text-mode-hook 'turn-on-auto-fill) | |
17292 | @end smallexample | |
17293 | ||
17294 | @noindent | |
17295 | In this line, the @code{add-hook} command adds | |
17296 | @code{turn-on-auto-fill} to the variable. | |
17297 | ||
17298 | @code{turn-on-auto-fill} is the name of a program, that, you guessed | |
17299 | it!, turns on Auto Fill mode. | |
17300 | ||
17301 | Every time Emacs turns on Text mode, Emacs runs the commands `hooked' | |
17302 | onto Text mode. So every time Emacs turns on Text mode, Emacs also | |
17303 | turns on Auto Fill mode. | |
17304 | ||
17305 | In brief, the first line causes Emacs to enter Text mode when you edit a | |
17306 | file, unless the file name extension, a first non-blank line, or local | |
17307 | variables to tell Emacs otherwise. | |
17308 | ||
17309 | Text mode among other actions, sets the syntax table to work | |
17310 | conveniently for writers. In Text mode, Emacs considers an apostrophe | |
17311 | as part of a word like a letter; but Emacs does not consider a period | |
17312 | or a space as part of a word. Thus, @kbd{M-f} moves you over | |
17313 | @samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after | |
17314 | the @samp{t} of @samp{it's}. | |
17315 | ||
17316 | The second line causes Emacs to turn on Auto Fill mode when it turns | |
17317 | on Text mode. In Auto Fill mode, Emacs automatically breaks a line | |
17318 | that is too wide and brings the excessively wide part of the line down | |
17319 | to the next line. Emacs breaks lines between words, not within them. | |
17320 | ||
17321 | When Auto Fill mode is turned off, lines continue to the right as you | |
17322 | type them. Depending on how you set the value of | |
17323 | @code{truncate-lines}, the words you type either disappear off the | |
17324 | right side of the screen, or else are shown, in a rather ugly and | |
17325 | unreadable manner, as a continuation line on the screen. | |
17326 | ||
17327 | @need 1250 | |
17328 | In addition, in this part of my @file{.emacs} file, I tell the Emacs | |
17329 | fill commands to insert two spaces after a colon: | |
17330 | ||
17331 | @smallexample | |
17332 | (setq colon-double-space t) | |
17333 | @end smallexample | |
17334 | ||
d6adf7e7 | 17335 | @node Mail Aliases |
8cda6f8f GM |
17336 | @section Mail Aliases |
17337 | ||
17338 | Here is a @code{setq} that `turns on' mail aliases, along with more | |
17339 | reminders. | |
17340 | ||
17341 | @smallexample | |
17342 | @group | |
17343 | ;;; Mail mode | |
17344 | ; To enter mail mode, type `C-x m' | |
17345 | ; To enter RMAIL (for reading mail), | |
17346 | ; type `M-x rmail' | |
17347 | (setq mail-aliases t) | |
17348 | @end group | |
17349 | @end smallexample | |
17350 | ||
17351 | @cindex Mail aliases | |
17352 | @noindent | |
17353 | This @code{setq} command sets the value of the variable | |
17354 | @code{mail-aliases} to @code{t}. Since @code{t} means true, the line | |
17355 | says, in effect, ``Yes, use mail aliases.'' | |
17356 | ||
17357 | Mail aliases are convenient short names for long email addresses or | |
17358 | for lists of email addresses. The file where you keep your `aliases' | |
17359 | is @file{~/.mailrc}. You write an alias like this: | |
17360 | ||
17361 | @smallexample | |
17362 | alias geo george@@foobar.wiz.edu | |
17363 | @end smallexample | |
17364 | ||
17365 | @noindent | |
17366 | When you write a message to George, address it to @samp{geo}; the | |
17367 | mailer will automatically expand @samp{geo} to the full address. | |
17368 | ||
d6adf7e7 | 17369 | @node Indent Tabs Mode |
8cda6f8f GM |
17370 | @section Indent Tabs Mode |
17371 | @cindex Tabs, preventing | |
17372 | @findex indent-tabs-mode | |
17373 | ||
17374 | By default, Emacs inserts tabs in place of multiple spaces when it | |
17375 | formats a region. (For example, you might indent many lines of text | |
17376 | all at once with the @code{indent-region} command.) Tabs look fine on | |
17377 | a terminal or with ordinary printing, but they produce badly indented | |
17378 | output when you use @TeX{} or Texinfo since @TeX{} ignores tabs. | |
17379 | ||
17380 | @need 1250 | |
17381 | The following turns off Indent Tabs mode: | |
17382 | ||
17383 | @smallexample | |
17384 | @group | |
17385 | ;;; Prevent Extraneous Tabs | |
17386 | (setq-default indent-tabs-mode nil) | |
17387 | @end group | |
17388 | @end smallexample | |
17389 | ||
17390 | Note that this line uses @code{setq-default} rather than the | |
17391 | @code{setq} command that we have seen before. The @code{setq-default} | |
17392 | command sets values only in buffers that do not have their own local | |
17393 | values for the variable. | |
17394 | ||
17395 | @ifinfo | |
17396 | @xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}. | |
17397 | ||
17398 | @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs | |
17399 | Manual}. | |
17400 | @end ifinfo | |
17401 | @iftex | |
17402 | See sections ``Tabs vs.@: Spaces'' and ``Local Variables in | |
17403 | Files'' in @cite{The GNU Emacs Manual}. | |
17404 | @end iftex | |
17405 | ||
17406 | @need 1700 | |
d6adf7e7 | 17407 | @node Keybindings |
8cda6f8f GM |
17408 | @section Some Keybindings |
17409 | ||
17410 | Now for some personal keybindings: | |
17411 | ||
17412 | @smallexample | |
17413 | @group | |
17414 | ;;; Compare windows | |
17415 | (global-set-key "\C-cw" 'compare-windows) | |
17416 | @end group | |
17417 | @end smallexample | |
17418 | ||
17419 | @findex compare-windows | |
17420 | @code{compare-windows} is a nifty command that compares the text in | |
17421 | your current window with text in the next window. It makes the | |
17422 | comparison by starting at point in each window, moving over text in | |
17423 | each window as far as they match. I use this command all the time. | |
17424 | ||
17425 | This also shows how to set a key globally, for all modes. | |
17426 | ||
17427 | @cindex Setting a key globally | |
17428 | @cindex Global set key | |
17429 | @cindex Key setting globally | |
17430 | @findex global-set-key | |
17431 | The command is @code{global-set-key}. It is followed by the | |
17432 | keybinding. In a @file{.emacs} file, the keybinding is written as | |
17433 | shown: @code{\C-c} stands for `control-c', which means `press the | |
17434 | control key and the @key{c} key at the same time'. The @code{w} means | |
17435 | `press the @key{w} key'. The keybinding is surrounded by double | |
17436 | quotation marks. In documentation, you would write this as | |
17437 | @w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as | |
17438 | @kbd{M-c}, rather than a @key{CTRL} key, you would write | |
17439 | @w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, , | |
17440 | Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for | |
17441 | details.) | |
17442 | ||
17443 | The command invoked by the keys is @code{compare-windows}. Note that | |
17444 | @code{compare-windows} is preceded by a single quote; otherwise, Emacs | |
17445 | would first try to evaluate the symbol to determine its value. | |
17446 | ||
17447 | These three things, the double quotation marks, the backslash before | |
17448 | the @samp{C}, and the single quote mark are necessary parts of | |
17449 | keybinding that I tend to forget. Fortunately, I have come to | |
17450 | remember that I should look at my existing @file{.emacs} file, and | |
17451 | adapt what is there. | |
17452 | ||
17453 | As for the keybinding itself: @kbd{C-c w}. This combines the prefix | |
17454 | key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This | |
17455 | set of keys, @kbd{C-c} followed by a single character, is strictly | |
17456 | reserved for individuals' own use. (I call these `own' keys, since | |
17457 | these are for my own use.) You should always be able to create such a | |
17458 | keybinding for your own use without stomping on someone else's | |
17459 | keybinding. If you ever write an extension to Emacs, please avoid | |
17460 | taking any of these keys for public use. Create a key like @kbd{C-c | |
17461 | C-w} instead. Otherwise, we will run out of `own' keys. | |
17462 | ||
17463 | @need 1250 | |
17464 | Here is another keybinding, with a comment: | |
17465 | ||
17466 | @smallexample | |
17467 | @group | |
17468 | ;;; Keybinding for `occur' | |
17469 | ; I use occur a lot, so let's bind it to a key: | |
17470 | (global-set-key "\C-co" 'occur) | |
17471 | @end group | |
17472 | @end smallexample | |
17473 | ||
17474 | @findex occur | |
17475 | The @code{occur} command shows all the lines in the current buffer | |
17476 | that contain a match for a regular expression. Matching lines are | |
17477 | shown in a buffer called @file{*Occur*}. That buffer serves as a menu | |
17478 | to jump to occurrences. | |
17479 | ||
17480 | @findex global-unset-key | |
17481 | @cindex Unbinding key | |
17482 | @cindex Key unbinding | |
17483 | @need 1250 | |
17484 | Here is how to unbind a key, so it does not | |
17485 | work: | |
17486 | ||
17487 | @smallexample | |
17488 | @group | |
17489 | ;;; Unbind `C-x f' | |
17490 | (global-unset-key "\C-xf") | |
17491 | @end group | |
17492 | @end smallexample | |
17493 | ||
17494 | There is a reason for this unbinding: I found I inadvertently typed | |
17495 | @w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a | |
17496 | file, as I intended, I accidentally set the width for filled text, | |
17497 | almost always to a width I did not want. Since I hardly ever reset my | |
17498 | default width, I simply unbound the key. | |
17499 | ||
17500 | @findex list-buffers, @r{rebound} | |
17501 | @findex buffer-menu, @r{bound to key} | |
17502 | @need 1250 | |
17503 | The following rebinds an existing key: | |
17504 | ||
17505 | @smallexample | |
17506 | @group | |
17507 | ;;; Rebind `C-x C-b' for `buffer-menu' | |
17508 | (global-set-key "\C-x\C-b" 'buffer-menu) | |
17509 | @end group | |
17510 | @end smallexample | |
17511 | ||
17512 | By default, @kbd{C-x C-b} runs the | |
17513 | @code{list-buffers} command. This command lists | |
17514 | your buffers in @emph{another} window. Since I | |
17515 | almost always want to do something in that | |
17516 | window, I prefer the @code{buffer-menu} | |
17517 | command, which not only lists the buffers, | |
17518 | but moves point into that window. | |
17519 | ||
d6adf7e7 | 17520 | @node Keymaps |
8cda6f8f GM |
17521 | @section Keymaps |
17522 | @cindex Keymaps | |
17523 | @cindex Rebinding keys | |
17524 | ||
17525 | Emacs uses @dfn{keymaps} to record which keys call which commands. | |
17526 | When you use @code{global-set-key} to set the keybinding for a single | |
17527 | command in all parts of Emacs, you are specifying the keybinding in | |
17528 | @code{current-global-map}. | |
17529 | ||
17530 | Specific modes, such as C mode or Text mode, have their own keymaps; | |
17531 | the mode-specific keymaps override the global map that is shared by | |
17532 | all buffers. | |
17533 | ||
17534 | The @code{global-set-key} function binds, or rebinds, the global | |
17535 | keymap. For example, the following binds the key @kbd{C-x C-b} to the | |
17536 | function @code{buffer-menu}: | |
17537 | ||
17538 | @smallexample | |
17539 | (global-set-key "\C-x\C-b" 'buffer-menu) | |
17540 | @end smallexample | |
17541 | ||
17542 | Mode-specific keymaps are bound using the @code{define-key} function, | |
17543 | which takes a specific keymap as an argument, as well as the key and | |
17544 | the command. For example, my @file{.emacs} file contains the | |
17545 | following expression to bind the @code{texinfo-insert-@@group} command | |
17546 | to @kbd{C-c C-c g}: | |
17547 | ||
17548 | @smallexample | |
17549 | @group | |
17550 | (define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group) | |
17551 | @end group | |
17552 | @end smallexample | |
17553 | ||
17554 | @noindent | |
17555 | The @code{texinfo-insert-@@group} function itself is a little extension | |
17556 | to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I | |
17557 | use this command all the time and prefer to type the three strokes | |
17558 | @kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}. | |
17559 | (@samp{@@group} and its matching @samp{@@end group} are commands that | |
17560 | keep all enclosed text together on one page; many multi-line examples | |
17561 | in this book are surrounded by @samp{@@group @dots{} @@end group}.) | |
17562 | ||
17563 | @need 1250 | |
17564 | Here is the @code{texinfo-insert-@@group} function definition: | |
17565 | ||
17566 | @smallexample | |
17567 | @group | |
17568 | (defun texinfo-insert-@@group () | |
17569 | "Insert the string @@group in a Texinfo buffer." | |
17570 | (interactive) | |
17571 | (beginning-of-line) | |
17572 | (insert "@@group\n")) | |
17573 | @end group | |
17574 | @end smallexample | |
17575 | ||
17576 | (Of course, I could have used Abbrev mode to save typing, rather than | |
17577 | write a function to insert a word; but I prefer key strokes consistent | |
17578 | with other Texinfo mode key bindings.) | |
17579 | ||
17580 | You will see numerous @code{define-key} expressions in | |
17581 | @file{loaddefs.el} as well as in the various mode libraries, such as | |
17582 | @file{cc-mode.el} and @file{lisp-mode.el}. | |
17583 | ||
17584 | @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs | |
17585 | Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp | |
17586 | Reference Manual}, for more information about keymaps. | |
17587 | ||
d6adf7e7 | 17588 | @node Loading Files |
8cda6f8f GM |
17589 | @section Loading Files |
17590 | @cindex Loading files | |
17591 | @c findex load | |
17592 | ||
17593 | Many people in the GNU Emacs community have written extensions to | |
17594 | Emacs. As time goes by, these extensions are often included in new | |
17595 | releases. For example, the Calendar and Diary packages are now part | |
17596 | of the standard GNU Emacs, as is Calc. | |
17597 | ||
17598 | You can use a @code{load} command to evaluate a complete file and | |
17599 | thereby install all the functions and variables in the file into Emacs. | |
17600 | For example: | |
17601 | ||
17602 | @c (auto-compression-mode t) | |
17603 | ||
17604 | @smallexample | |
17605 | (load "~/emacs/slowsplit") | |
17606 | @end smallexample | |
17607 | ||
1df7defd | 17608 | This evaluates, i.e., loads, the @file{slowsplit.el} file or if it |
8cda6f8f GM |
17609 | exists, the faster, byte compiled @file{slowsplit.elc} file from the |
17610 | @file{emacs} sub-directory of your home directory. The file contains | |
17611 | the function @code{split-window-quietly}, which John Robinson wrote in | |
17612 | 1989. | |
17613 | ||
17614 | The @code{split-window-quietly} function splits a window with the | |
17615 | minimum of redisplay. I installed it in 1989 because it worked well | |
17616 | with the slow 1200 baud terminals I was then using. Nowadays, I only | |
17617 | occasionally come across such a slow connection, but I continue to use | |
17618 | the function because I like the way it leaves the bottom half of a | |
17619 | buffer in the lower of the new windows and the top half in the upper | |
17620 | window. | |
17621 | ||
17622 | @need 1250 | |
17623 | To replace the key binding for the default | |
17624 | @code{split-window-vertically}, you must also unset that key and bind | |
17625 | the keys to @code{split-window-quietly}, like this: | |
17626 | ||
17627 | @smallexample | |
17628 | @group | |
17629 | (global-unset-key "\C-x2") | |
17630 | (global-set-key "\C-x2" 'split-window-quietly) | |
17631 | @end group | |
17632 | @end smallexample | |
17633 | ||
17634 | @vindex load-path | |
17635 | If you load many extensions, as I do, then instead of specifying the | |
17636 | exact location of the extension file, as shown above, you can specify | |
44e97401 | 17637 | that directory as part of Emacs's @code{load-path}. Then, when Emacs |
8cda6f8f GM |
17638 | loads a file, it will search that directory as well as its default |
17639 | list of directories. (The default list is specified in @file{paths.h} | |
17640 | when Emacs is built.) | |
17641 | ||
17642 | @need 1250 | |
17643 | The following command adds your @file{~/emacs} directory to the | |
17644 | existing load path: | |
17645 | ||
17646 | @smallexample | |
17647 | @group | |
17648 | ;;; Emacs Load Path | |
17649 | (setq load-path (cons "~/emacs" load-path)) | |
17650 | @end group | |
17651 | @end smallexample | |
17652 | ||
17653 | Incidentally, @code{load-library} is an interactive interface to the | |
17654 | @code{load} function. The complete function looks like this: | |
17655 | ||
17656 | @findex load-library | |
17657 | @smallexample | |
17658 | @group | |
17659 | (defun load-library (library) | |
17660 | "Load the library named LIBRARY. | |
17661 | This is an interface to the function `load'." | |
17662 | (interactive | |
17663 | (list (completing-read "Load library: " | |
e0e10d9d | 17664 | (apply-partially 'locate-file-completion-table |
f51f97dd SM |
17665 | load-path |
17666 | (get-load-suffixes))))) | |
8cda6f8f GM |
17667 | (load library)) |
17668 | @end group | |
17669 | @end smallexample | |
17670 | ||
17671 | The name of the function, @code{load-library}, comes from the use of | |
17672 | `library' as a conventional synonym for `file'. The source for the | |
17673 | @code{load-library} command is in the @file{files.el} library. | |
17674 | ||
17675 | Another interactive command that does a slightly different job is | |
17676 | @code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for | |
17677 | Emacs, emacs, The GNU Emacs Manual}, for information on the | |
17678 | distinction between @code{load-library} and this command. | |
17679 | ||
d6adf7e7 | 17680 | @node Autoload |
8cda6f8f GM |
17681 | @section Autoloading |
17682 | @findex autoload | |
17683 | ||
17684 | Instead of installing a function by loading the file that contains it, | |
17685 | or by evaluating the function definition, you can make the function | |
17686 | available but not actually install it until it is first called. This | |
17687 | is called @dfn{autoloading}. | |
17688 | ||
17689 | When you execute an autoloaded function, Emacs automatically evaluates | |
17690 | the file that contains the definition, and then calls the function. | |
17691 | ||
17692 | Emacs starts quicker with autoloaded functions, since their libraries | |
17693 | are not loaded right away; but you need to wait a moment when you | |
17694 | first use such a function, while its containing file is evaluated. | |
17695 | ||
17696 | Rarely used functions are frequently autoloaded. The | |
17697 | @file{loaddefs.el} library contains hundreds of autoloaded functions, | |
17698 | from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may | |
17699 | come to use a `rare' function frequently. When you do, you should | |
17700 | load that function's file with a @code{load} expression in your | |
17701 | @file{.emacs} file. | |
17702 | ||
17703 | In my @file{.emacs} file, I load 14 libraries that contain functions | |
17704 | that would otherwise be autoloaded. (Actually, it would have been | |
17705 | better to include these files in my `dumped' Emacs, but I forgot. | |
17706 | @xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp | |
17707 | Reference Manual}, and the @file{INSTALL} file for more about | |
17708 | dumping.) | |
17709 | ||
17710 | You may also want to include autoloaded expressions in your @file{.emacs} | |
17711 | file. @code{autoload} is a built-in function that takes up to five | |
17712 | arguments, the final three of which are optional. The first argument | |
17713 | is the name of the function to be autoloaded; the second is the name | |
17714 | of the file to be loaded. The third argument is documentation for the | |
17715 | function, and the fourth tells whether the function can be called | |
17716 | interactively. The fifth argument tells what type of | |
17717 | object---@code{autoload} can handle a keymap or macro as well as a | |
17718 | function (the default is a function). | |
17719 | ||
17720 | @need 800 | |
17721 | Here is a typical example: | |
17722 | ||
17723 | @smallexample | |
17724 | @group | |
17725 | (autoload 'html-helper-mode | |
17726 | "html-helper-mode" "Edit HTML documents" t) | |
17727 | @end group | |
17728 | @end smallexample | |
17729 | ||
17730 | @noindent | |
17731 | (@code{html-helper-mode} is an older alternative to @code{html-mode}, | |
17732 | which is a standard part of the distribution.) | |
17733 | ||
17734 | @noindent | |
17735 | This expression autoloads the @code{html-helper-mode} function. It | |
17736 | takes it from the @file{html-helper-mode.el} file (or from the byte | |
a9097c6d KB |
17737 | compiled version @file{html-helper-mode.elc}, if that exists.) The |
17738 | file must be located in a directory specified by @code{load-path}. | |
17739 | The documentation says that this is a mode to help you edit documents | |
8cda6f8f GM |
17740 | written in the HyperText Markup Language. You can call this mode |
17741 | interactively by typing @kbd{M-x html-helper-mode}. (You need to | |
17742 | duplicate the function's regular documentation in the autoload | |
17743 | expression because the regular function is not yet loaded, so its | |
17744 | documentation is not available.) | |
17745 | ||
17746 | @xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference | |
17747 | Manual}, for more information. | |
17748 | ||
d6adf7e7 | 17749 | @node Simple Extension |
8cda6f8f GM |
17750 | @section A Simple Extension: @code{line-to-top-of-window} |
17751 | @findex line-to-top-of-window | |
17752 | @cindex Simple extension in @file{.emacs} file | |
17753 | ||
17754 | Here is a simple extension to Emacs that moves the line point is on to | |
17755 | the top of the window. I use this all the time, to make text easier | |
17756 | to read. | |
17757 | ||
17758 | You can put the following code into a separate file and then load it | |
17759 | from your @file{.emacs} file, or you can include it within your | |
17760 | @file{.emacs} file. | |
17761 | ||
17762 | @need 1250 | |
17763 | Here is the definition: | |
17764 | ||
17765 | @smallexample | |
17766 | @group | |
17767 | ;;; Line to top of window; | |
17768 | ;;; replace three keystroke sequence C-u 0 C-l | |
17769 | (defun line-to-top-of-window () | |
17770 | "Move the line point is on to top of window." | |
17771 | (interactive) | |
17772 | (recenter 0)) | |
17773 | @end group | |
17774 | @end smallexample | |
17775 | ||
17776 | @need 1250 | |
17777 | Now for the keybinding. | |
17778 | ||
17779 | Nowadays, function keys as well as mouse button events and | |
17780 | non-@sc{ascii} characters are written within square brackets, without | |
17781 | quotation marks. (In Emacs version 18 and before, you had to write | |
17782 | different function key bindings for each different make of terminal.) | |
17783 | ||
17784 | I bind @code{line-to-top-of-window} to my @key{F6} function key like | |
17785 | this: | |
17786 | ||
17787 | @smallexample | |
17788 | (global-set-key [f6] 'line-to-top-of-window) | |
17789 | @end smallexample | |
17790 | ||
17791 | For more information, see @ref{Init Rebinding, , Rebinding Keys in | |
17792 | Your Init File, emacs, The GNU Emacs Manual}. | |
17793 | ||
17794 | @cindex Conditional 'twixt two versions of Emacs | |
17795 | @cindex Version of Emacs, choosing | |
17796 | @cindex Emacs version, choosing | |
6dd28193 | 17797 | If you run two versions of GNU Emacs, such as versions 22 and 23, and |
8cda6f8f GM |
17798 | use one @file{.emacs} file, you can select which code to evaluate with |
17799 | the following conditional: | |
17800 | ||
17801 | @smallexample | |
17802 | @group | |
17803 | (cond | |
6dd28193 | 17804 | ((= 22 emacs-major-version) |
8cda6f8f | 17805 | ;; evaluate version 22 code |
6dd28193 CY |
17806 | ( @dots{} )) |
17807 | ((= 23 emacs-major-version) | |
17808 | ;; evaluate version 23 code | |
8cda6f8f GM |
17809 | ( @dots{} ))) |
17810 | @end group | |
17811 | @end smallexample | |
17812 | ||
8f4ea8e0 | 17813 | For example, recent versions blink |
8cda6f8f GM |
17814 | their cursors by default. I hate such blinking, as well as other |
17815 | features, so I placed the following in my @file{.emacs} | |
17816 | file@footnote{When I start instances of Emacs that do not load my | |
17817 | @file{.emacs} file or any site file, I also turn off blinking: | |
17818 | ||
17819 | @smallexample | |
17820 | emacs -q --no-site-file -eval '(blink-cursor-mode nil)' | |
17821 | ||
17822 | @exdent Or nowadays, using an even more sophisticated set of options, | |
17823 | ||
9450ac06 | 17824 | emacs -Q -D |
8cda6f8f GM |
17825 | @end smallexample |
17826 | }: | |
17827 | ||
17828 | @smallexample | |
17829 | @group | |
6dd28193 CY |
17830 | (when (>= emacs-major-version 21) |
17831 | (blink-cursor-mode 0) | |
17832 | ;; Insert newline when you press `C-n' (next-line) | |
17833 | ;; at the end of the buffer | |
17834 | (setq next-line-add-newlines t) | |
8cda6f8f GM |
17835 | @end group |
17836 | @group | |
6dd28193 CY |
17837 | ;; Turn on image viewing |
17838 | (auto-image-file-mode t) | |
8cda6f8f GM |
17839 | @end group |
17840 | @group | |
6dd28193 CY |
17841 | ;; Turn on menu bar (this bar has text) |
17842 | ;; (Use numeric argument to turn on) | |
17843 | (menu-bar-mode 1) | |
8cda6f8f GM |
17844 | @end group |
17845 | @group | |
6dd28193 CY |
17846 | ;; Turn off tool bar (this bar has icons) |
17847 | ;; (Use numeric argument to turn on) | |
17848 | (tool-bar-mode nil) | |
8cda6f8f | 17849 | @end group |
8cda6f8f | 17850 | @group |
6dd28193 CY |
17851 | ;; Turn off tooltip mode for tool bar |
17852 | ;; (This mode causes icon explanations to pop up) | |
17853 | ;; (Use numeric argument to turn on) | |
17854 | (tooltip-mode nil) | |
17855 | ;; If tooltips turned on, make tips appear promptly | |
17856 | (setq tooltip-delay 0.1) ; default is 0.7 second | |
17857 | ) | |
8cda6f8f GM |
17858 | @end group |
17859 | @end smallexample | |
17860 | ||
d6adf7e7 | 17861 | @node X11 Colors |
8cda6f8f GM |
17862 | @section X11 Colors |
17863 | ||
17864 | You can specify colors when you use Emacs with the MIT X Windowing | |
17865 | system. | |
17866 | ||
17867 | I dislike the default colors and specify my own. | |
17868 | ||
17869 | @need 1250 | |
17870 | Here are the expressions in my @file{.emacs} | |
17871 | file that set values: | |
17872 | ||
17873 | @smallexample | |
17874 | @group | |
17875 | ;; Set cursor color | |
17876 | (set-cursor-color "white") | |
17877 | ||
17878 | ;; Set mouse color | |
17879 | (set-mouse-color "white") | |
17880 | ||
17881 | ;; Set foreground and background | |
17882 | (set-foreground-color "white") | |
17883 | (set-background-color "darkblue") | |
17884 | @end group | |
17885 | ||
17886 | @group | |
17887 | ;;; Set highlighting colors for isearch and drag | |
17888 | (set-face-foreground 'highlight "white") | |
17889 | (set-face-background 'highlight "blue") | |
17890 | @end group | |
17891 | ||
17892 | @group | |
17893 | (set-face-foreground 'region "cyan") | |
17894 | (set-face-background 'region "blue") | |
17895 | @end group | |
17896 | ||
17897 | @group | |
17898 | (set-face-foreground 'secondary-selection "skyblue") | |
17899 | (set-face-background 'secondary-selection "darkblue") | |
17900 | @end group | |
17901 | ||
17902 | @group | |
17903 | ;; Set calendar highlighting colors | |
17904 | (setq calendar-load-hook | |
d1069532 SM |
17905 | (lambda () |
17906 | (set-face-foreground 'diary-face "skyblue") | |
17907 | (set-face-background 'holiday-face "slate blue") | |
17908 | (set-face-foreground 'holiday-face "white"))) | |
8cda6f8f GM |
17909 | @end group |
17910 | @end smallexample | |
17911 | ||
17912 | The various shades of blue soothe my eye and prevent me from seeing | |
17913 | the screen flicker. | |
17914 | ||
17915 | Alternatively, I could have set my specifications in various X | |
17916 | initialization files. For example, I could set the foreground, | |
17917 | background, cursor, and pointer (i.e., mouse) colors in my | |
17918 | @file{~/.Xresources} file like this: | |
17919 | ||
17920 | @smallexample | |
17921 | @group | |
17922 | Emacs*foreground: white | |
17923 | Emacs*background: darkblue | |
17924 | Emacs*cursorColor: white | |
17925 | Emacs*pointerColor: white | |
17926 | @end group | |
17927 | @end smallexample | |
17928 | ||
17929 | In any event, since it is not part of Emacs, I set the root color of | |
17930 | my X window in my @file{~/.xinitrc} file, like this@footnote{I also | |
17931 | run more modern window managers, such as Enlightenment, Gnome, or KDE; | |
17932 | in those cases, I often specify an image rather than a plain color.}: | |
17933 | ||
17934 | @smallexample | |
17935 | xsetroot -solid Navy -fg white & | |
17936 | @end smallexample | |
17937 | ||
17938 | @need 1700 | |
d6adf7e7 | 17939 | @node Miscellaneous |
8cda6f8f GM |
17940 | @section Miscellaneous Settings for a @file{.emacs} File |
17941 | ||
17942 | @need 1250 | |
17943 | Here are a few miscellaneous settings: | |
17944 | @sp 1 | |
17945 | ||
17946 | @itemize @minus | |
17947 | @item | |
17948 | Set the shape and color of the mouse cursor: | |
17949 | ||
17950 | @smallexample | |
17951 | @group | |
17952 | ; Cursor shapes are defined in | |
17953 | ; `/usr/include/X11/cursorfont.h'; | |
17954 | ; for example, the `target' cursor is number 128; | |
17955 | ; the `top_left_arrow' cursor is number 132. | |
17956 | @end group | |
17957 | ||
17958 | @group | |
17959 | (let ((mpointer (x-get-resource "*mpointer" | |
17960 | "*emacs*mpointer"))) | |
17961 | ;; If you have not set your mouse pointer | |
17962 | ;; then set it, otherwise leave as is: | |
17963 | (if (eq mpointer nil) | |
17964 | (setq mpointer "132")) ; top_left_arrow | |
17965 | @end group | |
17966 | @group | |
17967 | (setq x-pointer-shape (string-to-int mpointer)) | |
17968 | (set-mouse-color "white")) | |
17969 | @end group | |
17970 | @end smallexample | |
17971 | ||
17972 | @item | |
17973 | Or you can set the values of a variety of features in an alist, like | |
17974 | this: | |
17975 | ||
17976 | @smallexample | |
17977 | @group | |
17978 | (setq-default | |
17979 | default-frame-alist | |
17980 | '((cursor-color . "white") | |
17981 | (mouse-color . "white") | |
17982 | (foreground-color . "white") | |
17983 | (background-color . "DodgerBlue4") | |
17984 | ;; (cursor-type . bar) | |
17985 | (cursor-type . box) | |
17986 | @end group | |
17987 | @group | |
17988 | (tool-bar-lines . 0) | |
17989 | (menu-bar-lines . 1) | |
17990 | (width . 80) | |
17991 | (height . 58) | |
17992 | (font . | |
17993 | "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1") | |
17994 | )) | |
17995 | @end group | |
17996 | @end smallexample | |
17997 | ||
17998 | @item | |
17999 | Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL} | |
18000 | into @kbd{@key{CTRL}-h}.@* | |
18001 | (Some older keyboards needed this, although I have not seen the | |
18002 | problem recently.) | |
18003 | ||
18004 | @smallexample | |
18005 | @group | |
18006 | ;; Translate `C-h' to <DEL>. | |
18007 | ; (keyboard-translate ?\C-h ?\C-?) | |
18008 | ||
18009 | ;; Translate <DEL> to `C-h'. | |
18010 | (keyboard-translate ?\C-? ?\C-h) | |
18011 | @end group | |
18012 | @end smallexample | |
18013 | ||
18014 | @item Turn off a blinking cursor! | |
18015 | ||
18016 | @smallexample | |
18017 | @group | |
18018 | (if (fboundp 'blink-cursor-mode) | |
18019 | (blink-cursor-mode -1)) | |
18020 | @end group | |
18021 | @end smallexample | |
18022 | ||
18023 | @noindent | |
18024 | or start GNU Emacs with the command @code{emacs -nbc}. | |
18025 | ||
18026 | @need 1250 | |
18027 | @item When using `grep'@* | |
18028 | @samp{-i}@w{ } Ignore case distinctions@* | |
18029 | @samp{-n}@w{ } Prefix each line of output with line number@* | |
18030 | @samp{-H}@w{ } Print the filename for each match.@* | |
18031 | @samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-} | |
18032 | ||
18033 | @smallexample | |
18034 | (setq grep-command "grep -i -nH -e ") | |
18035 | @end smallexample | |
18036 | ||
18037 | @ignore | |
18038 | @c Evidently, no longer needed in GNU Emacs 22 | |
18039 | ||
18040 | item Automatically uncompress compressed files when visiting them | |
18041 | ||
18042 | smallexample | |
18043 | (load "uncompress") | |
18044 | end smallexample | |
18045 | ||
18046 | @end ignore | |
18047 | ||
18048 | @item Find an existing buffer, even if it has a different name@* | |
18049 | This avoids problems with symbolic links. | |
18050 | ||
18051 | @smallexample | |
18052 | (setq find-file-existing-other-name t) | |
18053 | @end smallexample | |
18054 | ||
18055 | @item Set your language environment and default input method | |
18056 | ||
18057 | @smallexample | |
18058 | @group | |
18059 | (set-language-environment "latin-1") | |
18060 | ;; Remember you can enable or disable multilingual text input | |
18061 | ;; with the @code{toggle-input-method'} (@kbd{C-\}) command | |
18062 | (setq default-input-method "latin-1-prefix") | |
18063 | @end group | |
18064 | @end smallexample | |
18065 | ||
18066 | If you want to write with Chinese `GB' characters, set this instead: | |
18067 | ||
18068 | @smallexample | |
18069 | @group | |
18070 | (set-language-environment "Chinese-GB") | |
18071 | (setq default-input-method "chinese-tonepy") | |
18072 | @end group | |
18073 | @end smallexample | |
18074 | @end itemize | |
18075 | ||
18076 | @subsubheading Fixing Unpleasant Key Bindings | |
18077 | @cindex Key bindings, fixing | |
18078 | @cindex Bindings, key, fixing unpleasant | |
18079 | ||
18080 | Some systems bind keys unpleasantly. Sometimes, for example, the | |
18081 | @key{CTRL} key appears in an awkward spot rather than at the far left | |
18082 | of the home row. | |
18083 | ||
18084 | Usually, when people fix these sorts of keybindings, they do not | |
18085 | change their @file{~/.emacs} file. Instead, they bind the proper keys | |
18086 | on their consoles with the @code{loadkeys} or @code{install-keymap} | |
18087 | commands in their boot script and then include @code{xmodmap} commands | |
18088 | in their @file{.xinitrc} or @file{.Xsession} file for X Windows. | |
18089 | ||
18090 | @need 1250 | |
18091 | @noindent | |
18092 | For a boot script: | |
18093 | ||
18094 | @smallexample | |
18095 | @group | |
18096 | loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz | |
18097 | @exdent or | |
18098 | install-keymap emacs2 | |
18099 | @end group | |
18100 | @end smallexample | |
18101 | ||
18102 | @need 1250 | |
18103 | @noindent | |
18104 | For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps | |
18105 | Lock} key is at the far left of the home row: | |
18106 | ||
18107 | @smallexample | |
18108 | @group | |
18109 | # Bind the key labeled `Caps Lock' to `Control' | |
18110 | # (Such a broken user interface suggests that keyboard manufacturers | |
18111 | # think that computers are typewriters from 1885.) | |
18112 | ||
18113 | xmodmap -e "clear Lock" | |
18114 | xmodmap -e "add Control = Caps_Lock" | |
18115 | @end group | |
18116 | @end smallexample | |
18117 | ||
18118 | @need 1250 | |
18119 | @noindent | |
18120 | In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT} | |
18121 | key to a @key{META} key: | |
18122 | ||
18123 | @smallexample | |
18124 | @group | |
18125 | # Some ill designed keyboards have a key labeled ALT and no Meta | |
18126 | xmodmap -e "keysym Alt_L = Meta_L Alt_L" | |
18127 | @end group | |
18128 | @end smallexample | |
18129 | ||
18130 | @need 1700 | |
d6adf7e7 | 18131 | @node Mode Line |
8cda6f8f | 18132 | @section A Modified Mode Line |
cd61af01 | 18133 | @vindex mode-line-format |
8cda6f8f GM |
18134 | @cindex Mode line format |
18135 | ||
18136 | Finally, a feature I really like: a modified mode line. | |
18137 | ||
18138 | When I work over a network, I forget which machine I am using. Also, | |
18139 | I tend to I lose track of where I am, and which line point is on. | |
18140 | ||
18141 | So I reset my mode line to look like this: | |
18142 | ||
18143 | @smallexample | |
18144 | -:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top | |
18145 | @end smallexample | |
18146 | ||
18147 | I am visiting a file called @file{foo.texi}, on my machine | |
18148 | @file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in | |
18149 | Texinfo mode, and am at the top of the buffer. | |
18150 | ||
18151 | @need 1200 | |
18152 | My @file{.emacs} file has a section that looks like this: | |
18153 | ||
18154 | @smallexample | |
18155 | @group | |
18156 | ;; Set a Mode Line that tells me which machine, which directory, | |
18157 | ;; and which line I am on, plus the other customary information. | |
cd61af01 | 18158 | (setq-default mode-line-format |
8cda6f8f GM |
18159 | (quote |
18160 | (#("-" 0 1 | |
18161 | (help-echo | |
18162 | "mouse-1: select window, mouse-2: delete others ...")) | |
18163 | mode-line-mule-info | |
18164 | mode-line-modified | |
18165 | mode-line-frame-identification | |
18166 | " " | |
18167 | @end group | |
18168 | @group | |
18169 | mode-line-buffer-identification | |
18170 | " " | |
18171 | (:eval (substring | |
18172 | (system-name) 0 (string-match "\\..+" (system-name)))) | |
18173 | ":" | |
18174 | default-directory | |
18175 | #(" " 0 1 | |
18176 | (help-echo | |
18177 | "mouse-1: select window, mouse-2: delete others ...")) | |
18178 | (line-number-mode " Line %l ") | |
18179 | global-mode-string | |
18180 | @end group | |
18181 | @group | |
18182 | #(" %[(" 0 6 | |
18183 | (help-echo | |
18184 | "mouse-1: select window, mouse-2: delete others ...")) | |
18185 | (:eval (mode-line-mode-name)) | |
18186 | mode-line-process | |
18187 | minor-mode-alist | |
18188 | #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...))) | |
18189 | ")%] " | |
18190 | (-3 . "%P") | |
18191 | ;; "-%-" | |
18192 | ))) | |
18193 | @end group | |
18194 | @end smallexample | |
18195 | ||
18196 | @noindent | |
18197 | Here, I redefine the default mode line. Most of the parts are from | |
18198 | the original; but I make a few changes. I set the @emph{default} mode | |
18199 | line format so as to permit various modes, such as Info, to override | |
18200 | it. | |
18201 | ||
18202 | Many elements in the list are self-explanatory: | |
18203 | @code{mode-line-modified} is a variable that tells whether the buffer | |
18204 | has been modified, @code{mode-name} tells the name of the mode, and so | |
18205 | on. However, the format looks complicated because of two features we | |
18206 | have not discussed. | |
18207 | ||
18208 | @cindex Properties, in mode line example | |
18209 | The first string in the mode line is a dash or hyphen, @samp{-}. In | |
18210 | the old days, it would have been specified simply as @code{"-"}. But | |
18211 | nowadays, Emacs can add properties to a string, such as highlighting | |
18212 | or, as in this case, a help feature. If you place your mouse cursor | |
18213 | over the hyphen, some help information appears (By default, you must | |
18214 | wait seven-tenths of a second before the information appears. You can | |
18215 | change that timing by changing the value of @code{tooltip-delay}.) | |
18216 | ||
18217 | @need 1000 | |
18218 | The new string format has a special syntax: | |
18219 | ||
18220 | @smallexample | |
18221 | #("-" 0 1 (help-echo "mouse-1: select window, ...")) | |
18222 | @end smallexample | |
18223 | ||
18224 | @noindent | |
18225 | The @code{#(} begins a list. The first element of the list is the | |
18226 | string itself, just one @samp{-}. The second and third | |
18227 | elements specify the range over which the fourth element applies. A | |
18228 | range starts @emph{after} a character, so a zero means the range | |
18229 | starts just before the first character; a 1 means that the range ends | |
18230 | just after the first character. The third element is the property for | |
18231 | the range. It consists of a property list, a | |
18232 | property name, in this case, @samp{help-echo}, followed by a value, in this | |
18233 | case, a string. The second, third, and fourth elements of this new | |
18234 | string format can be repeated. | |
18235 | ||
18236 | @xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp | |
18237 | Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format, | |
18238 | elisp, The GNU Emacs Lisp Reference Manual}, for more information. | |
18239 | ||
18240 | @code{mode-line-buffer-identification} | |
18241 | displays the current buffer name. It is a list | |
18242 | beginning @code{(#("%12b" 0 4 @dots{}}. | |
18243 | The @code{#(} begins the list. | |
18244 | ||
18245 | The @samp{"%12b"} displays the current buffer name, using the | |
18246 | @code{buffer-name} function with which we are familiar; the `12' | |
18247 | specifies the maximum number of characters that will be displayed. | |
18248 | When a name has fewer characters, whitespace is added to fill out to | |
18249 | this number. (Buffer names can and often should be longer than 12 | |
18250 | characters; this length works well in a typical 80 column wide | |
18251 | window.) | |
18252 | ||
18253 | @code{:eval} says to evaluate the following form and use the result as | |
18254 | a string to display. In this case, the expression displays the first | |
18255 | component of the full system name. The end of the first component is | |
18256 | a @samp{.} (`period'), so I use the @code{string-match} function to | |
18257 | tell me the length of the first component. The substring from the | |
18258 | zeroth character to that length is the name of the machine. | |
18259 | ||
18260 | @need 1250 | |
18261 | This is the expression: | |
18262 | ||
18263 | @smallexample | |
18264 | @group | |
18265 | (:eval (substring | |
18266 | (system-name) 0 (string-match "\\..+" (system-name)))) | |
18267 | @end group | |
18268 | @end smallexample | |
18269 | ||
18270 | @samp{%[} and @samp{%]} cause a pair of square brackets | |
18271 | to appear for each recursive editing level. @samp{%n} says `Narrow' | |
18272 | when narrowing is in effect. @samp{%P} tells you the percentage of | |
18273 | the buffer that is above the bottom of the window, or `Top', `Bottom', | |
18274 | or `All'. (A lower case @samp{p} tell you the percentage above the | |
18275 | @emph{top} of the window.) @samp{%-} inserts enough dashes to fill | |
18276 | out the line. | |
18277 | ||
f99f1641 | 18278 | Remember, ``You don't have to like Emacs to like it''---your own |
8cda6f8f GM |
18279 | Emacs can have different colors, different commands, and different |
18280 | keys than a default Emacs. | |
18281 | ||
18282 | On the other hand, if you want to bring up a plain `out of the box' | |
18283 | Emacs, with no customization, type: | |
18284 | ||
18285 | @smallexample | |
18286 | emacs -q | |
18287 | @end smallexample | |
18288 | ||
18289 | @noindent | |
18290 | This will start an Emacs that does @emph{not} load your | |
18291 | @file{~/.emacs} initialization file. A plain, default Emacs. Nothing | |
18292 | more. | |
18293 | ||
d6adf7e7 | 18294 | @node Debugging |
8cda6f8f GM |
18295 | @chapter Debugging |
18296 | @cindex debugging | |
18297 | ||
18298 | GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The | |
18299 | first is built into the internals of Emacs and is always with you; | |
18300 | the second requires that you instrument a function before you can use it. | |
18301 | ||
18302 | Both debuggers are described extensively in @ref{Debugging, , | |
18303 | Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}. | |
18304 | In this chapter, I will walk through a short example of each. | |
18305 | ||
18306 | @menu | |
18307 | * debug:: How to use the built-in debugger. | |
18308 | * debug-on-entry:: Start debugging when you call a function. | |
18309 | * debug-on-quit:: Start debugging when you quit with @kbd{C-g}. | |
18310 | * edebug:: How to use Edebug, a source level debugger. | |
18311 | * Debugging Exercises:: | |
18312 | @end menu | |
18313 | ||
d6adf7e7 | 18314 | @node debug |
8cda6f8f GM |
18315 | @section @code{debug} |
18316 | @findex debug | |
18317 | ||
18318 | Suppose you have written a function definition that is intended to | |
18319 | return the sum of the numbers 1 through a given number. (This is the | |
18320 | @code{triangle} function discussed earlier. @xref{Decrementing | |
18321 | Example, , Example with Decrementing Counter}, for a discussion.) | |
18322 | @c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.) | |
18323 | ||
18324 | However, your function definition has a bug. You have mistyped | |
18325 | @samp{1=} for @samp{1-}. Here is the broken definition: | |
18326 | ||
18327 | @findex triangle-bugged | |
18328 | @smallexample | |
18329 | @group | |
18330 | (defun triangle-bugged (number) | |
18331 | "Return sum of numbers 1 through NUMBER inclusive." | |
18332 | (let ((total 0)) | |
18333 | (while (> number 0) | |
18334 | (setq total (+ total number)) | |
18335 | (setq number (1= number))) ; @r{Error here.} | |
18336 | total)) | |
18337 | @end group | |
18338 | @end smallexample | |
18339 | ||
18340 | If you are reading this in Info, you can evaluate this definition in | |
18341 | the normal fashion. You will see @code{triangle-bugged} appear in the | |
18342 | echo area. | |
18343 | ||
18344 | @need 1250 | |
18345 | Now evaluate the @code{triangle-bugged} function with an | |
18346 | argument of 4: | |
18347 | ||
18348 | @smallexample | |
18349 | (triangle-bugged 4) | |
18350 | @end smallexample | |
18351 | ||
18352 | @noindent | |
18353 | In a recent GNU Emacs, you will create and enter a @file{*Backtrace*} | |
18354 | buffer that says: | |
18355 | ||
18356 | @noindent | |
18357 | @smallexample | |
18358 | @group | |
18359 | ---------- Buffer: *Backtrace* ---------- | |
18360 | Debugger entered--Lisp error: (void-function 1=) | |
18361 | (1= number) | |
18362 | (setq number (1= number)) | |
18363 | (while (> number 0) (setq total (+ total number)) | |
18364 | (setq number (1= number))) | |
18365 | (let ((total 0)) (while (> number 0) (setq total ...) | |
18366 | (setq number ...)) total) | |
18367 | triangle-bugged(4) | |
18368 | @end group | |
18369 | @group | |
18370 | eval((triangle-bugged 4)) | |
18371 | eval-last-sexp-1(nil) | |
18372 | eval-last-sexp(nil) | |
18373 | call-interactively(eval-last-sexp) | |
18374 | ---------- Buffer: *Backtrace* ---------- | |
18375 | @end group | |
18376 | @end smallexample | |
18377 | ||
18378 | @noindent | |
18379 | (I have reformatted this example slightly; the debugger does not fold | |
18380 | long lines. As usual, you can quit the debugger by typing @kbd{q} in | |
18381 | the @file{*Backtrace*} buffer.) | |
18382 | ||
18383 | In practice, for a bug as simple as this, the `Lisp error' line will | |
18384 | tell you what you need to know to correct the definition. The | |
18385 | function @code{1=} is `void'. | |
18386 | ||
18387 | @ignore | |
18388 | @need 800 | |
18389 | In GNU Emacs 20 and before, you will see: | |
18390 | ||
18391 | @smallexample | |
18392 | Symbol's function definition is void:@: 1= | |
18393 | @end smallexample | |
18394 | ||
18395 | @noindent | |
18396 | which has the same meaning as the @file{*Backtrace*} buffer line in | |
18397 | version 21. | |
18398 | @end ignore | |
18399 | ||
18400 | However, suppose you are not quite certain what is going on? | |
18401 | You can read the complete backtrace. | |
18402 | ||
18403 | In this case, you need to run a recent GNU Emacs, which automatically | |
18404 | starts the debugger that puts you in the @file{*Backtrace*} buffer; or | |
18405 | else, you need to start the debugger manually as described below. | |
18406 | ||
18407 | Read the @file{*Backtrace*} buffer from the bottom up; it tells you | |
18408 | what Emacs did that led to the error. Emacs made an interactive call | |
18409 | to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation | |
18410 | of the @code{triangle-bugged} expression. Each line above tells you | |
18411 | what the Lisp interpreter evaluated next. | |
18412 | ||
18413 | @need 1250 | |
18414 | The third line from the top of the buffer is | |
18415 | ||
18416 | @smallexample | |
18417 | (setq number (1= number)) | |
18418 | @end smallexample | |
18419 | ||
18420 | @noindent | |
18421 | Emacs tried to evaluate this expression; in order to do so, it tried | |
18422 | to evaluate the inner expression shown on the second line from the | |
18423 | top: | |
18424 | ||
18425 | @smallexample | |
18426 | (1= number) | |
18427 | @end smallexample | |
18428 | ||
18429 | @need 1250 | |
18430 | @noindent | |
18431 | This is where the error occurred; as the top line says: | |
18432 | ||
18433 | @smallexample | |
18434 | Debugger entered--Lisp error: (void-function 1=) | |
18435 | @end smallexample | |
18436 | ||
18437 | @noindent | |
18438 | You can correct the mistake, re-evaluate the function definition, and | |
18439 | then run your test again. | |
18440 | ||
d6adf7e7 | 18441 | @node debug-on-entry |
8cda6f8f GM |
18442 | @section @code{debug-on-entry} |
18443 | @findex debug-on-entry | |
18444 | ||
18445 | A recent GNU Emacs starts the debugger automatically when your | |
18446 | function has an error. | |
18447 | ||
18448 | @ignore | |
18449 | GNU Emacs version 20 and before did not; it simply | |
18450 | presented you with an error message. You had to start the debugger | |
18451 | manually. | |
18452 | @end ignore | |
18453 | ||
18454 | Incidentally, you can start the debugger manually for all versions of | |
18455 | Emacs; the advantage is that the debugger runs even if you do not have | |
18456 | a bug in your code. Sometimes your code will be free of bugs! | |
18457 | ||
18458 | You can enter the debugger when you call the function by calling | |
18459 | @code{debug-on-entry}. | |
18460 | ||
18461 | @need 1250 | |
18462 | @noindent | |
18463 | Type: | |
18464 | ||
18465 | @smallexample | |
18466 | M-x debug-on-entry RET triangle-bugged RET | |
18467 | @end smallexample | |
18468 | ||
18469 | @need 1250 | |
18470 | @noindent | |
18471 | Now, evaluate the following: | |
18472 | ||
18473 | @smallexample | |
18474 | (triangle-bugged 5) | |
18475 | @end smallexample | |
18476 | ||
18477 | @noindent | |
18478 | All versions of Emacs will create a @file{*Backtrace*} buffer and tell | |
18479 | you that it is beginning to evaluate the @code{triangle-bugged} | |
18480 | function: | |
18481 | ||
18482 | @smallexample | |
18483 | @group | |
18484 | ---------- Buffer: *Backtrace* ---------- | |
18485 | Debugger entered--entering a function: | |
18486 | * triangle-bugged(5) | |
18487 | eval((triangle-bugged 5)) | |
18488 | @end group | |
18489 | @group | |
18490 | eval-last-sexp-1(nil) | |
18491 | eval-last-sexp(nil) | |
18492 | call-interactively(eval-last-sexp) | |
18493 | ---------- Buffer: *Backtrace* ---------- | |
18494 | @end group | |
18495 | @end smallexample | |
18496 | ||
18497 | In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate | |
18498 | the first expression in @code{triangle-bugged}; the buffer will look | |
18499 | like this: | |
18500 | ||
18501 | @smallexample | |
18502 | @group | |
18503 | ---------- Buffer: *Backtrace* ---------- | |
18504 | Debugger entered--beginning evaluation of function call form: | |
18505 | * (let ((total 0)) (while (> number 0) (setq total ...) | |
18506 | (setq number ...)) total) | |
18507 | * triangle-bugged(5) | |
18508 | eval((triangle-bugged 5)) | |
18509 | @end group | |
18510 | @group | |
18511 | eval-last-sexp-1(nil) | |
18512 | eval-last-sexp(nil) | |
18513 | call-interactively(eval-last-sexp) | |
18514 | ---------- Buffer: *Backtrace* ---------- | |
18515 | @end group | |
18516 | @end smallexample | |
18517 | ||
18518 | @noindent | |
18519 | Now, type @kbd{d} again, eight times, slowly. Each time you type | |
18520 | @kbd{d}, Emacs will evaluate another expression in the function | |
18521 | definition. | |
18522 | ||
18523 | @need 1750 | |
18524 | Eventually, the buffer will look like this: | |
18525 | ||
18526 | @smallexample | |
18527 | @group | |
18528 | ---------- Buffer: *Backtrace* ---------- | |
18529 | Debugger entered--beginning evaluation of function call form: | |
18530 | * (setq number (1= number)) | |
18531 | * (while (> number 0) (setq total (+ total number)) | |
18532 | (setq number (1= number))) | |
18533 | @group | |
18534 | @end group | |
18535 | * (let ((total 0)) (while (> number 0) (setq total ...) | |
18536 | (setq number ...)) total) | |
18537 | * triangle-bugged(5) | |
18538 | eval((triangle-bugged 5)) | |
18539 | @group | |
18540 | @end group | |
18541 | eval-last-sexp-1(nil) | |
18542 | eval-last-sexp(nil) | |
18543 | call-interactively(eval-last-sexp) | |
18544 | ---------- Buffer: *Backtrace* ---------- | |
18545 | @end group | |
18546 | @end smallexample | |
18547 | ||
18548 | @need 1500 | |
18549 | @noindent | |
18550 | Finally, after you type @kbd{d} two more times, Emacs will reach the | |
18551 | error, and the top two lines of the @file{*Backtrace*} buffer will look | |
18552 | like this: | |
18553 | ||
18554 | @smallexample | |
18555 | @group | |
18556 | ---------- Buffer: *Backtrace* ---------- | |
18557 | Debugger entered--Lisp error: (void-function 1=) | |
18558 | * (1= number) | |
18559 | @dots{} | |
18560 | ---------- Buffer: *Backtrace* ---------- | |
18561 | @end group | |
18562 | @end smallexample | |
18563 | ||
18564 | By typing @kbd{d}, you were able to step through the function. | |
18565 | ||
18566 | You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this | |
18567 | quits the trace, but does not cancel @code{debug-on-entry}. | |
18568 | ||
18569 | @findex cancel-debug-on-entry | |
18570 | To cancel the effect of @code{debug-on-entry}, call | |
18571 | @code{cancel-debug-on-entry} and the name of the function, like this: | |
18572 | ||
18573 | @smallexample | |
18574 | M-x cancel-debug-on-entry RET triangle-bugged RET | |
18575 | @end smallexample | |
18576 | ||
18577 | @noindent | |
18578 | (If you are reading this in Info, cancel @code{debug-on-entry} now.) | |
18579 | ||
d6adf7e7 | 18580 | @node debug-on-quit |
8cda6f8f GM |
18581 | @section @code{debug-on-quit} and @code{(debug)} |
18582 | ||
18583 | In addition to setting @code{debug-on-error} or calling @code{debug-on-entry}, | |
18584 | there are two other ways to start @code{debug}. | |
18585 | ||
18586 | @findex debug-on-quit | |
18587 | You can start @code{debug} whenever you type @kbd{C-g} | |
18588 | (@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to | |
18589 | @code{t}. This is useful for debugging infinite loops. | |
18590 | ||
18591 | @need 1500 | |
18592 | @cindex @code{(debug)} in code | |
18593 | Or, you can insert a line that says @code{(debug)} into your code | |
18594 | where you want the debugger to start, like this: | |
18595 | ||
18596 | @smallexample | |
18597 | @group | |
18598 | (defun triangle-bugged (number) | |
18599 | "Return sum of numbers 1 through NUMBER inclusive." | |
18600 | (let ((total 0)) | |
18601 | (while (> number 0) | |
18602 | (setq total (+ total number)) | |
18603 | (debug) ; @r{Start debugger.} | |
18604 | (setq number (1= number))) ; @r{Error here.} | |
18605 | total)) | |
18606 | @end group | |
18607 | @end smallexample | |
18608 | ||
18609 | The @code{debug} function is described in detail in @ref{Debugger, , | |
18610 | The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}. | |
18611 | ||
d6adf7e7 | 18612 | @node edebug |
8cda6f8f GM |
18613 | @section The @code{edebug} Source Level Debugger |
18614 | @cindex Source level debugger | |
18615 | @findex edebug | |
18616 | ||
18617 | Edebug is a source level debugger. Edebug normally displays the | |
18618 | source of the code you are debugging, with an arrow at the left that | |
18619 | shows which line you are currently executing. | |
18620 | ||
18621 | You can walk through the execution of a function, line by line, or run | |
18622 | quickly until reaching a @dfn{breakpoint} where execution stops. | |
18623 | ||
18624 | Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs | |
18625 | Lisp Reference Manual}. | |
18626 | ||
18627 | @need 1250 | |
18628 | Here is a bugged function definition for @code{triangle-recursively}. | |
18629 | @xref{Recursive triangle function, , Recursion in place of a counter}, | |
18630 | for a review of it. | |
18631 | ||
18632 | @smallexample | |
18633 | @group | |
18634 | (defun triangle-recursively-bugged (number) | |
18635 | "Return sum of numbers 1 through NUMBER inclusive. | |
18636 | Uses recursion." | |
18637 | (if (= number 1) | |
18638 | 1 | |
18639 | (+ number | |
18640 | (triangle-recursively-bugged | |
18641 | (1= number))))) ; @r{Error here.} | |
18642 | @end group | |
18643 | @end smallexample | |
18644 | ||
18645 | @noindent | |
18646 | Normally, you would install this definition by positioning your cursor | |
18647 | after the function's closing parenthesis and typing @kbd{C-x C-e} | |
18648 | (@code{eval-last-sexp}) or else by positioning your cursor within the | |
18649 | definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default, | |
18650 | the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp | |
a1539cd7 | 18651 | Interaction mode.) |
8cda6f8f GM |
18652 | |
18653 | @need 1500 | |
18654 | However, to prepare this function definition for Edebug, you must | |
18655 | first @dfn{instrument} the code using a different command. You can do | |
18656 | this by positioning your cursor within or just after the definition | |
18657 | and typing | |
18658 | ||
18659 | @smallexample | |
18660 | M-x edebug-defun RET | |
18661 | @end smallexample | |
18662 | ||
18663 | @noindent | |
18664 | This will cause Emacs to load Edebug automatically if it is not | |
18665 | already loaded, and properly instrument the function. | |
18666 | ||
18667 | After instrumenting the function, place your cursor after the | |
18668 | following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}): | |
18669 | ||
18670 | @smallexample | |
18671 | (triangle-recursively-bugged 3) | |
18672 | @end smallexample | |
18673 | ||
18674 | @noindent | |
18675 | You will be jumped back to the source for | |
18676 | @code{triangle-recursively-bugged} and the cursor positioned at the | |
18677 | beginning of the @code{if} line of the function. Also, you will see | |
18678 | an arrowhead at the left hand side of that line. The arrowhead marks | |
18679 | the line where the function is executing. (In the following examples, | |
18680 | we show the arrowhead with @samp{=>}; in a windowing system, you may | |
18681 | see the arrowhead as a solid triangle in the window `fringe'.) | |
18682 | ||
18683 | @smallexample | |
18684 | =>@point{}(if (= number 1) | |
18685 | @end smallexample | |
18686 | ||
18687 | @noindent | |
18688 | @iftex | |
18689 | In the example, the location of point is displayed with a star, | |
18690 | @samp{@point{}} (in Info, it is displayed as @samp{-!-}). | |
18691 | @end iftex | |
18692 | @ifnottex | |
18693 | In the example, the location of point is displayed as @samp{@point{}} | |
18694 | (in a printed book, it is displayed with a five pointed star). | |
18695 | @end ifnottex | |
18696 | ||
18697 | If you now press @key{SPC}, point will move to the next expression to | |
18698 | be executed; the line will look like this: | |
18699 | ||
18700 | @smallexample | |
18701 | =>(if @point{}(= number 1) | |
18702 | @end smallexample | |
18703 | ||
18704 | @noindent | |
18705 | As you continue to press @key{SPC}, point will move from expression to | |
18706 | expression. At the same time, whenever an expression returns a value, | |
18707 | that value will be displayed in the echo area. For example, after you | |
18708 | move point past @code{number}, you will see the following: | |
18709 | ||
18710 | @smallexample | |
18711 | Result: 3 (#o3, #x3, ?\C-c) | |
18712 | @end smallexample | |
18713 | ||
18714 | @noindent | |
18715 | This means the value of @code{number} is 3, which is octal three, | |
18716 | hexadecimal three, and @sc{ascii} `control-c' (the third letter of the | |
18717 | alphabet, in case you need to know this information). | |
18718 | ||
18719 | You can continue moving through the code until you reach the line with | |
18720 | the error. Before evaluation, that line looks like this: | |
18721 | ||
18722 | @smallexample | |
18723 | => @point{}(1= number))))) ; @r{Error here.} | |
18724 | @end smallexample | |
18725 | ||
18726 | @need 1250 | |
18727 | @noindent | |
18728 | When you press @key{SPC} once again, you will produce an error message | |
18729 | that says: | |
18730 | ||
18731 | @smallexample | |
18732 | Symbol's function definition is void:@: 1= | |
18733 | @end smallexample | |
18734 | ||
18735 | @noindent | |
18736 | This is the bug. | |
18737 | ||
18738 | Press @kbd{q} to quit Edebug. | |
18739 | ||
18740 | To remove instrumentation from a function definition, simply | |
18741 | re-evaluate it with a command that does not instrument it. | |
18742 | For example, you could place your cursor after the definition's | |
18743 | closing parenthesis and type @kbd{C-x C-e}. | |
18744 | ||
18745 | Edebug does a great deal more than walk with you through a function. | |
18746 | You can set it so it races through on its own, stopping only at an | |
18747 | error or at specified stopping points; you can cause it to display the | |
18748 | changing values of various expressions; you can find out how many | |
18749 | times a function is called, and more. | |
18750 | ||
18751 | Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs | |
18752 | Lisp Reference Manual}. | |
18753 | ||
18754 | @need 1500 | |
d6adf7e7 | 18755 | @node Debugging Exercises |
8cda6f8f GM |
18756 | @section Debugging Exercises |
18757 | ||
18758 | @itemize @bullet | |
18759 | @item | |
ea4f7750 | 18760 | Install the @code{@value{COUNT-WORDS}} function and then cause it to |
8cda6f8f GM |
18761 | enter the built-in debugger when you call it. Run the command on a |
18762 | region containing two words. You will need to press @kbd{d} a | |
18763 | remarkable number of times. On your system, is a `hook' called after | |
18764 | the command finishes? (For information on hooks, see @ref{Command | |
18765 | Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference | |
18766 | Manual}.) | |
18767 | ||
18768 | @item | |
ea4f7750 | 18769 | Copy @code{@value{COUNT-WORDS}} into the @file{*scratch*} buffer, |
8cda6f8f GM |
18770 | instrument the function for Edebug, and walk through its execution. |
18771 | The function does not need to have a bug, although you can introduce | |
18772 | one if you wish. If the function lacks a bug, the walk-through | |
18773 | completes without problems. | |
18774 | ||
18775 | @item | |
18776 | While running Edebug, type @kbd{?} to see a list of all the Edebug commands. | |
1df7defd | 18777 | (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e., |
8cda6f8f GM |
18778 | @kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix |
18779 | for commands made outside of the Edebug debugging buffer.) | |
18780 | ||
18781 | @item | |
18782 | In the Edebug debugging buffer, use the @kbd{p} | |
18783 | (@code{edebug-bounce-point}) command to see where in the region the | |
ea4f7750 | 18784 | @code{@value{COUNT-WORDS}} is working. |
8cda6f8f GM |
18785 | |
18786 | @item | |
18787 | Move point to some spot further down the function and then type the | |
18788 | @kbd{h} (@code{edebug-goto-here}) command to jump to that location. | |
18789 | ||
18790 | @item | |
18791 | Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to | |
18792 | walk through the function on its own; use an upper case @kbd{T} for | |
18793 | @code{edebug-Trace-fast-mode}. | |
18794 | ||
18795 | @item | |
18796 | Set a breakpoint, then run Edebug in Trace mode until it reaches the | |
18797 | stopping point. | |
18798 | @end itemize | |
18799 | ||
d6adf7e7 | 18800 | @node Conclusion |
8cda6f8f GM |
18801 | @chapter Conclusion |
18802 | ||
18803 | We have now reached the end of this Introduction. You have now | |
18804 | learned enough about programming in Emacs Lisp to set values, to write | |
18805 | simple @file{.emacs} files for yourself and your friends, and write | |
18806 | simple customizations and extensions to Emacs. | |
18807 | ||
18808 | This is a place to stop. Or, if you wish, you can now go onward, and | |
18809 | teach yourself. | |
18810 | ||
18811 | You have learned some of the basic nuts and bolts of programming. But | |
18812 | only some. There are a great many more brackets and hinges that are | |
18813 | easy to use that we have not touched. | |
18814 | ||
18815 | A path you can follow right now lies among the sources to GNU Emacs | |
18816 | and in | |
18817 | @ifnotinfo | |
18818 | @cite{The GNU Emacs Lisp Reference Manual}. | |
18819 | @end ifnotinfo | |
18820 | @ifinfo | |
18821 | @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU | |
18822 | Emacs Lisp Reference Manual}. | |
18823 | @end ifinfo | |
18824 | ||
18825 | The Emacs Lisp sources are an adventure. When you read the sources and | |
18826 | come across a function or expression that is unfamiliar, you need to | |
18827 | figure out or find out what it does. | |
18828 | ||
18829 | Go to the Reference Manual. It is a thorough, complete, and fairly | |
18830 | easy-to-read description of Emacs Lisp. It is written not only for | |
18831 | experts, but for people who know what you know. (The @cite{Reference | |
18832 | Manual} comes with the standard GNU Emacs distribution. Like this | |
18833 | introduction, it comes as a Texinfo source file, so you can read it | |
18834 | on-line and as a typeset, printed book.) | |
18835 | ||
18836 | Go to the other on-line help that is part of GNU Emacs: the on-line | |
88c26f5c | 18837 | documentation for all functions and variables, and @code{find-tag}, |
8cda6f8f GM |
18838 | the program that takes you to sources. |
18839 | ||
18840 | Here is an example of how I explore the sources. Because of its name, | |
18841 | @file{simple.el} is the file I looked at first, a long time ago. As | |
18842 | it happens some of the functions in @file{simple.el} are complicated, | |
18843 | or at least look complicated at first sight. The @code{open-line} | |
18844 | function, for example, looks complicated. | |
18845 | ||
18846 | You may want to walk through this function slowly, as we did with the | |
18847 | @code{forward-sentence} function. (@xref{forward-sentence, The | |
18848 | @code{forward-sentence} function}.) Or you may want to skip that | |
18849 | function and look at another, such as @code{split-line}. You don't | |
18850 | need to read all the functions. According to | |
18851 | @code{count-words-in-defun}, the @code{split-line} function contains | |
18852 | 102 words and symbols. | |
18853 | ||
18854 | Even though it is short, @code{split-line} contains expressions | |
18855 | we have not studied: @code{skip-chars-forward}, @code{indent-to}, | |
18856 | @code{current-column} and @code{insert-and-inherit}. | |
18857 | ||
18858 | Consider the @code{skip-chars-forward} function. (It is part of the | |
18859 | function definition for @code{back-to-indentation}, which is shown in | |
18860 | @ref{Review, , Review}.) | |
18861 | ||
18862 | In GNU Emacs, you can find out more about @code{skip-chars-forward} by | |
18863 | typing @kbd{C-h f} (@code{describe-function}) and the name of the | |
18864 | function. This gives you the function documentation. | |
18865 | ||
18866 | You may be able to guess what is done by a well named function such as | |
18867 | @code{indent-to}; or you can look it up, too. Incidentally, the | |
18868 | @code{describe-function} function itself is in @file{help.el}; it is | |
18869 | one of those long, but decipherable functions. You can look up | |
18870 | @code{describe-function} using the @kbd{C-h f} command! | |
18871 | ||
18872 | In this instance, since the code is Lisp, the @file{*Help*} buffer | |
18873 | contains the name of the library containing the function's source. | |
18874 | You can put point over the name of the library and press the RET key, | |
18875 | which in this situation is bound to @code{help-follow}, and be taken | |
18876 | directly to the source, in the same way as @kbd{M-.} | |
18877 | (@code{find-tag}). | |
18878 | ||
18879 | The definition for @code{describe-function} illustrates how to | |
18880 | customize the @code{interactive} expression without using the standard | |
18881 | character codes; and it shows how to create a temporary buffer. | |
18882 | ||
18883 | (The @code{indent-to} function is written in C rather than Emacs Lisp; | |
18884 | it is a `built-in' function. @code{help-follow} takes you to its | |
18885 | source as does @code{find-tag}, when properly set up.) | |
18886 | ||
18887 | You can look at a function's source using @code{find-tag}, which is | |
18888 | bound to @kbd{M-.} Finally, you can find out what the Reference | |
18889 | Manual has to say by visiting the manual in Info, and typing @kbd{i} | |
18890 | (@code{Info-index}) and the name of the function, or by looking up the | |
18891 | function in the index to a printed copy of the manual. | |
18892 | ||
18893 | Similarly, you can find out what is meant by | |
18894 | @code{insert-and-inherit}. | |
18895 | ||
18896 | Other interesting source files include @file{paragraphs.el}, | |
18897 | @file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el} | |
18898 | file includes short, easily understood functions as well as longer | |
18899 | ones. The @file{loaddefs.el} file contains the many standard | |
18900 | autoloads and many keymaps. I have never looked at it all; only at | |
18901 | parts. @file{loadup.el} is the file that loads the standard parts of | |
18902 | Emacs; it tells you a great deal about how Emacs is built. | |
18903 | (@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp | |
18904 | Reference Manual}, for more about building.) | |
18905 | ||
18906 | As I said, you have learned some nuts and bolts; however, and very | |
18907 | importantly, we have hardly touched major aspects of programming; I | |
18908 | have said nothing about how to sort information, except to use the | |
18909 | predefined @code{sort} function; I have said nothing about how to store | |
18910 | information, except to use variables and lists; I have said nothing | |
18911 | about how to write programs that write programs. These are topics for | |
18912 | another, and different kind of book, a different kind of learning. | |
18913 | ||
18914 | What you have done is learn enough for much practical work with GNU | |
18915 | Emacs. What you have done is get started. This is the end of a | |
18916 | beginning. | |
18917 | ||
18918 | @c ================ Appendix ================ | |
18919 | ||
d6adf7e7 | 18920 | @node the-the |
8cda6f8f GM |
18921 | @appendix The @code{the-the} Function |
18922 | @findex the-the | |
18923 | @cindex Duplicated words function | |
18924 | @cindex Words, duplicated | |
18925 | ||
18926 | Sometimes when you you write text, you duplicate words---as with ``you | |
18927 | you'' near the beginning of this sentence. I find that most | |
18928 | frequently, I duplicate ``the''; hence, I call the function for | |
18929 | detecting duplicated words, @code{the-the}. | |
18930 | ||
18931 | @need 1250 | |
18932 | As a first step, you could use the following regular expression to | |
18933 | search for duplicates: | |
18934 | ||
18935 | @smallexample | |
18936 | \\(\\w+[ \t\n]+\\)\\1 | |
18937 | @end smallexample | |
18938 | ||
18939 | @noindent | |
18940 | This regexp matches one or more word-constituent characters followed | |
18941 | by one or more spaces, tabs, or newlines. However, it does not detect | |
18942 | duplicated words on different lines, since the ending of the first | |
18943 | word, the end of the line, is different from the ending of the second | |
18944 | word, a space. (For more information about regular expressions, see | |
18945 | @ref{Regexp Search, , Regular Expression Searches}, as well as | |
18946 | @ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs | |
18947 | Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp, | |
18948 | The GNU Emacs Lisp Reference Manual}.) | |
18949 | ||
18950 | You might try searching just for duplicated word-constituent | |
18951 | characters but that does not work since the pattern detects doubles | |
18952 | such as the two occurrences of `th' in `with the'. | |
18953 | ||
18954 | Another possible regexp searches for word-constituent characters | |
18955 | followed by non-word-constituent characters, reduplicated. Here, | |
18956 | @w{@samp{\\w+}} matches one or more word-constituent characters and | |
18957 | @w{@samp{\\W*}} matches zero or more non-word-constituent characters. | |
18958 | ||
18959 | @smallexample | |
18960 | \\(\\(\\w+\\)\\W*\\)\\1 | |
18961 | @end smallexample | |
18962 | ||
18963 | @noindent | |
18964 | Again, not useful. | |
18965 | ||
18966 | Here is the pattern that I use. It is not perfect, but good enough. | |
18967 | @w{@samp{\\b}} matches the empty string, provided it is at the beginning | |
18968 | or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of | |
18969 | any characters that are @emph{not} an @@-sign, space, newline, or tab. | |
18970 | ||
18971 | @smallexample | |
18972 | \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b | |
18973 | @end smallexample | |
18974 | ||
18975 | One can write more complicated expressions, but I found that this | |
18976 | expression is good enough, so I use it. | |
18977 | ||
18978 | Here is the @code{the-the} function, as I include it in my | |
18979 | @file{.emacs} file, along with a handy global key binding: | |
18980 | ||
18981 | @smallexample | |
18982 | @group | |
18983 | (defun the-the () | |
18984 | "Search forward for for a duplicated word." | |
18985 | (interactive) | |
18986 | (message "Searching for for duplicated words ...") | |
18987 | (push-mark) | |
18988 | @end group | |
18989 | @group | |
18990 | ;; This regexp is not perfect | |
18991 | ;; but is fairly good over all: | |
18992 | (if (re-search-forward | |
18993 | "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move) | |
18994 | (message "Found duplicated word.") | |
18995 | (message "End of buffer"))) | |
18996 | @end group | |
18997 | ||
18998 | @group | |
18999 | ;; Bind `the-the' to C-c \ | |
19000 | (global-set-key "\C-c\\" 'the-the) | |
19001 | @end group | |
19002 | @end smallexample | |
19003 | ||
19004 | @sp 1 | |
19005 | Here is test text: | |
19006 | ||
19007 | @smallexample | |
19008 | @group | |
19009 | one two two three four five | |
19010 | five six seven | |
19011 | @end group | |
19012 | @end smallexample | |
19013 | ||
19014 | You can substitute the other regular expressions shown above in the | |
19015 | function definition and try each of them on this list. | |
19016 | ||
d6adf7e7 | 19017 | @node Kill Ring |
8cda6f8f GM |
19018 | @appendix Handling the Kill Ring |
19019 | @cindex Kill ring handling | |
19020 | @cindex Handling the kill ring | |
19021 | @cindex Ring, making a list like a | |
19022 | ||
19023 | The kill ring is a list that is transformed into a ring by the | |
19024 | workings of the @code{current-kill} function. The @code{yank} and | |
19025 | @code{yank-pop} commands use the @code{current-kill} function. | |
19026 | ||
19027 | This appendix describes the @code{current-kill} function as well as | |
19028 | both the @code{yank} and the @code{yank-pop} commands, but first, | |
19029 | consider the workings of the kill ring. | |
19030 | ||
19031 | @menu | |
19032 | * What the Kill Ring Does:: | |
19033 | * current-kill:: | |
19034 | * yank:: Paste a copy of a clipped element. | |
19035 | * yank-pop:: Insert element pointed to. | |
19036 | * ring file:: | |
19037 | @end menu | |
19038 | ||
8cda6f8f | 19039 | @ifnottex |
d6adf7e7 | 19040 | @node What the Kill Ring Does |
8cda6f8f GM |
19041 | @unnumberedsec What the Kill Ring Does |
19042 | @end ifnottex | |
19043 | ||
19044 | @need 1250 | |
19045 | The kill ring has a default maximum length of sixty items; this number | |
19046 | is too large for an explanation. Instead, set it to four. Please | |
19047 | evaluate the following: | |
19048 | ||
19049 | @smallexample | |
19050 | @group | |
19051 | (setq old-kill-ring-max kill-ring-max) | |
19052 | (setq kill-ring-max 4) | |
19053 | @end group | |
19054 | @end smallexample | |
19055 | ||
19056 | @noindent | |
19057 | Then, please copy each line of the following indented example into the | |
19058 | kill ring. You may kill each line with @kbd{C-k} or mark it and copy | |
19059 | it with @kbd{M-w}. | |
19060 | ||
19061 | @noindent | |
19062 | (In a read-only buffer, such as the @file{*info*} buffer, the kill | |
19063 | command, @kbd{C-k} (@code{kill-line}), will not remove the text, | |
19064 | merely copy it to the kill ring. However, your machine may beep at | |
19065 | you. Alternatively, for silence, you may copy the region of each line | |
19066 | with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark | |
19067 | each line for this command to succeed, but it does not matter at which | |
19068 | end you put point or mark.) | |
19069 | ||
19070 | @need 1250 | |
19071 | @noindent | |
19072 | Please invoke the calls in order, so that five elements attempt to | |
19073 | fill the kill ring: | |
19074 | ||
19075 | @smallexample | |
19076 | @group | |
19077 | first some text | |
19078 | second piece of text | |
19079 | third line | |
19080 | fourth line of text | |
19081 | fifth bit of text | |
19082 | @end group | |
19083 | @end smallexample | |
19084 | ||
19085 | @need 1250 | |
19086 | @noindent | |
19087 | Then find the value of @code{kill-ring} by evaluating | |
19088 | ||
19089 | @smallexample | |
19090 | kill-ring | |
19091 | @end smallexample | |
19092 | ||
19093 | @need 800 | |
19094 | @noindent | |
19095 | It is: | |
19096 | ||
19097 | @smallexample | |
19098 | @group | |
19099 | ("fifth bit of text" "fourth line of text" | |
19100 | "third line" "second piece of text") | |
19101 | @end group | |
19102 | @end smallexample | |
19103 | ||
19104 | @noindent | |
19105 | The first element, @samp{first some text}, was dropped. | |
19106 | ||
19107 | @need 1250 | |
19108 | To return to the old value for the length of the kill ring, evaluate: | |
19109 | ||
19110 | @smallexample | |
19111 | (setq kill-ring-max old-kill-ring-max) | |
19112 | @end smallexample | |
19113 | ||
d6adf7e7 | 19114 | @node current-kill |
8cda6f8f GM |
19115 | @appendixsec The @code{current-kill} Function |
19116 | @findex current-kill | |
19117 | ||
19118 | The @code{current-kill} function changes the element in the kill ring | |
19119 | to which @code{kill-ring-yank-pointer} points. (Also, the | |
19120 | @code{kill-new} function sets @code{kill-ring-yank-pointer} to point | |
867d4bb3 | 19121 | to the latest element of the kill ring. The @code{kill-new} |
8cda6f8f GM |
19122 | function is used directly or indirectly by @code{kill-append}, |
19123 | @code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line}, | |
19124 | and @code{kill-region}.) | |
19125 | ||
19126 | @menu | |
19127 | * Code for current-kill:: | |
19128 | * Understanding current-kill:: | |
19129 | @end menu | |
19130 | ||
8cda6f8f | 19131 | @ifnottex |
d6adf7e7 | 19132 | @node Code for current-kill |
8cda6f8f GM |
19133 | @unnumberedsubsec The code for @code{current-kill} |
19134 | @end ifnottex | |
19135 | ||
19136 | ||
19137 | @need 1500 | |
19138 | The @code{current-kill} function is used by @code{yank} and by | |
19139 | @code{yank-pop}. Here is the code for @code{current-kill}: | |
19140 | ||
19141 | @smallexample | |
19142 | @group | |
19143 | (defun current-kill (n &optional do-not-move) | |
19144 | "Rotate the yanking point by N places, and then return that kill. | |
19145 | If N is zero, `interprogram-paste-function' is set, and calling it | |
19146 | returns a string, then that string is added to the front of the | |
19147 | kill ring and returned as the latest kill. | |
19148 | @end group | |
19149 | @group | |
19150 | If optional arg DO-NOT-MOVE is non-nil, then don't actually move the | |
19151 | yanking point; just return the Nth kill forward." | |
19152 | (let ((interprogram-paste (and (= n 0) | |
19153 | interprogram-paste-function | |
19154 | (funcall interprogram-paste-function)))) | |
19155 | @end group | |
19156 | @group | |
19157 | (if interprogram-paste | |
19158 | (progn | |
19159 | ;; Disable the interprogram cut function when we add the new | |
19160 | ;; text to the kill ring, so Emacs doesn't try to own the | |
19161 | ;; selection, with identical text. | |
19162 | (let ((interprogram-cut-function nil)) | |
19163 | (kill-new interprogram-paste)) | |
19164 | interprogram-paste) | |
19165 | @end group | |
19166 | @group | |
19167 | (or kill-ring (error "Kill ring is empty")) | |
19168 | (let ((ARGth-kill-element | |
19169 | (nthcdr (mod (- n (length kill-ring-yank-pointer)) | |
19170 | (length kill-ring)) | |
19171 | kill-ring))) | |
19172 | (or do-not-move | |
19173 | (setq kill-ring-yank-pointer ARGth-kill-element)) | |
19174 | (car ARGth-kill-element))))) | |
19175 | @end group | |
19176 | @end smallexample | |
19177 | ||
19178 | Remember also that the @code{kill-new} function sets | |
867d4bb3 | 19179 | @code{kill-ring-yank-pointer} to the latest element of the kill |
8cda6f8f GM |
19180 | ring, which means that all the functions that call it set the value |
19181 | indirectly: @code{kill-append}, @code{copy-region-as-kill}, | |
19182 | @code{kill-ring-save}, @code{kill-line}, and @code{kill-region}. | |
19183 | ||
19184 | @need 1500 | |
19185 | Here is the line in @code{kill-new}, which is explained in | |
19186 | @ref{kill-new function, , The @code{kill-new} function}. | |
19187 | ||
19188 | @smallexample | |
19189 | (setq kill-ring-yank-pointer kill-ring) | |
19190 | @end smallexample | |
19191 | ||
8cda6f8f | 19192 | @ifnottex |
d6adf7e7 | 19193 | @node Understanding current-kill |
8cda6f8f GM |
19194 | @unnumberedsubsec @code{current-kill} in Outline |
19195 | @end ifnottex | |
19196 | ||
19197 | The @code{current-kill} function looks complex, but as usual, it can | |
19198 | be understood by taking it apart piece by piece. First look at it in | |
19199 | skeletal form: | |
19200 | ||
19201 | @smallexample | |
19202 | @group | |
19203 | (defun current-kill (n &optional do-not-move) | |
19204 | "Rotate the yanking point by N places, and then return that kill." | |
19205 | (let @var{varlist} | |
19206 | @var{body}@dots{}) | |
19207 | @end group | |
19208 | @end smallexample | |
19209 | ||
19210 | This function takes two arguments, one of which is optional. It has a | |
19211 | documentation string. It is @emph{not} interactive. | |
19212 | ||
19213 | @menu | |
19214 | * Body of current-kill:: | |
19215 | * Digression concerning error:: How to mislead humans, but not computers. | |
19216 | * Determining the Element:: | |
19217 | @end menu | |
19218 | ||
8cda6f8f | 19219 | @ifnottex |
d6adf7e7 | 19220 | @node Body of current-kill |
8cda6f8f GM |
19221 | @unnumberedsubsubsec The Body of @code{current-kill} |
19222 | @end ifnottex | |
19223 | ||
19224 | The body of the function definition is a @code{let} expression, which | |
19225 | itself has a body as well as a @var{varlist}. | |
19226 | ||
19227 | The @code{let} expression declares a variable that will be only usable | |
19228 | within the bounds of this function. This variable is called | |
19229 | @code{interprogram-paste} and is for copying to another program. It | |
19230 | is not for copying within this instance of GNU Emacs. Most window | |
19231 | systems provide a facility for interprogram pasting. Sadly, that | |
19232 | facility usually provides only for the last element. Most windowing | |
19233 | systems have not adopted a ring of many possibilities, even though | |
19234 | Emacs has provided it for decades. | |
19235 | ||
19236 | The @code{if} expression has two parts, one if there exists | |
19237 | @code{interprogram-paste} and one if not. | |
19238 | ||
19239 | @need 2000 | |
19240 | Let us consider the `if not' or else-part of the @code{current-kill} | |
867d4bb3 | 19241 | function. (The then-part uses the @code{kill-new} function, which |
8cda6f8f GM |
19242 | we have already described. @xref{kill-new function, , The |
19243 | @code{kill-new} function}.) | |
19244 | ||
19245 | @smallexample | |
19246 | @group | |
19247 | (or kill-ring (error "Kill ring is empty")) | |
19248 | (let ((ARGth-kill-element | |
19249 | (nthcdr (mod (- n (length kill-ring-yank-pointer)) | |
19250 | (length kill-ring)) | |
19251 | kill-ring))) | |
19252 | (or do-not-move | |
19253 | (setq kill-ring-yank-pointer ARGth-kill-element)) | |
19254 | (car ARGth-kill-element)) | |
19255 | @end group | |
19256 | @end smallexample | |
19257 | ||
19258 | @noindent | |
19259 | The code first checks whether the kill ring has content; otherwise it | |
19260 | signals an error. | |
19261 | ||
19262 | @need 1000 | |
19263 | Note that the @code{or} expression is very similar to testing length | |
19264 | with an @code{if}: | |
19265 | ||
19266 | @findex zerop | |
19267 | @findex error | |
19268 | @smallexample | |
19269 | @group | |
19270 | (if (zerop (length kill-ring)) ; @r{if-part} | |
19271 | (error "Kill ring is empty")) ; @r{then-part} | |
19272 | ;; No else-part | |
19273 | @end group | |
19274 | @end smallexample | |
19275 | ||
19276 | @noindent | |
19277 | If there is not anything in the kill ring, its length must be zero and | |
19278 | an error message sent to the user: @samp{Kill ring is empty}. The | |
19279 | @code{current-kill} function uses an @code{or} expression which is | |
19280 | simpler. But an @code{if} expression reminds us what goes on. | |
19281 | ||
19282 | This @code{if} expression uses the function @code{zerop} which returns | |
19283 | true if the value it is testing is zero. When @code{zerop} tests | |
19284 | true, the then-part of the @code{if} is evaluated. The then-part is a | |
19285 | list starting with the function @code{error}, which is a function that | |
19286 | is similar to the @code{message} function | |
19287 | (@pxref{message, , The @code{message} Function}) in that | |
19288 | it prints a one-line message in the echo area. However, in addition | |
19289 | to printing a message, @code{error} also stops evaluation of the | |
19290 | function within which it is embedded. This means that the rest of the | |
19291 | function will not be evaluated if the length of the kill ring is zero. | |
19292 | ||
19293 | Then the @code{current-kill} function selects the element to return. | |
19294 | The selection depends on the number of places that @code{current-kill} | |
19295 | rotates and on where @code{kill-ring-yank-pointer} points. | |
19296 | ||
19297 | Next, either the optional @code{do-not-move} argument is true or the | |
19298 | current value of @code{kill-ring-yank-pointer} is set to point to the | |
19299 | list. Finally, another expression returns the first element of the | |
19300 | list even if the @code{do-not-move} argument is true. | |
19301 | ||
8cda6f8f | 19302 | @ifnottex |
d6adf7e7 | 19303 | @node Digression concerning error |
8cda6f8f GM |
19304 | @unnumberedsubsubsec Digression about the word `error' |
19305 | @end ifnottex | |
19306 | ||
19307 | In my opinion, it is slightly misleading, at least to humans, to use | |
19308 | the term `error' as the name of the @code{error} function. A better | |
19309 | term would be `cancel'. Strictly speaking, of course, you cannot | |
19310 | point to, much less rotate a pointer to a list that has no length, so | |
19311 | from the point of view of the computer, the word `error' is correct. | |
19312 | But a human expects to attempt this sort of thing, if only to find out | |
19313 | whether the kill ring is full or empty. This is an act of | |
19314 | exploration. | |
19315 | ||
19316 | From the human point of view, the act of exploration and discovery is | |
09e80d9f | 19317 | not necessarily an error, and therefore should not be labeled as one, |
8cda6f8f GM |
19318 | even in the bowels of a computer. As it is, the code in Emacs implies |
19319 | that a human who is acting virtuously, by exploring his or her | |
19320 | environment, is making an error. This is bad. Even though the computer | |
19321 | takes the same steps as it does when there is an `error', a term such as | |
19322 | `cancel' would have a clearer connotation. | |
19323 | ||
8cda6f8f | 19324 | @ifnottex |
d6adf7e7 | 19325 | @node Determining the Element |
8cda6f8f GM |
19326 | @unnumberedsubsubsec Determining the Element |
19327 | @end ifnottex | |
19328 | ||
19329 | Among other actions, the else-part of the @code{if} expression sets | |
19330 | the value of @code{kill-ring-yank-pointer} to | |
19331 | @code{ARGth-kill-element} when the kill ring has something in it and | |
19332 | the value of @code{do-not-move} is @code{nil}. | |
19333 | ||
19334 | @need 800 | |
19335 | The code looks like this: | |
19336 | ||
19337 | @smallexample | |
19338 | @group | |
19339 | (nthcdr (mod (- n (length kill-ring-yank-pointer)) | |
19340 | (length kill-ring)) | |
19341 | kill-ring))) | |
19342 | @end group | |
19343 | @end smallexample | |
19344 | ||
19345 | This needs some examination. Unless it is not supposed to move the | |
19346 | pointer, the @code{current-kill} function changes where | |
19347 | @code{kill-ring-yank-pointer} points. | |
19348 | That is what the | |
19349 | @w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}} | |
19350 | expression does. Also, clearly, @code{ARGth-kill-element} is being | |
19351 | set to be equal to some @sc{cdr} of the kill ring, using the | |
19352 | @code{nthcdr} function that is described in an earlier section. | |
19353 | (@xref{copy-region-as-kill}.) How does it do this? | |
19354 | ||
19355 | As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function | |
19356 | works by repeatedly taking the @sc{cdr} of a list---it takes the | |
19357 | @sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{} | |
19358 | ||
19359 | @need 800 | |
19360 | The two following expressions produce the same result: | |
19361 | ||
19362 | @smallexample | |
19363 | @group | |
19364 | (setq kill-ring-yank-pointer (cdr kill-ring)) | |
19365 | ||
19366 | (setq kill-ring-yank-pointer (nthcdr 1 kill-ring)) | |
19367 | @end group | |
19368 | @end smallexample | |
19369 | ||
19370 | However, the @code{nthcdr} expression is more complicated. It uses | |
19371 | the @code{mod} function to determine which @sc{cdr} to select. | |
19372 | ||
19373 | (You will remember to look at inner functions first; indeed, we will | |
19374 | have to go inside the @code{mod}.) | |
19375 | ||
19376 | The @code{mod} function returns the value of its first argument modulo | |
19377 | the second; that is to say, it returns the remainder after dividing | |
19378 | the first argument by the second. The value returned has the same | |
19379 | sign as the second argument. | |
19380 | ||
19381 | @need 800 | |
19382 | Thus, | |
19383 | ||
19384 | @smallexample | |
19385 | @group | |
19386 | (mod 12 4) | |
19387 | @result{} 0 ;; @r{because there is no remainder} | |
19388 | (mod 13 4) | |
19389 | @result{} 1 | |
19390 | @end group | |
19391 | @end smallexample | |
19392 | ||
19393 | @need 1250 | |
19394 | In this case, the first argument is often smaller than the second. | |
19395 | That is fine. | |
19396 | ||
19397 | @smallexample | |
19398 | @group | |
19399 | (mod 0 4) | |
19400 | @result{} 0 | |
19401 | (mod 1 4) | |
19402 | @result{} 1 | |
19403 | @end group | |
19404 | @end smallexample | |
19405 | ||
19406 | We can guess what the @code{-} function does. It is like @code{+} but | |
19407 | subtracts instead of adds; the @code{-} function subtracts its second | |
19408 | argument from its first. Also, we already know what the @code{length} | |
19409 | function does (@pxref{length}). It returns the length of a list. | |
19410 | ||
19411 | And @code{n} is the name of the required argument to the | |
19412 | @code{current-kill} function. | |
19413 | ||
19414 | @need 1250 | |
19415 | So when the first argument to @code{nthcdr} is zero, the @code{nthcdr} | |
19416 | expression returns the whole list, as you can see by evaluating the | |
19417 | following: | |
19418 | ||
19419 | @smallexample | |
19420 | @group | |
19421 | ;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four} | |
19422 | ;; @r{and} (mod (- 0 4) 4) @result{} 0 | |
19423 | (nthcdr (mod (- 0 4) 4) | |
19424 | '("fourth line of text" | |
19425 | "third line" | |
19426 | "second piece of text" | |
19427 | "first some text")) | |
19428 | @end group | |
19429 | @end smallexample | |
19430 | ||
19431 | @need 1250 | |
19432 | When the first argument to the @code{current-kill} function is one, | |
19433 | the @code{nthcdr} expression returns the list without its first | |
19434 | element. | |
19435 | ||
19436 | @smallexample | |
19437 | @group | |
19438 | (nthcdr (mod (- 1 4) 4) | |
19439 | '("fourth line of text" | |
19440 | "third line" | |
19441 | "second piece of text" | |
19442 | "first some text")) | |
19443 | @end group | |
19444 | @end smallexample | |
19445 | ||
19446 | @cindex @samp{global variable} defined | |
19447 | @cindex @samp{variable, global}, defined | |
19448 | Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer} | |
19449 | are @dfn{global variables}. That means that any expression in Emacs | |
19450 | Lisp can access them. They are not like the local variables set by | |
19451 | @code{let} or like the symbols in an argument list. | |
19452 | Local variables can only be accessed | |
19453 | within the @code{let} that defines them or the function that specifies | |
19454 | them in an argument list (and within expressions called by them). | |
19455 | ||
19456 | @ignore | |
19457 | @c texi2dvi fails when the name of the section is within ifnottex ... | |
19458 | (@xref{Prevent confusion, , @code{let} Prevents Confusion}, and | |
19459 | @ref{defun, , The @code{defun} Special Form}.) | |
19460 | @end ignore | |
19461 | ||
d6adf7e7 | 19462 | @node yank |
8cda6f8f GM |
19463 | @appendixsec @code{yank} |
19464 | @findex yank | |
19465 | ||
19466 | After learning about @code{current-kill}, the code for the | |
19467 | @code{yank} function is almost easy. | |
19468 | ||
19469 | The @code{yank} function does not use the | |
19470 | @code{kill-ring-yank-pointer} variable directly. It calls | |
19471 | @code{insert-for-yank} which calls @code{current-kill} which sets the | |
19472 | @code{kill-ring-yank-pointer} variable. | |
19473 | ||
19474 | @need 1250 | |
19475 | The code looks like this: | |
19476 | ||
19477 | @c in GNU Emacs 22 | |
19478 | @smallexample | |
19479 | @group | |
19480 | (defun yank (&optional arg) | |
19481 | "Reinsert (\"paste\") the last stretch of killed text. | |
19482 | More precisely, reinsert the stretch of killed text most recently | |
19483 | killed OR yanked. Put point at end, and set mark at beginning. | |
19484 | With just \\[universal-argument] as argument, same but put point at | |
19485 | beginning (and mark at end). With argument N, reinsert the Nth most | |
19486 | recently killed stretch of killed text. | |
19487 | ||
19488 | When this command inserts killed text into the buffer, it honors | |
19489 | `yank-excluded-properties' and `yank-handler' as described in the | |
19490 | doc string for `insert-for-yank-1', which see. | |
19491 | ||
19492 | See also the command \\[yank-pop]." | |
19493 | @end group | |
19494 | @group | |
19495 | (interactive "*P") | |
19496 | (setq yank-window-start (window-start)) | |
19497 | ;; If we don't get all the way thru, make last-command indicate that | |
19498 | ;; for the following command. | |
19499 | (setq this-command t) | |
19500 | (push-mark (point)) | |
19501 | @end group | |
19502 | @group | |
19503 | (insert-for-yank (current-kill (cond | |
19504 | ((listp arg) 0) | |
19505 | ((eq arg '-) -2) | |
19506 | (t (1- arg))))) | |
19507 | (if (consp arg) | |
19508 | ;; This is like exchange-point-and-mark, | |
19509 | ;; but doesn't activate the mark. | |
19510 | ;; It is cleaner to avoid activation, even though the command | |
19511 | ;; loop would deactivate the mark because we inserted text. | |
19512 | (goto-char (prog1 (mark t) | |
19513 | (set-marker (mark-marker) (point) (current-buffer))))) | |
19514 | @end group | |
19515 | @group | |
19516 | ;; If we do get all the way thru, make this-command indicate that. | |
19517 | (if (eq this-command t) | |
19518 | (setq this-command 'yank)) | |
19519 | nil) | |
19520 | @end group | |
19521 | @end smallexample | |
19522 | ||
19523 | The key expression is @code{insert-for-yank}, which inserts the string | |
19524 | returned by @code{current-kill}, but removes some text properties from | |
19525 | it. | |
19526 | ||
19527 | However, before getting to that expression, the function sets the value | |
19528 | of @code{yank-window-start} to the position returned by the | |
19529 | @code{(window-start)} expression, the position at which the display | |
19530 | currently starts. The @code{yank} function also sets | |
19531 | @code{this-command} and pushes the mark. | |
19532 | ||
19533 | After it yanks the appropriate element, if the optional argument is a | |
19534 | @sc{cons} rather than a number or nothing, it puts point at beginning | |
19535 | of the yanked text and mark at its end. | |
19536 | ||
19537 | (The @code{prog1} function is like @code{progn} but returns the value | |
19538 | of its first argument rather than the value of its last argument. Its | |
19539 | first argument is forced to return the buffer's mark as an integer. | |
19540 | You can see the documentation for these functions by placing point | |
19541 | over them in this buffer and then typing @kbd{C-h f} | |
19542 | (@code{describe-function}) followed by a @kbd{RET}; the default is the | |
19543 | function.) | |
19544 | ||
19545 | The last part of the function tells what to do when it succeeds. | |
19546 | ||
d6adf7e7 | 19547 | @node yank-pop |
8cda6f8f GM |
19548 | @appendixsec @code{yank-pop} |
19549 | @findex yank-pop | |
19550 | ||
19551 | After understanding @code{yank} and @code{current-kill}, you know how | |
19552 | to approach the @code{yank-pop} function. Leaving out the | |
19553 | documentation to save space, it looks like this: | |
19554 | ||
19555 | @c GNU Emacs 22 | |
19556 | @smallexample | |
19557 | @group | |
19558 | (defun yank-pop (&optional arg) | |
19559 | "@dots{}" | |
19560 | (interactive "*p") | |
19561 | (if (not (eq last-command 'yank)) | |
19562 | (error "Previous command was not a yank")) | |
19563 | @end group | |
19564 | @group | |
19565 | (setq this-command 'yank) | |
19566 | (unless arg (setq arg 1)) | |
19567 | (let ((inhibit-read-only t) | |
19568 | (before (< (point) (mark t)))) | |
19569 | @end group | |
19570 | @group | |
19571 | (if before | |
19572 | (funcall (or yank-undo-function 'delete-region) (point) (mark t)) | |
19573 | (funcall (or yank-undo-function 'delete-region) (mark t) (point))) | |
19574 | (setq yank-undo-function nil) | |
19575 | @end group | |
19576 | @group | |
19577 | (set-marker (mark-marker) (point) (current-buffer)) | |
19578 | (insert-for-yank (current-kill arg)) | |
19579 | ;; Set the window start back where it was in the yank command, | |
19580 | ;; if possible. | |
19581 | (set-window-start (selected-window) yank-window-start t) | |
19582 | @end group | |
19583 | @group | |
19584 | (if before | |
19585 | ;; This is like exchange-point-and-mark, | |
19586 | ;; but doesn't activate the mark. | |
19587 | ;; It is cleaner to avoid activation, even though the command | |
19588 | ;; loop would deactivate the mark because we inserted text. | |
19589 | (goto-char (prog1 (mark t) | |
19590 | (set-marker (mark-marker) | |
19591 | (point) | |
19592 | (current-buffer)))))) | |
19593 | nil) | |
19594 | @end group | |
19595 | @end smallexample | |
19596 | ||
19597 | The function is interactive with a small @samp{p} so the prefix | |
19598 | argument is processed and passed to the function. The command can | |
19599 | only be used after a previous yank; otherwise an error message is | |
19600 | sent. This check uses the variable @code{last-command} which is set | |
19601 | by @code{yank} and is discussed elsewhere. | |
19602 | (@xref{copy-region-as-kill}.) | |
19603 | ||
19604 | The @code{let} clause sets the variable @code{before} to true or false | |
19605 | depending whether point is before or after mark and then the region | |
19606 | between point and mark is deleted. This is the region that was just | |
19607 | inserted by the previous yank and it is this text that will be | |
19608 | replaced. | |
19609 | ||
19610 | @code{funcall} calls its first argument as a function, passing | |
19611 | remaining arguments to it. The first argument is whatever the | |
19612 | @code{or} expression returns. The two remaining arguments are the | |
19613 | positions of point and mark set by the preceding @code{yank} command. | |
19614 | ||
19615 | There is more, but that is the hardest part. | |
19616 | ||
d6adf7e7 | 19617 | @node ring file |
8cda6f8f GM |
19618 | @appendixsec The @file{ring.el} File |
19619 | @cindex @file{ring.el} file | |
19620 | ||
19621 | Interestingly, GNU Emacs posses a file called @file{ring.el} that | |
19622 | provides many of the features we just discussed. But functions such | |
19623 | as @code{kill-ring-yank-pointer} do not use this library, possibly | |
19624 | because they were written earlier. | |
19625 | ||
d6adf7e7 | 19626 | @node Full Graph |
09e80d9f | 19627 | @appendix A Graph with Labeled Axes |
8cda6f8f GM |
19628 | |
19629 | Printed axes help you understand a graph. They convey scale. In an | |
19630 | earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we | |
19631 | wrote the code to print the body of a graph. Here we write the code | |
09e80d9f | 19632 | for printing and labeling vertical and horizontal axes, along with the |
8cda6f8f GM |
19633 | body itself. |
19634 | ||
19635 | @menu | |
09e80d9f | 19636 | * Labeled Example:: |
8cda6f8f GM |
19637 | * print-graph Varlist:: @code{let} expression in @code{print-graph}. |
19638 | * print-Y-axis:: Print a label for the vertical axis. | |
19639 | * print-X-axis:: Print a horizontal label. | |
19640 | * Print Whole Graph:: The function to print a complete graph. | |
19641 | @end menu | |
19642 | ||
8cda6f8f | 19643 | @ifnottex |
d6adf7e7 | 19644 | @node Labeled Example |
09e80d9f | 19645 | @unnumberedsec Labeled Example Graph |
8cda6f8f GM |
19646 | @end ifnottex |
19647 | ||
19648 | Since insertions fill a buffer to the right and below point, the new | |
19649 | graph printing function should first print the Y or vertical axis, | |
19650 | then the body of the graph, and finally the X or horizontal axis. | |
19651 | This sequence lays out for us the contents of the function: | |
19652 | ||
19653 | @enumerate | |
19654 | @item | |
19655 | Set up code. | |
19656 | ||
19657 | @item | |
19658 | Print Y axis. | |
19659 | ||
19660 | @item | |
19661 | Print body of graph. | |
19662 | ||
19663 | @item | |
19664 | Print X axis. | |
19665 | @end enumerate | |
19666 | ||
19667 | @need 800 | |
19668 | Here is an example of how a finished graph should look: | |
19669 | ||
19670 | @smallexample | |
19671 | @group | |
19672 | 10 - | |
19673 | * | |
19674 | * * | |
19675 | * ** | |
19676 | * *** | |
19677 | 5 - * ******* | |
19678 | * *** ******* | |
19679 | ************* | |
19680 | *************** | |
19681 | 1 - **************** | |
19682 | | | | | | |
19683 | 1 5 10 15 | |
19684 | @end group | |
19685 | @end smallexample | |
19686 | ||
19687 | @noindent | |
09e80d9f | 19688 | In this graph, both the vertical and the horizontal axes are labeled |
8cda6f8f | 19689 | with numbers. However, in some graphs, the horizontal axis is time |
09e80d9f | 19690 | and would be better labeled with months, like this: |
8cda6f8f GM |
19691 | |
19692 | @smallexample | |
19693 | @group | |
19694 | 5 - * | |
19695 | * ** * | |
19696 | ******* | |
19697 | ********** ** | |
19698 | 1 - ************** | |
19699 | | ^ | | |
19700 | Jan June Jan | |
19701 | @end group | |
19702 | @end smallexample | |
19703 | ||
19704 | Indeed, with a little thought, we can easily come up with a variety of | |
09e80d9f | 19705 | vertical and horizontal labeling schemes. Our task could become |
8cda6f8f | 19706 | complicated. But complications breed confusion. Rather than permit |
09e80d9f | 19707 | this, it is better choose a simple labeling scheme for our first |
8cda6f8f GM |
19708 | effort, and to modify or replace it later. |
19709 | ||
19710 | @need 1200 | |
19711 | These considerations suggest the following outline for the | |
19712 | @code{print-graph} function: | |
19713 | ||
19714 | @smallexample | |
19715 | @group | |
19716 | (defun print-graph (numbers-list) | |
19717 | "@var{documentation}@dots{}" | |
19718 | (let ((height @dots{} | |
19719 | @dots{})) | |
19720 | @end group | |
19721 | @group | |
19722 | (print-Y-axis height @dots{} ) | |
19723 | (graph-body-print numbers-list) | |
19724 | (print-X-axis @dots{} ))) | |
19725 | @end group | |
19726 | @end smallexample | |
19727 | ||
19728 | We can work on each part of the @code{print-graph} function definition | |
19729 | in turn. | |
19730 | ||
d6adf7e7 | 19731 | @node print-graph Varlist |
8cda6f8f GM |
19732 | @appendixsec The @code{print-graph} Varlist |
19733 | @cindex @code{print-graph} varlist | |
19734 | ||
19735 | In writing the @code{print-graph} function, the first task is to write | |
19736 | the varlist in the @code{let} expression. (We will leave aside for the | |
19737 | moment any thoughts about making the function interactive or about the | |
19738 | contents of its documentation string.) | |
19739 | ||
19740 | The varlist should set several values. Clearly, the top of the label | |
19741 | for the vertical axis must be at least the height of the graph, which | |
19742 | means that we must obtain this information here. Note that the | |
19743 | @code{print-graph-body} function also requires this information. There | |
19744 | is no reason to calculate the height of the graph in two different | |
19745 | places, so we should change @code{print-graph-body} from the way we | |
19746 | defined it earlier to take advantage of the calculation. | |
19747 | ||
19748 | Similarly, both the function for printing the X axis labels and the | |
19749 | @code{print-graph-body} function need to learn the value of the width of | |
19750 | each symbol. We can perform the calculation here and change the | |
19751 | definition for @code{print-graph-body} from the way we defined it in the | |
19752 | previous chapter. | |
19753 | ||
19754 | The length of the label for the horizontal axis must be at least as long | |
19755 | as the graph. However, this information is used only in the function | |
19756 | that prints the horizontal axis, so it does not need to be calculated here. | |
19757 | ||
19758 | These thoughts lead us directly to the following form for the varlist | |
19759 | in the @code{let} for @code{print-graph}: | |
19760 | ||
19761 | @smallexample | |
19762 | @group | |
19763 | (let ((height (apply 'max numbers-list)) ; @r{First version.} | |
19764 | (symbol-width (length graph-blank))) | |
19765 | @end group | |
19766 | @end smallexample | |
19767 | ||
19768 | @noindent | |
19769 | As we shall see, this expression is not quite right. | |
19770 | ||
19771 | @need 2000 | |
d6adf7e7 | 19772 | @node print-Y-axis |
8cda6f8f GM |
19773 | @appendixsec The @code{print-Y-axis} Function |
19774 | @cindex Axis, print vertical | |
19775 | @cindex Y axis printing | |
19776 | @cindex Vertical axis printing | |
19777 | @cindex Print vertical axis | |
19778 | ||
19779 | The job of the @code{print-Y-axis} function is to print a label for | |
19780 | the vertical axis that looks like this: | |
19781 | ||
19782 | @smallexample | |
19783 | @group | |
19784 | 10 - | |
19785 | ||
19786 | ||
19787 | ||
19788 | ||
19789 | 5 - | |
19790 | ||
19791 | ||
19792 | ||
19793 | 1 - | |
19794 | @end group | |
19795 | @end smallexample | |
19796 | ||
19797 | @noindent | |
19798 | The function should be passed the height of the graph, and then should | |
19799 | construct and insert the appropriate numbers and marks. | |
19800 | ||
19801 | @menu | |
19802 | * print-Y-axis in Detail:: | |
19803 | * Height of label:: What height for the Y axis? | |
19804 | * Compute a Remainder:: How to compute the remainder of a division. | |
19805 | * Y Axis Element:: Construct a line for the Y axis. | |
19806 | * Y-axis-column:: Generate a list of Y axis labels. | |
19807 | * print-Y-axis Penultimate:: A not quite final version. | |
19808 | @end menu | |
19809 | ||
8cda6f8f | 19810 | @ifnottex |
d6adf7e7 | 19811 | @node print-Y-axis in Detail |
8cda6f8f GM |
19812 | @unnumberedsubsec The @code{print-Y-axis} Function in Detail |
19813 | @end ifnottex | |
19814 | ||
19815 | It is easy enough to see in the figure what the Y axis label should | |
19816 | look like; but to say in words, and then to write a function | |
19817 | definition to do the job is another matter. It is not quite true to | |
19818 | say that we want a number and a tic every five lines: there are only | |
19819 | three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4), | |
19820 | but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8, | |
19821 | and 9). It is better to say that we want a number and a tic mark on | |
19822 | the base line (number 1) and then that we want a number and a tic on | |
19823 | the fifth line from the bottom and on every line that is a multiple of | |
19824 | five. | |
19825 | ||
8cda6f8f | 19826 | @ifnottex |
d6adf7e7 | 19827 | @node Height of label |
8cda6f8f GM |
19828 | @unnumberedsubsec What height should the label be? |
19829 | @end ifnottex | |
19830 | ||
19831 | The next issue is what height the label should be? Suppose the maximum | |
19832 | height of tallest column of the graph is seven. Should the highest | |
19833 | label on the Y axis be @samp{5 -}, and should the graph stick up above | |
19834 | the label? Or should the highest label be @samp{7 -}, and mark the peak | |
19835 | of the graph? Or should the highest label be @code{10 -}, which is a | |
19836 | multiple of five, and be higher than the topmost value of the graph? | |
19837 | ||
19838 | The latter form is preferred. Most graphs are drawn within rectangles | |
19839 | whose sides are an integral number of steps long---5, 10, 15, and so | |
19840 | on for a step distance of five. But as soon as we decide to use a | |
19841 | step height for the vertical axis, we discover that the simple | |
19842 | expression in the varlist for computing the height is wrong. The | |
19843 | expression is @code{(apply 'max numbers-list)}. This returns the | |
19844 | precise height, not the maximum height plus whatever is necessary to | |
19845 | round up to the nearest multiple of five. A more complex expression | |
19846 | is required. | |
19847 | ||
19848 | As usual in cases like this, a complex problem becomes simpler if it is | |
19849 | divided into several smaller problems. | |
19850 | ||
19851 | First, consider the case when the highest value of the graph is an | |
19852 | integral multiple of five---when it is 5, 10, 15, or some higher | |
19853 | multiple of five. We can use this value as the Y axis height. | |
19854 | ||
19855 | A fairly simply way to determine whether a number is a multiple of | |
19856 | five is to divide it by five and see if the division results in a | |
19857 | remainder. If there is no remainder, the number is a multiple of | |
19858 | five. Thus, seven divided by five has a remainder of two, and seven | |
19859 | is not an integral multiple of five. Put in slightly different | |
19860 | language, more reminiscent of the classroom, five goes into seven | |
19861 | once, with a remainder of two. However, five goes into ten twice, | |
19862 | with no remainder: ten is an integral multiple of five. | |
19863 | ||
d6adf7e7 | 19864 | @node Compute a Remainder |
8cda6f8f GM |
19865 | @appendixsubsec Side Trip: Compute a Remainder |
19866 | ||
19867 | @findex % @r{(remainder function)} | |
19868 | @cindex Remainder function, @code{%} | |
19869 | In Lisp, the function for computing a remainder is @code{%}. The | |
19870 | function returns the remainder of its first argument divided by its | |
19871 | second argument. As it happens, @code{%} is a function in Emacs Lisp | |
19872 | that you cannot discover using @code{apropos}: you find nothing if you | |
19873 | type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to | |
19874 | learn of the existence of @code{%} is to read about it in a book such | |
19875 | as this or in the Emacs Lisp sources. | |
19876 | ||
19877 | You can try the @code{%} function by evaluating the following two | |
19878 | expressions: | |
19879 | ||
19880 | @smallexample | |
19881 | @group | |
19882 | (% 7 5) | |
19883 | ||
19884 | (% 10 5) | |
19885 | @end group | |
19886 | @end smallexample | |
19887 | ||
19888 | @noindent | |
19889 | The first expression returns 2 and the second expression returns 0. | |
19890 | ||
19891 | To test whether the returned value is zero or some other number, we | |
19892 | can use the @code{zerop} function. This function returns @code{t} if | |
19893 | its argument, which must be a number, is zero. | |
19894 | ||
19895 | @smallexample | |
19896 | @group | |
19897 | (zerop (% 7 5)) | |
19898 | @result{} nil | |
19899 | ||
19900 | (zerop (% 10 5)) | |
19901 | @result{} t | |
19902 | @end group | |
19903 | @end smallexample | |
19904 | ||
19905 | Thus, the following expression will return @code{t} if the height | |
19906 | of the graph is evenly divisible by five: | |
19907 | ||
19908 | @smallexample | |
19909 | (zerop (% height 5)) | |
19910 | @end smallexample | |
19911 | ||
19912 | @noindent | |
19913 | (The value of @code{height}, of course, can be found from @code{(apply | |
19914 | 'max numbers-list)}.) | |
19915 | ||
19916 | On the other hand, if the value of @code{height} is not a multiple of | |
19917 | five, we want to reset the value to the next higher multiple of five. | |
19918 | This is straightforward arithmetic using functions with which we are | |
19919 | already familiar. First, we divide the value of @code{height} by five | |
19920 | to determine how many times five goes into the number. Thus, five | |
19921 | goes into twelve twice. If we add one to this quotient and multiply by | |
19922 | five, we will obtain the value of the next multiple of five that is | |
19923 | larger than the height. Five goes into twelve twice. Add one to two, | |
19924 | and multiply by five; the result is fifteen, which is the next multiple | |
19925 | of five that is higher than twelve. The Lisp expression for this is: | |
19926 | ||
19927 | @smallexample | |
19928 | (* (1+ (/ height 5)) 5) | |
19929 | @end smallexample | |
19930 | ||
19931 | @noindent | |
19932 | For example, if you evaluate the following, the result is 15: | |
19933 | ||
19934 | @smallexample | |
19935 | (* (1+ (/ 12 5)) 5) | |
19936 | @end smallexample | |
19937 | ||
19938 | All through this discussion, we have been using `five' as the value | |
19939 | for spacing labels on the Y axis; but we may want to use some other | |
19940 | value. For generality, we should replace `five' with a variable to | |
19941 | which we can assign a value. The best name I can think of for this | |
19942 | variable is @code{Y-axis-label-spacing}. | |
19943 | ||
19944 | @need 1250 | |
19945 | Using this term, and an @code{if} expression, we produce the | |
19946 | following: | |
19947 | ||
19948 | @smallexample | |
19949 | @group | |
19950 | (if (zerop (% height Y-axis-label-spacing)) | |
19951 | height | |
19952 | ;; @r{else} | |
19953 | (* (1+ (/ height Y-axis-label-spacing)) | |
19954 | Y-axis-label-spacing)) | |
19955 | @end group | |
19956 | @end smallexample | |
19957 | ||
19958 | @noindent | |
19959 | This expression returns the value of @code{height} itself if the height | |
19960 | is an even multiple of the value of the @code{Y-axis-label-spacing} or | |
19961 | else it computes and returns a value of @code{height} that is equal to | |
19962 | the next higher multiple of the value of the @code{Y-axis-label-spacing}. | |
19963 | ||
19964 | We can now include this expression in the @code{let} expression of the | |
19965 | @code{print-graph} function (after first setting the value of | |
19966 | @code{Y-axis-label-spacing}): | |
19967 | @vindex Y-axis-label-spacing | |
19968 | ||
19969 | @smallexample | |
19970 | @group | |
19971 | (defvar Y-axis-label-spacing 5 | |
19972 | "Number of lines from one Y axis label to next.") | |
19973 | @end group | |
19974 | ||
19975 | @group | |
19976 | @dots{} | |
19977 | (let* ((height (apply 'max numbers-list)) | |
19978 | (height-of-top-line | |
19979 | (if (zerop (% height Y-axis-label-spacing)) | |
19980 | height | |
19981 | @end group | |
19982 | @group | |
19983 | ;; @r{else} | |
19984 | (* (1+ (/ height Y-axis-label-spacing)) | |
19985 | Y-axis-label-spacing))) | |
19986 | (symbol-width (length graph-blank)))) | |
19987 | @dots{} | |
19988 | @end group | |
19989 | @end smallexample | |
19990 | ||
19991 | @noindent | |
19992 | (Note use of the @code{let*} function: the initial value of height is | |
19993 | computed once by the @code{(apply 'max numbers-list)} expression and | |
19994 | then the resulting value of @code{height} is used to compute its | |
19995 | final value. @xref{fwd-para let, , The @code{let*} expression}, for | |
19996 | more about @code{let*}.) | |
19997 | ||
d6adf7e7 | 19998 | @node Y Axis Element |
8cda6f8f GM |
19999 | @appendixsubsec Construct a Y Axis Element |
20000 | ||
20001 | When we print the vertical axis, we want to insert strings such as | |
20002 | @w{@samp{5 -}} and @w{@samp{10 - }} every five lines. | |
20003 | Moreover, we want the numbers and dashes to line up, so shorter | |
20004 | numbers must be padded with leading spaces. If some of the strings | |
20005 | use two digit numbers, the strings with single digit numbers must | |
20006 | include a leading blank space before the number. | |
20007 | ||
20008 | @findex number-to-string | |
20009 | To figure out the length of the number, the @code{length} function is | |
20010 | used. But the @code{length} function works only with a string, not with | |
20011 | a number. So the number has to be converted from being a number to | |
20012 | being a string. This is done with the @code{number-to-string} function. | |
20013 | For example, | |
20014 | ||
20015 | @smallexample | |
20016 | @group | |
20017 | (length (number-to-string 35)) | |
20018 | @result{} 2 | |
20019 | ||
20020 | (length (number-to-string 100)) | |
20021 | @result{} 3 | |
20022 | @end group | |
20023 | @end smallexample | |
20024 | ||
20025 | @noindent | |
20026 | (@code{number-to-string} is also called @code{int-to-string}; you will | |
20027 | see this alternative name in various sources.) | |
20028 | ||
20029 | In addition, in each label, each number is followed by a string such | |
20030 | as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker. | |
20031 | This variable is defined with @code{defvar}: | |
20032 | ||
20033 | @vindex Y-axis-tic | |
20034 | @smallexample | |
20035 | @group | |
20036 | (defvar Y-axis-tic " - " | |
20037 | "String that follows number in a Y axis label.") | |
20038 | @end group | |
20039 | @end smallexample | |
20040 | ||
20041 | The length of the Y label is the sum of the length of the Y axis tic | |
20042 | mark and the length of the number of the top of the graph. | |
20043 | ||
20044 | @smallexample | |
20045 | (length (concat (number-to-string height) Y-axis-tic))) | |
20046 | @end smallexample | |
20047 | ||
20048 | This value will be calculated by the @code{print-graph} function in | |
20049 | its varlist as @code{full-Y-label-width} and passed on. (Note that we | |
20050 | did not think to include this in the varlist when we first proposed it.) | |
20051 | ||
20052 | To make a complete vertical axis label, a tic mark is concatenated | |
20053 | with a number; and the two together may be preceded by one or more | |
20054 | spaces depending on how long the number is. The label consists of | |
20055 | three parts: the (optional) leading spaces, the number, and the tic | |
20056 | mark. The function is passed the value of the number for the specific | |
20057 | row, and the value of the width of the top line, which is calculated | |
20058 | (just once) by @code{print-graph}. | |
20059 | ||
20060 | @smallexample | |
20061 | @group | |
20062 | (defun Y-axis-element (number full-Y-label-width) | |
20063 | "Construct a NUMBERed label element. | |
20064 | A numbered element looks like this ` 5 - ', | |
20065 | and is padded as needed so all line up with | |
20066 | the element for the largest number." | |
20067 | @end group | |
20068 | @group | |
20069 | (let* ((leading-spaces | |
20070 | (- full-Y-label-width | |
20071 | (length | |
20072 | (concat (number-to-string number) | |
20073 | Y-axis-tic))))) | |
20074 | @end group | |
20075 | @group | |
20076 | (concat | |
20077 | (make-string leading-spaces ? ) | |
20078 | (number-to-string number) | |
20079 | Y-axis-tic))) | |
20080 | @end group | |
20081 | @end smallexample | |
20082 | ||
20083 | The @code{Y-axis-element} function concatenates together the leading | |
20084 | spaces, if any; the number, as a string; and the tic mark. | |
20085 | ||
20086 | To figure out how many leading spaces the label will need, the | |
20087 | function subtracts the actual length of the label---the length of the | |
20088 | number plus the length of the tic mark---from the desired label width. | |
20089 | ||
20090 | @findex make-string | |
20091 | Blank spaces are inserted using the @code{make-string} function. This | |
20092 | function takes two arguments: the first tells it how long the string | |
20093 | will be and the second is a symbol for the character to insert, in a | |
20094 | special format. The format is a question mark followed by a blank | |
20095 | space, like this, @samp{? }. @xref{Character Type, , Character Type, | |
20096 | elisp, The GNU Emacs Lisp Reference Manual}, for a description of the | |
20097 | syntax for characters. (Of course, you might want to replace the | |
20098 | blank space by some other character @dots{} You know what to do.) | |
20099 | ||
20100 | The @code{number-to-string} function is used in the concatenation | |
20101 | expression, to convert the number to a string that is concatenated | |
20102 | with the leading spaces and the tic mark. | |
20103 | ||
d6adf7e7 | 20104 | @node Y-axis-column |
8cda6f8f GM |
20105 | @appendixsubsec Create a Y Axis Column |
20106 | ||
20107 | The preceding functions provide all the tools needed to construct a | |
20108 | function that generates a list of numbered and blank strings to insert | |
20109 | as the label for the vertical axis: | |
20110 | ||
20111 | @findex Y-axis-column | |
20112 | @smallexample | |
20113 | @group | |
20114 | (defun Y-axis-column (height width-of-label) | |
20115 | "Construct list of Y axis labels and blank strings. | |
20116 | For HEIGHT of line above base and WIDTH-OF-LABEL." | |
20117 | (let (Y-axis) | |
20118 | @group | |
20119 | @end group | |
20120 | (while (> height 1) | |
20121 | (if (zerop (% height Y-axis-label-spacing)) | |
20122 | ;; @r{Insert label.} | |
20123 | (setq Y-axis | |
20124 | (cons | |
20125 | (Y-axis-element height width-of-label) | |
20126 | Y-axis)) | |
20127 | @group | |
20128 | @end group | |
20129 | ;; @r{Else, insert blanks.} | |
20130 | (setq Y-axis | |
20131 | (cons | |
20132 | (make-string width-of-label ? ) | |
20133 | Y-axis))) | |
20134 | (setq height (1- height))) | |
20135 | ;; @r{Insert base line.} | |
20136 | (setq Y-axis | |
20137 | (cons (Y-axis-element 1 width-of-label) Y-axis)) | |
20138 | (nreverse Y-axis))) | |
20139 | @end group | |
20140 | @end smallexample | |
20141 | ||
20142 | In this function, we start with the value of @code{height} and | |
20143 | repetitively subtract one from its value. After each subtraction, we | |
20144 | test to see whether the value is an integral multiple of the | |
20145 | @code{Y-axis-label-spacing}. If it is, we construct a numbered label | |
20146 | using the @code{Y-axis-element} function; if not, we construct a | |
20147 | blank label using the @code{make-string} function. The base line | |
20148 | consists of the number one followed by a tic mark. | |
20149 | ||
20150 | @need 2000 | |
d6adf7e7 | 20151 | @node print-Y-axis Penultimate |
8cda6f8f GM |
20152 | @appendixsubsec The Not Quite Final Version of @code{print-Y-axis} |
20153 | ||
20154 | The list constructed by the @code{Y-axis-column} function is passed to | |
20155 | the @code{print-Y-axis} function, which inserts the list as a column. | |
20156 | ||
20157 | @findex print-Y-axis | |
20158 | @smallexample | |
20159 | @group | |
20160 | (defun print-Y-axis (height full-Y-label-width) | |
20161 | "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH. | |
20162 | Height must be the maximum height of the graph. | |
20163 | Full width is the width of the highest label element." | |
20164 | ;; Value of height and full-Y-label-width | |
20165 | ;; are passed by `print-graph'. | |
20166 | @end group | |
20167 | @group | |
20168 | (let ((start (point))) | |
20169 | (insert-rectangle | |
20170 | (Y-axis-column height full-Y-label-width)) | |
20171 | ;; @r{Place point ready for inserting graph.} | |
20172 | (goto-char start) | |
20173 | ;; @r{Move point forward by value of} full-Y-label-width | |
20174 | (forward-char full-Y-label-width))) | |
20175 | @end group | |
20176 | @end smallexample | |
20177 | ||
20178 | The @code{print-Y-axis} uses the @code{insert-rectangle} function to | |
20179 | insert the Y axis labels created by the @code{Y-axis-column} function. | |
20180 | In addition, it places point at the correct position for printing the body of | |
20181 | the graph. | |
20182 | ||
20183 | You can test @code{print-Y-axis}: | |
20184 | ||
20185 | @enumerate | |
20186 | @item | |
20187 | Install | |
20188 | ||
20189 | @smallexample | |
20190 | @group | |
20191 | Y-axis-label-spacing | |
20192 | Y-axis-tic | |
20193 | Y-axis-element | |
20194 | Y-axis-column | |
20195 | print-Y-axis | |
20196 | @end group | |
20197 | @end smallexample | |
20198 | ||
20199 | @item | |
20200 | Copy the following expression: | |
20201 | ||
20202 | @smallexample | |
20203 | (print-Y-axis 12 5) | |
20204 | @end smallexample | |
20205 | ||
20206 | @item | |
20207 | Switch to the @file{*scratch*} buffer and place the cursor where you | |
20208 | want the axis labels to start. | |
20209 | ||
20210 | @item | |
20211 | Type @kbd{M-:} (@code{eval-expression}). | |
20212 | ||
20213 | @item | |
20214 | Yank the @code{graph-body-print} expression into the minibuffer | |
20215 | with @kbd{C-y} (@code{yank)}. | |
20216 | ||
20217 | @item | |
20218 | Press @key{RET} to evaluate the expression. | |
20219 | @end enumerate | |
20220 | ||
20221 | Emacs will print labels vertically, the top one being @w{@samp{10 -@w{ | |
20222 | }}}. (The @code{print-graph} function will pass the value of | |
20223 | @code{height-of-top-line}, which in this case will end up as 15, | |
20224 | thereby getting rid of what might appear as a bug.) | |
20225 | ||
20226 | @need 2000 | |
d6adf7e7 | 20227 | @node print-X-axis |
8cda6f8f GM |
20228 | @appendixsec The @code{print-X-axis} Function |
20229 | @cindex Axis, print horizontal | |
20230 | @cindex X axis printing | |
20231 | @cindex Print horizontal axis | |
20232 | @cindex Horizontal axis printing | |
20233 | ||
20234 | X axis labels are much like Y axis labels, except that the ticks are on a | |
20235 | line above the numbers. Labels should look like this: | |
20236 | ||
20237 | @smallexample | |
20238 | @group | |
20239 | | | | | | |
20240 | 1 5 10 15 | |
20241 | @end group | |
20242 | @end smallexample | |
20243 | ||
20244 | The first tic is under the first column of the graph and is preceded by | |
20245 | several blank spaces. These spaces provide room in rows above for the Y | |
20246 | axis labels. The second, third, fourth, and subsequent ticks are all | |
20247 | spaced equally, according to the value of @code{X-axis-label-spacing}. | |
20248 | ||
20249 | The second row of the X axis consists of numbers, preceded by several | |
20250 | blank spaces and also separated according to the value of the variable | |
20251 | @code{X-axis-label-spacing}. | |
20252 | ||
20253 | The value of the variable @code{X-axis-label-spacing} should itself be | |
20254 | measured in units of @code{symbol-width}, since you may want to change | |
20255 | the width of the symbols that you are using to print the body of the | |
09e80d9f | 20256 | graph without changing the ways the graph is labeled. |
8cda6f8f GM |
20257 | |
20258 | @menu | |
20259 | * Similarities differences:: Much like @code{print-Y-axis}, but not exactly. | |
20260 | * X Axis Tic Marks:: Create tic marks for the horizontal axis. | |
20261 | @end menu | |
20262 | ||
8cda6f8f | 20263 | @ifnottex |
d6adf7e7 | 20264 | @node Similarities differences |
8cda6f8f GM |
20265 | @unnumberedsubsec Similarities and differences |
20266 | @end ifnottex | |
20267 | ||
20268 | The @code{print-X-axis} function is constructed in more or less the | |
20269 | same fashion as the @code{print-Y-axis} function except that it has | |
20270 | two lines: the line of tic marks and the numbers. We will write a | |
20271 | separate function to print each line and then combine them within the | |
20272 | @code{print-X-axis} function. | |
20273 | ||
20274 | This is a three step process: | |
20275 | ||
20276 | @enumerate | |
20277 | @item | |
20278 | Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}. | |
20279 | ||
20280 | @item | |
20281 | Write a function to print the X numbers, @code{print-X-axis-numbered-line}. | |
20282 | ||
20283 | @item | |
20284 | Write a function to print both lines, the @code{print-X-axis} function, | |
20285 | using @code{print-X-axis-tic-line} and | |
20286 | @code{print-X-axis-numbered-line}. | |
20287 | @end enumerate | |
20288 | ||
d6adf7e7 | 20289 | @node X Axis Tic Marks |
8cda6f8f GM |
20290 | @appendixsubsec X Axis Tic Marks |
20291 | ||
20292 | The first function should print the X axis tic marks. We must specify | |
20293 | the tic marks themselves and their spacing: | |
20294 | ||
20295 | @smallexample | |
20296 | @group | |
20297 | (defvar X-axis-label-spacing | |
20298 | (if (boundp 'graph-blank) | |
20299 | (* 5 (length graph-blank)) 5) | |
20300 | "Number of units from one X axis label to next.") | |
20301 | @end group | |
20302 | @end smallexample | |
20303 | ||
20304 | @noindent | |
20305 | (Note that the value of @code{graph-blank} is set by another | |
20306 | @code{defvar}. The @code{boundp} predicate checks whether it has | |
20307 | already been set; @code{boundp} returns @code{nil} if it has not. If | |
20308 | @code{graph-blank} were unbound and we did not use this conditional | |
20309 | construction, in a recent GNU Emacs, we would enter the debugger and | |
20310 | see an error message saying @samp{@w{Debugger entered--Lisp error:} | |
20311 | @w{(void-variable graph-blank)}}.) | |
20312 | ||
20313 | @need 1200 | |
20314 | Here is the @code{defvar} for @code{X-axis-tic-symbol}: | |
20315 | ||
20316 | @smallexample | |
20317 | @group | |
20318 | (defvar X-axis-tic-symbol "|" | |
20319 | "String to insert to point to a column in X axis.") | |
20320 | @end group | |
20321 | @end smallexample | |
20322 | ||
20323 | @need 1250 | |
20324 | The goal is to make a line that looks like this: | |
20325 | ||
20326 | @smallexample | |
20327 | | | | | | |
20328 | @end smallexample | |
20329 | ||
20330 | The first tic is indented so that it is under the first column, which is | |
20331 | indented to provide space for the Y axis labels. | |
20332 | ||
20333 | A tic element consists of the blank spaces that stretch from one tic to | |
20334 | the next plus a tic symbol. The number of blanks is determined by the | |
20335 | width of the tic symbol and the @code{X-axis-label-spacing}. | |
20336 | ||
20337 | @need 1250 | |
20338 | The code looks like this: | |
20339 | ||
20340 | @smallexample | |
20341 | @group | |
20342 | ;;; X-axis-tic-element | |
20343 | @dots{} | |
20344 | (concat | |
20345 | (make-string | |
20346 | ;; @r{Make a string of blanks.} | |
20347 | (- (* symbol-width X-axis-label-spacing) | |
20348 | (length X-axis-tic-symbol)) | |
20349 | ? ) | |
20350 | ;; @r{Concatenate blanks with tic symbol.} | |
20351 | X-axis-tic-symbol) | |
20352 | @dots{} | |
20353 | @end group | |
20354 | @end smallexample | |
20355 | ||
20356 | Next, we determine how many blanks are needed to indent the first tic | |
20357 | mark to the first column of the graph. This uses the value of | |
20358 | @code{full-Y-label-width} passed it by the @code{print-graph} function. | |
20359 | ||
20360 | @need 1250 | |
20361 | The code to make @code{X-axis-leading-spaces} | |
20362 | looks like this: | |
20363 | ||
20364 | @smallexample | |
20365 | @group | |
20366 | ;; X-axis-leading-spaces | |
20367 | @dots{} | |
20368 | (make-string full-Y-label-width ? ) | |
20369 | @dots{} | |
20370 | @end group | |
20371 | @end smallexample | |
20372 | ||
20373 | We also need to determine the length of the horizontal axis, which is | |
20374 | the length of the numbers list, and the number of ticks in the horizontal | |
20375 | axis: | |
20376 | ||
20377 | @smallexample | |
20378 | @group | |
20379 | ;; X-length | |
20380 | @dots{} | |
20381 | (length numbers-list) | |
20382 | @end group | |
20383 | ||
20384 | @group | |
20385 | ;; tic-width | |
20386 | @dots{} | |
20387 | (* symbol-width X-axis-label-spacing) | |
20388 | @end group | |
20389 | ||
20390 | @group | |
20391 | ;; number-of-X-ticks | |
20392 | (if (zerop (% (X-length tic-width))) | |
20393 | (/ (X-length tic-width)) | |
20394 | (1+ (/ (X-length tic-width)))) | |
20395 | @end group | |
20396 | @end smallexample | |
20397 | ||
20398 | @need 1250 | |
20399 | All this leads us directly to the function for printing the X axis tic line: | |
20400 | ||
20401 | @findex print-X-axis-tic-line | |
20402 | @smallexample | |
20403 | @group | |
20404 | (defun print-X-axis-tic-line | |
20405 | (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) | |
20406 | "Print ticks for X axis." | |
20407 | (insert X-axis-leading-spaces) | |
20408 | (insert X-axis-tic-symbol) ; @r{Under first column.} | |
20409 | @end group | |
20410 | @group | |
20411 | ;; @r{Insert second tic in the right spot.} | |
20412 | (insert (concat | |
20413 | (make-string | |
20414 | (- (* symbol-width X-axis-label-spacing) | |
20415 | ;; @r{Insert white space up to second tic symbol.} | |
20416 | (* 2 (length X-axis-tic-symbol))) | |
20417 | ? ) | |
20418 | X-axis-tic-symbol)) | |
20419 | @end group | |
20420 | @group | |
20421 | ;; @r{Insert remaining ticks.} | |
20422 | (while (> number-of-X-tics 1) | |
20423 | (insert X-axis-tic-element) | |
20424 | (setq number-of-X-tics (1- number-of-X-tics)))) | |
20425 | @end group | |
20426 | @end smallexample | |
20427 | ||
20428 | The line of numbers is equally straightforward: | |
20429 | ||
20430 | @need 1250 | |
20431 | First, we create a numbered element with blank spaces before each number: | |
20432 | ||
20433 | @findex X-axis-element | |
20434 | @smallexample | |
20435 | @group | |
20436 | (defun X-axis-element (number) | |
20437 | "Construct a numbered X axis element." | |
20438 | (let ((leading-spaces | |
20439 | (- (* symbol-width X-axis-label-spacing) | |
20440 | (length (number-to-string number))))) | |
20441 | (concat (make-string leading-spaces ? ) | |
20442 | (number-to-string number)))) | |
20443 | @end group | |
20444 | @end smallexample | |
20445 | ||
20446 | Next, we create the function to print the numbered line, starting with | |
20447 | the number ``1'' under the first column: | |
20448 | ||
20449 | @findex print-X-axis-numbered-line | |
20450 | @smallexample | |
20451 | @group | |
20452 | (defun print-X-axis-numbered-line | |
20453 | (number-of-X-tics X-axis-leading-spaces) | |
20454 | "Print line of X-axis numbers" | |
20455 | (let ((number X-axis-label-spacing)) | |
20456 | (insert X-axis-leading-spaces) | |
20457 | (insert "1") | |
20458 | @end group | |
20459 | @group | |
20460 | (insert (concat | |
20461 | (make-string | |
20462 | ;; @r{Insert white space up to next number.} | |
20463 | (- (* symbol-width X-axis-label-spacing) 2) | |
20464 | ? ) | |
20465 | (number-to-string number))) | |
20466 | @end group | |
20467 | @group | |
20468 | ;; @r{Insert remaining numbers.} | |
20469 | (setq number (+ number X-axis-label-spacing)) | |
20470 | (while (> number-of-X-tics 1) | |
20471 | (insert (X-axis-element number)) | |
20472 | (setq number (+ number X-axis-label-spacing)) | |
20473 | (setq number-of-X-tics (1- number-of-X-tics))))) | |
20474 | @end group | |
20475 | @end smallexample | |
20476 | ||
20477 | Finally, we need to write the @code{print-X-axis} that uses | |
20478 | @code{print-X-axis-tic-line} and | |
20479 | @code{print-X-axis-numbered-line}. | |
20480 | ||
20481 | The function must determine the local values of the variables used by both | |
20482 | @code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and | |
20483 | then it must call them. Also, it must print the carriage return that | |
20484 | separates the two lines. | |
20485 | ||
20486 | The function consists of a varlist that specifies five local variables, | |
20487 | and calls to each of the two line printing functions: | |
20488 | ||
20489 | @findex print-X-axis | |
20490 | @smallexample | |
20491 | @group | |
20492 | (defun print-X-axis (numbers-list) | |
20493 | "Print X axis labels to length of NUMBERS-LIST." | |
20494 | (let* ((leading-spaces | |
20495 | (make-string full-Y-label-width ? )) | |
20496 | @end group | |
20497 | @group | |
20498 | ;; symbol-width @r{is provided by} graph-body-print | |
20499 | (tic-width (* symbol-width X-axis-label-spacing)) | |
20500 | (X-length (length numbers-list)) | |
20501 | @end group | |
20502 | @group | |
20503 | (X-tic | |
20504 | (concat | |
20505 | (make-string | |
20506 | @end group | |
20507 | @group | |
20508 | ;; @r{Make a string of blanks.} | |
20509 | (- (* symbol-width X-axis-label-spacing) | |
20510 | (length X-axis-tic-symbol)) | |
20511 | ? ) | |
20512 | @end group | |
20513 | @group | |
20514 | ;; @r{Concatenate blanks with tic symbol.} | |
20515 | X-axis-tic-symbol)) | |
20516 | @end group | |
20517 | @group | |
20518 | (tic-number | |
20519 | (if (zerop (% X-length tic-width)) | |
20520 | (/ X-length tic-width) | |
20521 | (1+ (/ X-length tic-width))))) | |
20522 | @end group | |
20523 | @group | |
20524 | (print-X-axis-tic-line tic-number leading-spaces X-tic) | |
20525 | (insert "\n") | |
20526 | (print-X-axis-numbered-line tic-number leading-spaces))) | |
20527 | @end group | |
20528 | @end smallexample | |
20529 | ||
20530 | @need 1250 | |
20531 | You can test @code{print-X-axis}: | |
20532 | ||
20533 | @enumerate | |
20534 | @item | |
20535 | Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing}, | |
20536 | @code{print-X-axis-tic-line}, as well as @code{X-axis-element}, | |
20537 | @code{print-X-axis-numbered-line}, and @code{print-X-axis}. | |
20538 | ||
20539 | @item | |
20540 | Copy the following expression: | |
20541 | ||
20542 | @smallexample | |
20543 | @group | |
20544 | (progn | |
20545 | (let ((full-Y-label-width 5) | |
20546 | (symbol-width 1)) | |
20547 | (print-X-axis | |
20548 | '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16)))) | |
20549 | @end group | |
20550 | @end smallexample | |
20551 | ||
20552 | @item | |
20553 | Switch to the @file{*scratch*} buffer and place the cursor where you | |
20554 | want the axis labels to start. | |
20555 | ||
20556 | @item | |
20557 | Type @kbd{M-:} (@code{eval-expression}). | |
20558 | ||
20559 | @item | |
20560 | Yank the test expression into the minibuffer | |
20561 | with @kbd{C-y} (@code{yank)}. | |
20562 | ||
20563 | @item | |
20564 | Press @key{RET} to evaluate the expression. | |
20565 | @end enumerate | |
20566 | ||
20567 | @need 1250 | |
20568 | Emacs will print the horizontal axis like this: | |
20569 | @sp 1 | |
20570 | ||
20571 | @smallexample | |
20572 | @group | |
20573 | | | | | | | |
20574 | 1 5 10 15 20 | |
20575 | @end group | |
20576 | @end smallexample | |
20577 | ||
d6adf7e7 | 20578 | @node Print Whole Graph |
8cda6f8f GM |
20579 | @appendixsec Printing the Whole Graph |
20580 | @cindex Printing the whole graph | |
20581 | @cindex Whole graph printing | |
20582 | @cindex Graph, printing all | |
20583 | ||
20584 | Now we are nearly ready to print the whole graph. | |
20585 | ||
20586 | The function to print the graph with the proper labels follows the | |
09e80d9f | 20587 | outline we created earlier (@pxref{Full Graph, , A Graph with Labeled |
8cda6f8f GM |
20588 | Axes}), but with additions. |
20589 | ||
20590 | @need 1250 | |
20591 | Here is the outline: | |
20592 | ||
20593 | @smallexample | |
20594 | @group | |
20595 | (defun print-graph (numbers-list) | |
20596 | "@var{documentation}@dots{}" | |
20597 | (let ((height @dots{} | |
20598 | @dots{})) | |
20599 | @end group | |
20600 | @group | |
20601 | (print-Y-axis height @dots{} ) | |
20602 | (graph-body-print numbers-list) | |
20603 | (print-X-axis @dots{} ))) | |
20604 | @end group | |
20605 | @end smallexample | |
20606 | ||
20607 | @menu | |
20608 | * The final version:: A few changes. | |
20609 | * Test print-graph:: Run a short test. | |
20610 | * Graphing words in defuns:: Executing the final code. | |
20611 | * lambda:: How to write an anonymous function. | |
20612 | * mapcar:: Apply a function to elements of a list. | |
20613 | * Another Bug:: Yet another bug @dots{} most insidious. | |
20614 | * Final printed graph:: The graph itself! | |
20615 | @end menu | |
20616 | ||
8cda6f8f | 20617 | @ifnottex |
d6adf7e7 | 20618 | @node The final version |
8cda6f8f GM |
20619 | @unnumberedsubsec Changes for the Final Version |
20620 | @end ifnottex | |
20621 | ||
20622 | The final version is different from what we planned in two ways: | |
20623 | first, it contains additional values calculated once in the varlist; | |
20624 | second, it carries an option to specify the labels' increment per row. | |
20625 | This latter feature turns out to be essential; otherwise, a graph may | |
20626 | have more rows than fit on a display or on a sheet of paper. | |
20627 | ||
20628 | @need 1500 | |
20629 | This new feature requires a change to the @code{Y-axis-column} | |
20630 | function, to add @code{vertical-step} to it. The function looks like | |
20631 | this: | |
20632 | ||
20633 | @findex Y-axis-column @r{Final version.} | |
20634 | @smallexample | |
20635 | @group | |
20636 | ;;; @r{Final version.} | |
20637 | (defun Y-axis-column | |
20638 | (height width-of-label &optional vertical-step) | |
20639 | "Construct list of labels for Y axis. | |
20640 | HEIGHT is maximum height of graph. | |
20641 | WIDTH-OF-LABEL is maximum width of label. | |
20642 | VERTICAL-STEP, an option, is a positive integer | |
20643 | that specifies how much a Y axis label increments | |
20644 | for each line. For example, a step of 5 means | |
20645 | that each line is five units of the graph." | |
20646 | @end group | |
20647 | @group | |
20648 | (let (Y-axis | |
20649 | (number-per-line (or vertical-step 1))) | |
20650 | (while (> height 1) | |
20651 | (if (zerop (% height Y-axis-label-spacing)) | |
20652 | @end group | |
20653 | @group | |
20654 | ;; @r{Insert label.} | |
20655 | (setq Y-axis | |
20656 | (cons | |
20657 | (Y-axis-element | |
20658 | (* height number-per-line) | |
20659 | width-of-label) | |
20660 | Y-axis)) | |
20661 | @end group | |
20662 | @group | |
20663 | ;; @r{Else, insert blanks.} | |
20664 | (setq Y-axis | |
20665 | (cons | |
20666 | (make-string width-of-label ? ) | |
20667 | Y-axis))) | |
20668 | (setq height (1- height))) | |
20669 | @end group | |
20670 | @group | |
20671 | ;; @r{Insert base line.} | |
20672 | (setq Y-axis (cons (Y-axis-element | |
20673 | (or vertical-step 1) | |
20674 | width-of-label) | |
20675 | Y-axis)) | |
20676 | (nreverse Y-axis))) | |
20677 | @end group | |
20678 | @end smallexample | |
20679 | ||
20680 | The values for the maximum height of graph and the width of a symbol | |
20681 | are computed by @code{print-graph} in its @code{let} expression; so | |
20682 | @code{graph-body-print} must be changed to accept them. | |
20683 | ||
20684 | @findex graph-body-print @r{Final version.} | |
20685 | @smallexample | |
20686 | @group | |
20687 | ;;; @r{Final version.} | |
20688 | (defun graph-body-print (numbers-list height symbol-width) | |
20689 | "Print a bar graph of the NUMBERS-LIST. | |
20690 | The numbers-list consists of the Y-axis values. | |
20691 | HEIGHT is maximum height of graph. | |
20692 | SYMBOL-WIDTH is number of each column." | |
20693 | @end group | |
20694 | @group | |
20695 | (let (from-position) | |
20696 | (while numbers-list | |
20697 | (setq from-position (point)) | |
20698 | (insert-rectangle | |
20699 | (column-of-graph height (car numbers-list))) | |
20700 | (goto-char from-position) | |
20701 | (forward-char symbol-width) | |
20702 | @end group | |
20703 | @group | |
20704 | ;; @r{Draw graph column by column.} | |
20705 | (sit-for 0) | |
20706 | (setq numbers-list (cdr numbers-list))) | |
20707 | ;; @r{Place point for X axis labels.} | |
20708 | (forward-line height) | |
20709 | (insert "\n"))) | |
20710 | @end group | |
20711 | @end smallexample | |
20712 | ||
20713 | @need 1250 | |
20714 | Finally, the code for the @code{print-graph} function: | |
20715 | ||
20716 | @findex print-graph @r{Final version.} | |
20717 | @smallexample | |
20718 | @group | |
20719 | ;;; @r{Final version.} | |
20720 | (defun print-graph | |
20721 | (numbers-list &optional vertical-step) | |
09e80d9f | 20722 | "Print labeled bar graph of the NUMBERS-LIST. |
8cda6f8f GM |
20723 | The numbers-list consists of the Y-axis values. |
20724 | @end group | |
20725 | ||
20726 | @group | |
20727 | Optionally, VERTICAL-STEP, a positive integer, | |
20728 | specifies how much a Y axis label increments for | |
20729 | each line. For example, a step of 5 means that | |
20730 | each row is five units." | |
20731 | @end group | |
20732 | @group | |
20733 | (let* ((symbol-width (length graph-blank)) | |
20734 | ;; @code{height} @r{is both the largest number} | |
20735 | ;; @r{and the number with the most digits.} | |
20736 | (height (apply 'max numbers-list)) | |
20737 | @end group | |
20738 | @group | |
20739 | (height-of-top-line | |
20740 | (if (zerop (% height Y-axis-label-spacing)) | |
20741 | height | |
20742 | ;; @r{else} | |
20743 | (* (1+ (/ height Y-axis-label-spacing)) | |
20744 | Y-axis-label-spacing))) | |
20745 | @end group | |
20746 | @group | |
20747 | (vertical-step (or vertical-step 1)) | |
20748 | (full-Y-label-width | |
20749 | (length | |
20750 | @end group | |
20751 | @group | |
20752 | (concat | |
20753 | (number-to-string | |
20754 | (* height-of-top-line vertical-step)) | |
20755 | Y-axis-tic)))) | |
20756 | @end group | |
20757 | ||
20758 | @group | |
20759 | (print-Y-axis | |
20760 | height-of-top-line full-Y-label-width vertical-step) | |
20761 | @end group | |
20762 | @group | |
20763 | (graph-body-print | |
20764 | numbers-list height-of-top-line symbol-width) | |
20765 | (print-X-axis numbers-list))) | |
20766 | @end group | |
20767 | @end smallexample | |
20768 | ||
d6adf7e7 | 20769 | @node Test print-graph |
8cda6f8f GM |
20770 | @appendixsubsec Testing @code{print-graph} |
20771 | ||
20772 | @need 1250 | |
20773 | We can test the @code{print-graph} function with a short list of numbers: | |
20774 | ||
20775 | @enumerate | |
20776 | @item | |
20777 | Install the final versions of @code{Y-axis-column}, | |
20778 | @code{graph-body-print}, and @code{print-graph} (in addition to the | |
20779 | rest of the code.) | |
20780 | ||
20781 | @item | |
20782 | Copy the following expression: | |
20783 | ||
20784 | @smallexample | |
20785 | (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1)) | |
20786 | @end smallexample | |
20787 | ||
20788 | @item | |
20789 | Switch to the @file{*scratch*} buffer and place the cursor where you | |
20790 | want the axis labels to start. | |
20791 | ||
20792 | @item | |
20793 | Type @kbd{M-:} (@code{eval-expression}). | |
20794 | ||
20795 | @item | |
20796 | Yank the test expression into the minibuffer | |
20797 | with @kbd{C-y} (@code{yank)}. | |
20798 | ||
20799 | @item | |
20800 | Press @key{RET} to evaluate the expression. | |
20801 | @end enumerate | |
20802 | ||
20803 | @need 1250 | |
20804 | Emacs will print a graph that looks like this: | |
20805 | ||
20806 | @smallexample | |
20807 | @group | |
20808 | 10 - | |
20809 | ||
20810 | ||
20811 | * | |
20812 | ** * | |
20813 | 5 - **** * | |
20814 | **** *** | |
20815 | * ********* | |
20816 | ************ | |
20817 | 1 - ************* | |
20818 | ||
20819 | | | | | | |
20820 | 1 5 10 15 | |
20821 | @end group | |
20822 | @end smallexample | |
20823 | ||
20824 | @need 1200 | |
20825 | On the other hand, if you pass @code{print-graph} a | |
20826 | @code{vertical-step} value of 2, by evaluating this expression: | |
20827 | ||
20828 | @smallexample | |
20829 | (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2) | |
20830 | @end smallexample | |
20831 | ||
20832 | @need 1250 | |
20833 | @noindent | |
20834 | The graph looks like this: | |
20835 | ||
20836 | @smallexample | |
20837 | @group | |
20838 | 20 - | |
20839 | ||
20840 | ||
20841 | * | |
20842 | ** * | |
20843 | 10 - **** * | |
20844 | **** *** | |
20845 | * ********* | |
20846 | ************ | |
20847 | 2 - ************* | |
20848 | ||
20849 | | | | | | |
20850 | 1 5 10 15 | |
20851 | @end group | |
20852 | @end smallexample | |
20853 | ||
20854 | @noindent | |
20855 | (A question: is the `2' on the bottom of the vertical axis a bug or a | |
20856 | feature? If you think it is a bug, and should be a `1' instead, (or | |
20857 | even a `0'), you can modify the sources.) | |
20858 | ||
d6adf7e7 | 20859 | @node Graphing words in defuns |
8cda6f8f GM |
20860 | @appendixsubsec Graphing Numbers of Words and Symbols |
20861 | ||
20862 | Now for the graph for which all this code was written: a graph that | |
20863 | shows how many function definitions contain fewer than 10 words and | |
20864 | symbols, how many contain between 10 and 19 words and symbols, how | |
20865 | many contain between 20 and 29 words and symbols, and so on. | |
20866 | ||
20867 | This is a multi-step process. First make sure you have loaded all the | |
20868 | requisite code. | |
20869 | ||
20870 | @need 1500 | |
20871 | It is a good idea to reset the value of @code{top-of-ranges} in case | |
20872 | you have set it to some different value. You can evaluate the | |
20873 | following: | |
20874 | ||
20875 | @smallexample | |
20876 | @group | |
20877 | (setq top-of-ranges | |
20878 | '(10 20 30 40 50 | |
20879 | 60 70 80 90 100 | |
20880 | 110 120 130 140 150 | |
20881 | 160 170 180 190 200 | |
20882 | 210 220 230 240 250 | |
20883 | 260 270 280 290 300) | |
20884 | @end group | |
20885 | @end smallexample | |
20886 | ||
20887 | @noindent | |
20888 | Next create a list of the number of words and symbols in each range. | |
20889 | ||
20890 | @need 1500 | |
20891 | @noindent | |
20892 | Evaluate the following: | |
20893 | ||
20894 | @smallexample | |
20895 | @group | |
20896 | (setq list-for-graph | |
20897 | (defuns-per-range | |
20898 | (sort | |
20899 | (recursive-lengths-list-many-files | |
20900 | (directory-files "/usr/local/emacs/lisp" | |
20901 | t ".+el$")) | |
20902 | '<) | |
20903 | top-of-ranges)) | |
20904 | @end group | |
20905 | @end smallexample | |
20906 | ||
20907 | @noindent | |
20908 | On my old machine, this took about an hour. It looked though 303 Lisp | |
20909 | files in my copy of Emacs version 19.23. After all that computing, | |
20910 | the @code{list-for-graph} had this value: | |
20911 | ||
20912 | @smallexample | |
20913 | @group | |
20914 | (537 1027 955 785 594 483 349 292 224 199 166 120 116 99 | |
20915 | 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220) | |
20916 | @end group | |
20917 | @end smallexample | |
20918 | ||
20919 | @noindent | |
20920 | This means that my copy of Emacs had 537 function definitions with | |
20921 | fewer than 10 words or symbols in them, 1,027 function definitions | |
20922 | with 10 to 19 words or symbols in them, 955 function definitions with | |
20923 | 20 to 29 words or symbols in them, and so on. | |
20924 | ||
20925 | Clearly, just by looking at this list we can see that most function | |
20926 | definitions contain ten to thirty words and symbols. | |
20927 | ||
20928 | Now for printing. We do @emph{not} want to print a graph that is | |
20929 | 1,030 lines high @dots{} Instead, we should print a graph that is | |
20930 | fewer than twenty-five lines high. A graph that height can be | |
20931 | displayed on almost any monitor, and easily printed on a sheet of paper. | |
20932 | ||
20933 | This means that each value in @code{list-for-graph} must be reduced to | |
20934 | one-fiftieth its present value. | |
20935 | ||
20936 | Here is a short function to do just that, using two functions we have | |
20937 | not yet seen, @code{mapcar} and @code{lambda}. | |
20938 | ||
20939 | @smallexample | |
20940 | @group | |
20941 | (defun one-fiftieth (full-range) | |
20942 | "Return list, each number one-fiftieth of previous." | |
d1069532 | 20943 | (mapcar (lambda (arg) (/ arg 50)) full-range)) |
8cda6f8f GM |
20944 | @end group |
20945 | @end smallexample | |
20946 | ||
d6adf7e7 | 20947 | @node lambda |
8cda6f8f GM |
20948 | @appendixsubsec A @code{lambda} Expression: Useful Anonymity |
20949 | @cindex Anonymous function | |
20950 | @findex lambda | |
20951 | ||
20952 | @code{lambda} is the symbol for an anonymous function, a function | |
20953 | without a name. Every time you use an anonymous function, you need to | |
20954 | include its whole body. | |
20955 | ||
20956 | @need 1250 | |
20957 | @noindent | |
20958 | Thus, | |
20959 | ||
20960 | @smallexample | |
20961 | (lambda (arg) (/ arg 50)) | |
20962 | @end smallexample | |
20963 | ||
20964 | @noindent | |
20965 | is a function definition that says `return the value resulting from | |
20966 | dividing whatever is passed to me as @code{arg} by 50'. | |
20967 | ||
20968 | @need 1200 | |
20969 | Earlier, for example, we had a function @code{multiply-by-seven}; it | |
20970 | multiplied its argument by 7. This function is similar, except it | |
20971 | divides its argument by 50; and, it has no name. The anonymous | |
20972 | equivalent of @code{multiply-by-seven} is: | |
20973 | ||
20974 | @smallexample | |
20975 | (lambda (number) (* 7 number)) | |
20976 | @end smallexample | |
20977 | ||
20978 | @noindent | |
20979 | (@xref{defun, , The @code{defun} Special Form}.) | |
20980 | ||
20981 | @need 1250 | |
20982 | @noindent | |
20983 | If we want to multiply 3 by 7, we can write: | |
20984 | ||
20985 | @c !!! Clear print-postscript-figures if the computer formatting this | |
20986 | @c document is too small and cannot handle all the diagrams and figures. | |
20987 | @c clear print-postscript-figures | |
20988 | @c set print-postscript-figures | |
20989 | @c lambda example diagram #1 | |
20990 | @ifnottex | |
20991 | @smallexample | |
20992 | @group | |
20993 | (multiply-by-seven 3) | |
20994 | \_______________/ ^ | |
20995 | | | | |
20996 | function argument | |
20997 | @end group | |
20998 | @end smallexample | |
20999 | @end ifnottex | |
21000 | @ifset print-postscript-figures | |
21001 | @sp 1 | |
21002 | @tex | |
21003 | @center @image{lambda-1} | |
21004 | %%%% old method of including an image | |
21005 | % \input /usr/local/lib/tex/inputs/psfig.tex | |
21006 | % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}} | |
21007 | % \catcode`\@=0 % | |
21008 | @end tex | |
21009 | @sp 1 | |
21010 | @end ifset | |
21011 | @ifclear print-postscript-figures | |
21012 | @iftex | |
21013 | @smallexample | |
21014 | @group | |
21015 | (multiply-by-seven 3) | |
21016 | \_______________/ ^ | |
21017 | | | | |
21018 | function argument | |
21019 | @end group | |
21020 | @end smallexample | |
21021 | @end iftex | |
21022 | @end ifclear | |
21023 | ||
21024 | @noindent | |
21025 | This expression returns 21. | |
21026 | ||
21027 | @need 1250 | |
21028 | @noindent | |
21029 | Similarly, we can write: | |
21030 | ||
21031 | @c lambda example diagram #2 | |
21032 | @ifnottex | |
21033 | @smallexample | |
21034 | @group | |
21035 | ((lambda (number) (* 7 number)) 3) | |
21036 | \____________________________/ ^ | |
21037 | | | | |
21038 | anonymous function argument | |
21039 | @end group | |
21040 | @end smallexample | |
21041 | @end ifnottex | |
21042 | @ifset print-postscript-figures | |
21043 | @sp 1 | |
21044 | @tex | |
21045 | @center @image{lambda-2} | |
21046 | %%%% old method of including an image | |
21047 | % \input /usr/local/lib/tex/inputs/psfig.tex | |
21048 | % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}} | |
21049 | % \catcode`\@=0 % | |
21050 | @end tex | |
21051 | @sp 1 | |
21052 | @end ifset | |
21053 | @ifclear print-postscript-figures | |
21054 | @iftex | |
21055 | @smallexample | |
21056 | @group | |
21057 | ((lambda (number) (* 7 number)) 3) | |
21058 | \____________________________/ ^ | |
21059 | | | | |
21060 | anonymous function argument | |
21061 | @end group | |
21062 | @end smallexample | |
21063 | @end iftex | |
21064 | @end ifclear | |
21065 | ||
21066 | @need 1250 | |
21067 | @noindent | |
21068 | If we want to divide 100 by 50, we can write: | |
21069 | ||
21070 | @c lambda example diagram #3 | |
21071 | @ifnottex | |
21072 | @smallexample | |
21073 | @group | |
21074 | ((lambda (arg) (/ arg 50)) 100) | |
21075 | \______________________/ \_/ | |
21076 | | | | |
21077 | anonymous function argument | |
21078 | @end group | |
21079 | @end smallexample | |
21080 | @end ifnottex | |
21081 | @ifset print-postscript-figures | |
21082 | @sp 1 | |
21083 | @tex | |
21084 | @center @image{lambda-3} | |
21085 | %%%% old method of including an image | |
21086 | % \input /usr/local/lib/tex/inputs/psfig.tex | |
21087 | % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}} | |
21088 | % \catcode`\@=0 % | |
21089 | @end tex | |
21090 | @sp 1 | |
21091 | @end ifset | |
21092 | @ifclear print-postscript-figures | |
21093 | @iftex | |
21094 | @smallexample | |
21095 | @group | |
21096 | ((lambda (arg) (/ arg 50)) 100) | |
21097 | \______________________/ \_/ | |
21098 | | | | |
21099 | anonymous function argument | |
21100 | @end group | |
21101 | @end smallexample | |
21102 | @end iftex | |
21103 | @end ifclear | |
21104 | ||
21105 | @noindent | |
21106 | This expression returns 2. The 100 is passed to the function, which | |
21107 | divides that number by 50. | |
21108 | ||
21109 | @xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs | |
21110 | Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda | |
21111 | expressions derive from the Lambda Calculus. | |
21112 | ||
d6adf7e7 | 21113 | @node mapcar |
8cda6f8f GM |
21114 | @appendixsubsec The @code{mapcar} Function |
21115 | @findex mapcar | |
21116 | ||
21117 | @code{mapcar} is a function that calls its first argument with each | |
21118 | element of its second argument, in turn. The second argument must be | |
21119 | a sequence. | |
21120 | ||
21121 | The @samp{map} part of the name comes from the mathematical phrase, | |
21122 | `mapping over a domain', meaning to apply a function to each of the | |
21123 | elements in a domain. The mathematical phrase is based on the | |
21124 | metaphor of a surveyor walking, one step at a time, over an area he is | |
21125 | mapping. And @samp{car}, of course, comes from the Lisp notion of the | |
21126 | first of a list. | |
21127 | ||
21128 | @need 1250 | |
21129 | @noindent | |
21130 | For example, | |
21131 | ||
21132 | @smallexample | |
21133 | @group | |
21134 | (mapcar '1+ '(2 4 6)) | |
21135 | @result{} (3 5 7) | |
21136 | @end group | |
21137 | @end smallexample | |
21138 | ||
21139 | @noindent | |
21140 | The function @code{1+} which adds one to its argument, is executed on | |
21141 | @emph{each} element of the list, and a new list is returned. | |
21142 | ||
21143 | Contrast this with @code{apply}, which applies its first argument to | |
21144 | all the remaining. | |
21145 | (@xref{Readying a Graph, , Readying a Graph}, for a explanation of | |
21146 | @code{apply}.) | |
21147 | ||
21148 | @need 1250 | |
21149 | In the definition of @code{one-fiftieth}, the first argument is the | |
21150 | anonymous function: | |
21151 | ||
21152 | @smallexample | |
21153 | (lambda (arg) (/ arg 50)) | |
21154 | @end smallexample | |
21155 | ||
21156 | @noindent | |
21157 | and the second argument is @code{full-range}, which will be bound to | |
21158 | @code{list-for-graph}. | |
21159 | ||
21160 | @need 1250 | |
21161 | The whole expression looks like this: | |
21162 | ||
21163 | @smallexample | |
d1069532 | 21164 | (mapcar (lambda (arg) (/ arg 50)) full-range)) |
8cda6f8f GM |
21165 | @end smallexample |
21166 | ||
21167 | @xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs | |
21168 | Lisp Reference Manual}, for more about @code{mapcar}. | |
21169 | ||
21170 | Using the @code{one-fiftieth} function, we can generate a list in | |
21171 | which each element is one-fiftieth the size of the corresponding | |
21172 | element in @code{list-for-graph}. | |
21173 | ||
21174 | @smallexample | |
21175 | @group | |
21176 | (setq fiftieth-list-for-graph | |
21177 | (one-fiftieth list-for-graph)) | |
21178 | @end group | |
21179 | @end smallexample | |
21180 | ||
21181 | @need 1250 | |
21182 | The resulting list looks like this: | |
21183 | ||
21184 | @smallexample | |
21185 | @group | |
21186 | (10 20 19 15 11 9 6 5 4 3 3 2 2 | |
21187 | 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4) | |
21188 | @end group | |
21189 | @end smallexample | |
21190 | ||
21191 | @noindent | |
21192 | This, we are almost ready to print! (We also notice the loss of | |
21193 | information: many of the higher ranges are 0, meaning that fewer than | |
21194 | 50 defuns had that many words or symbols---but not necessarily meaning | |
21195 | that none had that many words or symbols.) | |
21196 | ||
d6adf7e7 | 21197 | @node Another Bug |
8cda6f8f GM |
21198 | @appendixsubsec Another Bug @dots{} Most Insidious |
21199 | @cindex Bug, most insidious type | |
21200 | @cindex Insidious type of bug | |
21201 | ||
21202 | I said `almost ready to print'! Of course, there is a bug in the | |
21203 | @code{print-graph} function @dots{} It has a @code{vertical-step} | |
21204 | option, but not a @code{horizontal-step} option. The | |
21205 | @code{top-of-range} scale goes from 10 to 300 by tens. But the | |
21206 | @code{print-graph} function will print only by ones. | |
21207 | ||
21208 | This is a classic example of what some consider the most insidious | |
21209 | type of bug, the bug of omission. This is not the kind of bug you can | |
21210 | find by studying the code, for it is not in the code; it is an omitted | |
21211 | feature. Your best actions are to try your program early and often; | |
21212 | and try to arrange, as much as you can, to write code that is easy to | |
21213 | understand and easy to change. Try to be aware, whenever you can, | |
21214 | that whatever you have written, @emph{will} be rewritten, if not soon, | |
21215 | eventually. A hard maxim to follow. | |
21216 | ||
21217 | It is the @code{print-X-axis-numbered-line} function that needs the | |
21218 | work; and then the @code{print-X-axis} and the @code{print-graph} | |
21219 | functions need to be adapted. Not much needs to be done; there is one | |
21220 | nicety: the numbers ought to line up under the tic marks. This takes | |
21221 | a little thought. | |
21222 | ||
21223 | @need 1250 | |
21224 | Here is the corrected @code{print-X-axis-numbered-line}: | |
21225 | ||
21226 | @smallexample | |
21227 | @group | |
21228 | (defun print-X-axis-numbered-line | |
21229 | (number-of-X-tics X-axis-leading-spaces | |
21230 | &optional horizontal-step) | |
21231 | "Print line of X-axis numbers" | |
21232 | (let ((number X-axis-label-spacing) | |
21233 | (horizontal-step (or horizontal-step 1))) | |
21234 | @end group | |
21235 | @group | |
21236 | (insert X-axis-leading-spaces) | |
21237 | ;; @r{Delete extra leading spaces.} | |
21238 | (delete-char | |
21239 | (- (1- | |
21240 | (length (number-to-string horizontal-step))))) | |
21241 | (insert (concat | |
21242 | (make-string | |
21243 | @end group | |
21244 | @group | |
21245 | ;; @r{Insert white space.} | |
21246 | (- (* symbol-width | |
21247 | X-axis-label-spacing) | |
21248 | (1- | |
21249 | (length | |
21250 | (number-to-string horizontal-step))) | |
21251 | 2) | |
21252 | ? ) | |
21253 | (number-to-string | |
21254 | (* number horizontal-step)))) | |
21255 | @end group | |
21256 | @group | |
21257 | ;; @r{Insert remaining numbers.} | |
21258 | (setq number (+ number X-axis-label-spacing)) | |
21259 | (while (> number-of-X-tics 1) | |
21260 | (insert (X-axis-element | |
21261 | (* number horizontal-step))) | |
21262 | (setq number (+ number X-axis-label-spacing)) | |
21263 | (setq number-of-X-tics (1- number-of-X-tics))))) | |
21264 | @end group | |
21265 | @end smallexample | |
21266 | ||
21267 | @need 1500 | |
21268 | If you are reading this in Info, you can see the new versions of | |
21269 | @code{print-X-axis} @code{print-graph} and evaluate them. If you are | |
21270 | reading this in a printed book, you can see the changed lines here | |
21271 | (the full text is too much to print). | |
21272 | ||
21273 | @iftex | |
21274 | @smallexample | |
21275 | @group | |
21276 | (defun print-X-axis (numbers-list horizontal-step) | |
21277 | @dots{} | |
21278 | (print-X-axis-numbered-line | |
21279 | tic-number leading-spaces horizontal-step)) | |
21280 | @end group | |
21281 | @end smallexample | |
21282 | ||
21283 | @smallexample | |
21284 | @group | |
21285 | (defun print-graph | |
21286 | (numbers-list | |
21287 | &optional vertical-step horizontal-step) | |
21288 | @dots{} | |
21289 | (print-X-axis numbers-list horizontal-step)) | |
21290 | @end group | |
21291 | @end smallexample | |
21292 | @end iftex | |
21293 | ||
21294 | @ifnottex | |
21295 | @smallexample | |
21296 | @group | |
21297 | (defun print-X-axis (numbers-list horizontal-step) | |
21298 | "Print X axis labels to length of NUMBERS-LIST. | |
21299 | Optionally, HORIZONTAL-STEP, a positive integer, | |
21300 | specifies how much an X axis label increments for | |
21301 | each column." | |
21302 | @end group | |
21303 | @group | |
21304 | ;; Value of symbol-width and full-Y-label-width | |
21305 | ;; are passed by `print-graph'. | |
21306 | (let* ((leading-spaces | |
21307 | (make-string full-Y-label-width ? )) | |
21308 | ;; symbol-width @r{is provided by} graph-body-print | |
21309 | (tic-width (* symbol-width X-axis-label-spacing)) | |
21310 | (X-length (length numbers-list)) | |
21311 | @end group | |
21312 | @group | |
21313 | (X-tic | |
21314 | (concat | |
21315 | (make-string | |
21316 | ;; @r{Make a string of blanks.} | |
21317 | (- (* symbol-width X-axis-label-spacing) | |
21318 | (length X-axis-tic-symbol)) | |
21319 | ? ) | |
21320 | @end group | |
21321 | @group | |
21322 | ;; @r{Concatenate blanks with tic symbol.} | |
21323 | X-axis-tic-symbol)) | |
21324 | (tic-number | |
21325 | (if (zerop (% X-length tic-width)) | |
21326 | (/ X-length tic-width) | |
21327 | (1+ (/ X-length tic-width))))) | |
21328 | @end group | |
21329 | ||
21330 | @group | |
21331 | (print-X-axis-tic-line | |
21332 | tic-number leading-spaces X-tic) | |
21333 | (insert "\n") | |
21334 | (print-X-axis-numbered-line | |
21335 | tic-number leading-spaces horizontal-step))) | |
21336 | @end group | |
21337 | @end smallexample | |
21338 | ||
21339 | @smallexample | |
21340 | @group | |
21341 | (defun print-graph | |
21342 | (numbers-list &optional vertical-step horizontal-step) | |
09e80d9f | 21343 | "Print labeled bar graph of the NUMBERS-LIST. |
8cda6f8f GM |
21344 | The numbers-list consists of the Y-axis values. |
21345 | @end group | |
21346 | ||
21347 | @group | |
21348 | Optionally, VERTICAL-STEP, a positive integer, | |
21349 | specifies how much a Y axis label increments for | |
21350 | each line. For example, a step of 5 means that | |
21351 | each row is five units. | |
21352 | @end group | |
21353 | ||
21354 | @group | |
21355 | Optionally, HORIZONTAL-STEP, a positive integer, | |
21356 | specifies how much an X axis label increments for | |
21357 | each column." | |
21358 | (let* ((symbol-width (length graph-blank)) | |
21359 | ;; @code{height} @r{is both the largest number} | |
21360 | ;; @r{and the number with the most digits.} | |
21361 | (height (apply 'max numbers-list)) | |
21362 | @end group | |
21363 | @group | |
21364 | (height-of-top-line | |
21365 | (if (zerop (% height Y-axis-label-spacing)) | |
21366 | height | |
21367 | ;; @r{else} | |
21368 | (* (1+ (/ height Y-axis-label-spacing)) | |
21369 | Y-axis-label-spacing))) | |
21370 | @end group | |
21371 | @group | |
21372 | (vertical-step (or vertical-step 1)) | |
21373 | (full-Y-label-width | |
21374 | (length | |
21375 | (concat | |
21376 | (number-to-string | |
21377 | (* height-of-top-line vertical-step)) | |
21378 | Y-axis-tic)))) | |
21379 | @end group | |
21380 | @group | |
21381 | (print-Y-axis | |
21382 | height-of-top-line full-Y-label-width vertical-step) | |
21383 | (graph-body-print | |
21384 | numbers-list height-of-top-line symbol-width) | |
21385 | (print-X-axis numbers-list horizontal-step))) | |
21386 | @end group | |
21387 | @end smallexample | |
21388 | @end ifnottex | |
21389 | ||
21390 | @c qqq | |
21391 | @ignore | |
21392 | Graphing Definitions Re-listed | |
21393 | ||
21394 | @need 1250 | |
21395 | Here are all the graphing definitions in their final form: | |
21396 | ||
21397 | @smallexample | |
21398 | @group | |
21399 | (defvar top-of-ranges | |
21400 | '(10 20 30 40 50 | |
21401 | 60 70 80 90 100 | |
21402 | 110 120 130 140 150 | |
21403 | 160 170 180 190 200 | |
21404 | 210 220 230 240 250) | |
21405 | "List specifying ranges for `defuns-per-range'.") | |
21406 | @end group | |
21407 | ||
21408 | @group | |
21409 | (defvar graph-symbol "*" | |
21410 | "String used as symbol in graph, usually an asterisk.") | |
21411 | @end group | |
21412 | ||
21413 | @group | |
21414 | (defvar graph-blank " " | |
21415 | "String used as blank in graph, usually a blank space. | |
21416 | graph-blank must be the same number of columns wide | |
21417 | as graph-symbol.") | |
21418 | @end group | |
21419 | ||
21420 | @group | |
21421 | (defvar Y-axis-tic " - " | |
21422 | "String that follows number in a Y axis label.") | |
21423 | @end group | |
21424 | ||
21425 | @group | |
21426 | (defvar Y-axis-label-spacing 5 | |
21427 | "Number of lines from one Y axis label to next.") | |
21428 | @end group | |
21429 | ||
21430 | @group | |
21431 | (defvar X-axis-tic-symbol "|" | |
21432 | "String to insert to point to a column in X axis.") | |
21433 | @end group | |
21434 | ||
21435 | @group | |
21436 | (defvar X-axis-label-spacing | |
21437 | (if (boundp 'graph-blank) | |
21438 | (* 5 (length graph-blank)) 5) | |
21439 | "Number of units from one X axis label to next.") | |
21440 | @end group | |
21441 | @end smallexample | |
21442 | ||
21443 | @smallexample | |
21444 | @group | |
21445 | (defun count-words-in-defun () | |
21446 | "Return the number of words and symbols in a defun." | |
21447 | (beginning-of-defun) | |
21448 | (let ((count 0) | |
21449 | (end (save-excursion (end-of-defun) (point)))) | |
21450 | @end group | |
21451 | ||
21452 | @group | |
21453 | (while | |
21454 | (and (< (point) end) | |
21455 | (re-search-forward | |
21456 | "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" | |
21457 | end t)) | |
21458 | (setq count (1+ count))) | |
21459 | count)) | |
21460 | @end group | |
21461 | @end smallexample | |
21462 | ||
21463 | @smallexample | |
21464 | @group | |
21465 | (defun lengths-list-file (filename) | |
21466 | "Return list of definitions' lengths within FILE. | |
21467 | The returned list is a list of numbers. | |
21468 | Each number is the number of words or | |
21469 | symbols in one function definition." | |
21470 | @end group | |
21471 | ||
21472 | @group | |
21473 | (message "Working on `%s' ... " filename) | |
21474 | (save-excursion | |
21475 | (let ((buffer (find-file-noselect filename)) | |
21476 | (lengths-list)) | |
21477 | (set-buffer buffer) | |
21478 | (setq buffer-read-only t) | |
21479 | (widen) | |
21480 | (goto-char (point-min)) | |
21481 | @end group | |
21482 | ||
21483 | @group | |
21484 | (while (re-search-forward "^(defun" nil t) | |
21485 | (setq lengths-list | |
21486 | (cons (count-words-in-defun) lengths-list))) | |
21487 | (kill-buffer buffer) | |
21488 | lengths-list))) | |
21489 | @end group | |
21490 | @end smallexample | |
21491 | ||
21492 | @smallexample | |
21493 | @group | |
21494 | (defun lengths-list-many-files (list-of-files) | |
21495 | "Return list of lengths of defuns in LIST-OF-FILES." | |
21496 | (let (lengths-list) | |
21497 | ;;; @r{true-or-false-test} | |
21498 | (while list-of-files | |
21499 | (setq lengths-list | |
21500 | (append | |
21501 | lengths-list | |
21502 | @end group | |
21503 | @group | |
21504 | ;;; @r{Generate a lengths' list.} | |
21505 | (lengths-list-file | |
21506 | (expand-file-name (car list-of-files))))) | |
21507 | ;;; @r{Make files' list shorter.} | |
21508 | (setq list-of-files (cdr list-of-files))) | |
21509 | ;;; @r{Return final value of lengths' list.} | |
21510 | lengths-list)) | |
21511 | @end group | |
21512 | @end smallexample | |
21513 | ||
21514 | @smallexample | |
21515 | @group | |
21516 | (defun defuns-per-range (sorted-lengths top-of-ranges) | |
21517 | "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." | |
21518 | (let ((top-of-range (car top-of-ranges)) | |
21519 | (number-within-range 0) | |
21520 | defuns-per-range-list) | |
21521 | @end group | |
21522 | ||
21523 | @group | |
21524 | ;; @r{Outer loop.} | |
21525 | (while top-of-ranges | |
21526 | ||
21527 | ;; @r{Inner loop.} | |
21528 | (while (and | |
21529 | ;; @r{Need number for numeric test.} | |
21530 | (car sorted-lengths) | |
21531 | (< (car sorted-lengths) top-of-range)) | |
21532 | ||
21533 | ;; @r{Count number of definitions within current range.} | |
21534 | (setq number-within-range (1+ number-within-range)) | |
21535 | (setq sorted-lengths (cdr sorted-lengths))) | |
21536 | @end group | |
21537 | ||
21538 | @group | |
21539 | ;; @r{Exit inner loop but remain within outer loop.} | |
21540 | ||
21541 | (setq defuns-per-range-list | |
21542 | (cons number-within-range defuns-per-range-list)) | |
21543 | (setq number-within-range 0) ; @r{Reset count to zero.} | |
21544 | ||
21545 | ;; @r{Move to next range.} | |
21546 | (setq top-of-ranges (cdr top-of-ranges)) | |
21547 | ;; @r{Specify next top of range value.} | |
21548 | (setq top-of-range (car top-of-ranges))) | |
21549 | @end group | |
21550 | ||
21551 | @group | |
21552 | ;; @r{Exit outer loop and count the number of defuns larger than} | |
21553 | ;; @r{ the largest top-of-range value.} | |
21554 | (setq defuns-per-range-list | |
21555 | (cons | |
21556 | (length sorted-lengths) | |
21557 | defuns-per-range-list)) | |
21558 | ||
21559 | ;; @r{Return a list of the number of definitions within each range,} | |
21560 | ;; @r{ smallest to largest.} | |
21561 | (nreverse defuns-per-range-list))) | |
21562 | @end group | |
21563 | @end smallexample | |
21564 | ||
21565 | @smallexample | |
21566 | @group | |
21567 | (defun column-of-graph (max-graph-height actual-height) | |
21568 | "Return list of MAX-GRAPH-HEIGHT strings; | |
21569 | ACTUAL-HEIGHT are graph-symbols. | |
21570 | The graph-symbols are contiguous entries at the end | |
21571 | of the list. | |
21572 | The list will be inserted as one column of a graph. | |
21573 | The strings are either graph-blank or graph-symbol." | |
21574 | @end group | |
21575 | ||
21576 | @group | |
21577 | (let ((insert-list nil) | |
21578 | (number-of-top-blanks | |
21579 | (- max-graph-height actual-height))) | |
21580 | ||
21581 | ;; @r{Fill in @code{graph-symbols}.} | |
21582 | (while (> actual-height 0) | |
21583 | (setq insert-list (cons graph-symbol insert-list)) | |
21584 | (setq actual-height (1- actual-height))) | |
21585 | @end group | |
21586 | ||
21587 | @group | |
21588 | ;; @r{Fill in @code{graph-blanks}.} | |
21589 | (while (> number-of-top-blanks 0) | |
21590 | (setq insert-list (cons graph-blank insert-list)) | |
21591 | (setq number-of-top-blanks | |
21592 | (1- number-of-top-blanks))) | |
21593 | ||
21594 | ;; @r{Return whole list.} | |
21595 | insert-list)) | |
21596 | @end group | |
21597 | @end smallexample | |
21598 | ||
21599 | @smallexample | |
21600 | @group | |
21601 | (defun Y-axis-element (number full-Y-label-width) | |
21602 | "Construct a NUMBERed label element. | |
21603 | A numbered element looks like this ` 5 - ', | |
21604 | and is padded as needed so all line up with | |
21605 | the element for the largest number." | |
21606 | @end group | |
21607 | @group | |
21608 | (let* ((leading-spaces | |
21609 | (- full-Y-label-width | |
21610 | (length | |
21611 | (concat (number-to-string number) | |
21612 | Y-axis-tic))))) | |
21613 | @end group | |
21614 | @group | |
21615 | (concat | |
21616 | (make-string leading-spaces ? ) | |
21617 | (number-to-string number) | |
21618 | Y-axis-tic))) | |
21619 | @end group | |
21620 | @end smallexample | |
21621 | ||
21622 | @smallexample | |
21623 | @group | |
21624 | (defun print-Y-axis | |
21625 | (height full-Y-label-width &optional vertical-step) | |
21626 | "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH. | |
21627 | Height must be the maximum height of the graph. | |
21628 | Full width is the width of the highest label element. | |
21629 | Optionally, print according to VERTICAL-STEP." | |
21630 | @end group | |
21631 | @group | |
21632 | ;; Value of height and full-Y-label-width | |
21633 | ;; are passed by `print-graph'. | |
21634 | (let ((start (point))) | |
21635 | (insert-rectangle | |
21636 | (Y-axis-column height full-Y-label-width vertical-step)) | |
21637 | @end group | |
21638 | @group | |
21639 | ;; @r{Place point ready for inserting graph.} | |
21640 | (goto-char start) | |
21641 | ;; @r{Move point forward by value of} full-Y-label-width | |
21642 | (forward-char full-Y-label-width))) | |
21643 | @end group | |
21644 | @end smallexample | |
21645 | ||
21646 | @smallexample | |
21647 | @group | |
21648 | (defun print-X-axis-tic-line | |
21649 | (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) | |
21650 | "Print ticks for X axis." | |
21651 | (insert X-axis-leading-spaces) | |
21652 | (insert X-axis-tic-symbol) ; @r{Under first column.} | |
21653 | @end group | |
21654 | @group | |
21655 | ;; @r{Insert second tic in the right spot.} | |
21656 | (insert (concat | |
21657 | (make-string | |
21658 | (- (* symbol-width X-axis-label-spacing) | |
21659 | ;; @r{Insert white space up to second tic symbol.} | |
21660 | (* 2 (length X-axis-tic-symbol))) | |
21661 | ? ) | |
21662 | X-axis-tic-symbol)) | |
21663 | @end group | |
21664 | @group | |
21665 | ;; @r{Insert remaining ticks.} | |
21666 | (while (> number-of-X-tics 1) | |
21667 | (insert X-axis-tic-element) | |
21668 | (setq number-of-X-tics (1- number-of-X-tics)))) | |
21669 | @end group | |
21670 | @end smallexample | |
21671 | ||
21672 | @smallexample | |
21673 | @group | |
21674 | (defun X-axis-element (number) | |
21675 | "Construct a numbered X axis element." | |
21676 | (let ((leading-spaces | |
21677 | (- (* symbol-width X-axis-label-spacing) | |
21678 | (length (number-to-string number))))) | |
21679 | (concat (make-string leading-spaces ? ) | |
21680 | (number-to-string number)))) | |
21681 | @end group | |
21682 | @end smallexample | |
21683 | ||
21684 | @smallexample | |
21685 | @group | |
21686 | (defun graph-body-print (numbers-list height symbol-width) | |
21687 | "Print a bar graph of the NUMBERS-LIST. | |
21688 | The numbers-list consists of the Y-axis values. | |
21689 | HEIGHT is maximum height of graph. | |
21690 | SYMBOL-WIDTH is number of each column." | |
21691 | @end group | |
21692 | @group | |
21693 | (let (from-position) | |
21694 | (while numbers-list | |
21695 | (setq from-position (point)) | |
21696 | (insert-rectangle | |
21697 | (column-of-graph height (car numbers-list))) | |
21698 | (goto-char from-position) | |
21699 | (forward-char symbol-width) | |
21700 | @end group | |
21701 | @group | |
21702 | ;; @r{Draw graph column by column.} | |
21703 | (sit-for 0) | |
21704 | (setq numbers-list (cdr numbers-list))) | |
21705 | ;; @r{Place point for X axis labels.} | |
21706 | (forward-line height) | |
21707 | (insert "\n"))) | |
21708 | @end group | |
21709 | @end smallexample | |
21710 | ||
21711 | @smallexample | |
21712 | @group | |
21713 | (defun Y-axis-column | |
21714 | (height width-of-label &optional vertical-step) | |
21715 | "Construct list of labels for Y axis. | |
21716 | HEIGHT is maximum height of graph. | |
21717 | WIDTH-OF-LABEL is maximum width of label. | |
21718 | @end group | |
21719 | @group | |
21720 | VERTICAL-STEP, an option, is a positive integer | |
21721 | that specifies how much a Y axis label increments | |
21722 | for each line. For example, a step of 5 means | |
21723 | that each line is five units of the graph." | |
21724 | (let (Y-axis | |
21725 | (number-per-line (or vertical-step 1))) | |
21726 | @end group | |
21727 | @group | |
21728 | (while (> height 1) | |
21729 | (if (zerop (% height Y-axis-label-spacing)) | |
21730 | ;; @r{Insert label.} | |
21731 | (setq Y-axis | |
21732 | (cons | |
21733 | (Y-axis-element | |
21734 | (* height number-per-line) | |
21735 | width-of-label) | |
21736 | Y-axis)) | |
21737 | @end group | |
21738 | @group | |
21739 | ;; @r{Else, insert blanks.} | |
21740 | (setq Y-axis | |
21741 | (cons | |
21742 | (make-string width-of-label ? ) | |
21743 | Y-axis))) | |
21744 | (setq height (1- height))) | |
21745 | @end group | |
21746 | @group | |
21747 | ;; @r{Insert base line.} | |
21748 | (setq Y-axis (cons (Y-axis-element | |
21749 | (or vertical-step 1) | |
21750 | width-of-label) | |
21751 | Y-axis)) | |
21752 | (nreverse Y-axis))) | |
21753 | @end group | |
21754 | @end smallexample | |
21755 | ||
21756 | @smallexample | |
21757 | @group | |
21758 | (defun print-X-axis-numbered-line | |
21759 | (number-of-X-tics X-axis-leading-spaces | |
21760 | &optional horizontal-step) | |
21761 | "Print line of X-axis numbers" | |
21762 | (let ((number X-axis-label-spacing) | |
21763 | (horizontal-step (or horizontal-step 1))) | |
21764 | @end group | |
21765 | @group | |
21766 | (insert X-axis-leading-spaces) | |
21767 | ;; line up number | |
21768 | (delete-char (- (1- (length (number-to-string horizontal-step))))) | |
21769 | (insert (concat | |
21770 | (make-string | |
21771 | ;; @r{Insert white space up to next number.} | |
21772 | (- (* symbol-width X-axis-label-spacing) | |
21773 | (1- (length (number-to-string horizontal-step))) | |
21774 | 2) | |
21775 | ? ) | |
21776 | (number-to-string (* number horizontal-step)))) | |
21777 | @end group | |
21778 | @group | |
21779 | ;; @r{Insert remaining numbers.} | |
21780 | (setq number (+ number X-axis-label-spacing)) | |
21781 | (while (> number-of-X-tics 1) | |
21782 | (insert (X-axis-element (* number horizontal-step))) | |
21783 | (setq number (+ number X-axis-label-spacing)) | |
21784 | (setq number-of-X-tics (1- number-of-X-tics))))) | |
21785 | @end group | |
21786 | @end smallexample | |
21787 | ||
21788 | @smallexample | |
21789 | @group | |
21790 | (defun print-X-axis (numbers-list horizontal-step) | |
21791 | "Print X axis labels to length of NUMBERS-LIST. | |
21792 | Optionally, HORIZONTAL-STEP, a positive integer, | |
21793 | specifies how much an X axis label increments for | |
21794 | each column." | |
21795 | @end group | |
21796 | @group | |
21797 | ;; Value of symbol-width and full-Y-label-width | |
21798 | ;; are passed by `print-graph'. | |
21799 | (let* ((leading-spaces | |
21800 | (make-string full-Y-label-width ? )) | |
21801 | ;; symbol-width @r{is provided by} graph-body-print | |
21802 | (tic-width (* symbol-width X-axis-label-spacing)) | |
21803 | (X-length (length numbers-list)) | |
21804 | @end group | |
21805 | @group | |
21806 | (X-tic | |
21807 | (concat | |
21808 | (make-string | |
21809 | ;; @r{Make a string of blanks.} | |
21810 | (- (* symbol-width X-axis-label-spacing) | |
21811 | (length X-axis-tic-symbol)) | |
21812 | ? ) | |
21813 | @end group | |
21814 | @group | |
21815 | ;; @r{Concatenate blanks with tic symbol.} | |
21816 | X-axis-tic-symbol)) | |
21817 | (tic-number | |
21818 | (if (zerop (% X-length tic-width)) | |
21819 | (/ X-length tic-width) | |
21820 | (1+ (/ X-length tic-width))))) | |
21821 | @end group | |
21822 | ||
21823 | @group | |
21824 | (print-X-axis-tic-line | |
21825 | tic-number leading-spaces X-tic) | |
21826 | (insert "\n") | |
21827 | (print-X-axis-numbered-line | |
21828 | tic-number leading-spaces horizontal-step))) | |
21829 | @end group | |
21830 | @end smallexample | |
21831 | ||
21832 | @smallexample | |
21833 | @group | |
21834 | (defun one-fiftieth (full-range) | |
21835 | "Return list, each number of which is 1/50th previous." | |
d1069532 | 21836 | (mapcar (lambda (arg) (/ arg 50)) full-range)) |
8cda6f8f GM |
21837 | @end group |
21838 | @end smallexample | |
21839 | ||
21840 | @smallexample | |
21841 | @group | |
21842 | (defun print-graph | |
21843 | (numbers-list &optional vertical-step horizontal-step) | |
09e80d9f | 21844 | "Print labeled bar graph of the NUMBERS-LIST. |
8cda6f8f GM |
21845 | The numbers-list consists of the Y-axis values. |
21846 | @end group | |
21847 | ||
21848 | @group | |
21849 | Optionally, VERTICAL-STEP, a positive integer, | |
21850 | specifies how much a Y axis label increments for | |
21851 | each line. For example, a step of 5 means that | |
21852 | each row is five units. | |
21853 | @end group | |
21854 | ||
21855 | @group | |
21856 | Optionally, HORIZONTAL-STEP, a positive integer, | |
21857 | specifies how much an X axis label increments for | |
21858 | each column." | |
21859 | (let* ((symbol-width (length graph-blank)) | |
21860 | ;; @code{height} @r{is both the largest number} | |
21861 | ;; @r{and the number with the most digits.} | |
21862 | (height (apply 'max numbers-list)) | |
21863 | @end group | |
21864 | @group | |
21865 | (height-of-top-line | |
21866 | (if (zerop (% height Y-axis-label-spacing)) | |
21867 | height | |
21868 | ;; @r{else} | |
21869 | (* (1+ (/ height Y-axis-label-spacing)) | |
21870 | Y-axis-label-spacing))) | |
21871 | @end group | |
21872 | @group | |
21873 | (vertical-step (or vertical-step 1)) | |
21874 | (full-Y-label-width | |
21875 | (length | |
21876 | (concat | |
21877 | (number-to-string | |
21878 | (* height-of-top-line vertical-step)) | |
21879 | Y-axis-tic)))) | |
21880 | @end group | |
21881 | @group | |
21882 | ||
21883 | (print-Y-axis | |
21884 | height-of-top-line full-Y-label-width vertical-step) | |
21885 | (graph-body-print | |
21886 | numbers-list height-of-top-line symbol-width) | |
21887 | (print-X-axis numbers-list horizontal-step))) | |
21888 | @end group | |
21889 | @end smallexample | |
21890 | @c qqq | |
21891 | @end ignore | |
21892 | ||
21893 | @page | |
d6adf7e7 | 21894 | @node Final printed graph |
8cda6f8f GM |
21895 | @appendixsubsec The Printed Graph |
21896 | ||
21897 | When made and installed, you can call the @code{print-graph} command | |
21898 | like this: | |
21899 | @sp 1 | |
21900 | ||
21901 | @smallexample | |
21902 | @group | |
21903 | (print-graph fiftieth-list-for-graph 50 10) | |
21904 | @end group | |
21905 | @end smallexample | |
21906 | @sp 1 | |
21907 | ||
21908 | @noindent | |
21909 | Here is the graph: | |
21910 | @sp 2 | |
21911 | ||
21912 | @smallexample | |
21913 | @group | |
21914 | 1000 - * | |
21915 | ** | |
21916 | ** | |
21917 | ** | |
21918 | ** | |
21919 | 750 - *** | |
21920 | *** | |
21921 | *** | |
21922 | *** | |
21923 | **** | |
21924 | 500 - ***** | |
21925 | ****** | |
21926 | ****** | |
21927 | ****** | |
21928 | ******* | |
21929 | 250 - ******** | |
21930 | ********* * | |
21931 | *********** * | |
21932 | ************* * | |
21933 | 50 - ***************** * * | |
21934 | | | | | | | | | | |
21935 | 10 50 100 150 200 250 300 350 | |
21936 | @end group | |
21937 | @end smallexample | |
21938 | ||
21939 | @sp 2 | |
21940 | ||
21941 | @noindent | |
f99f1641 | 21942 | The largest group of functions contain 10--19 words and symbols each. |
8cda6f8f | 21943 | |
d6adf7e7 | 21944 | @node Free Software and Free Manuals |
8cda6f8f GM |
21945 | @appendix Free Software and Free Manuals |
21946 | ||
21947 | @strong{by Richard M. Stallman} | |
21948 | @sp 1 | |
21949 | ||
21950 | The biggest deficiency in free operating systems is not in the | |
21951 | software---it is the lack of good free manuals that we can include in | |
21952 | these systems. Many of our most important programs do not come with | |
21953 | full manuals. Documentation is an essential part of any software | |
21954 | package; when an important free software package does not come with a | |
21955 | free manual, that is a major gap. We have many such gaps today. | |
21956 | ||
21957 | Once upon a time, many years ago, I thought I would learn Perl. I got | |
21958 | a copy of a free manual, but I found it hard to read. When I asked | |
21959 | Perl users about alternatives, they told me that there were better | |
21960 | introductory manuals---but those were not free. | |
21961 | ||
21962 | Why was this? The authors of the good manuals had written them for | |
21963 | O'Reilly Associates, which published them with restrictive terms---no | |
21964 | copying, no modification, source files not available---which exclude | |
21965 | them from the free software community. | |
21966 | ||
21967 | That wasn't the first time this sort of thing has happened, and (to | |
21968 | our community's great loss) it was far from the last. Proprietary | |
21969 | manual publishers have enticed a great many authors to restrict their | |
21970 | manuals since then. Many times I have heard a GNU user eagerly tell me | |
21971 | about a manual that he is writing, with which he expects to help the | |
21972 | GNU project---and then had my hopes dashed, as he proceeded to explain | |
21973 | that he had signed a contract with a publisher that would restrict it | |
21974 | so that we cannot use it. | |
21975 | ||
21976 | Given that writing good English is a rare skill among programmers, we | |
21977 | can ill afford to lose manuals this way. | |
21978 | ||
8cda6f8f GM |
21979 | Free documentation, like free software, is a matter of freedom, not |
21980 | price. The problem with these manuals was not that O'Reilly Associates | |
31b62755 GM |
21981 | charged a price for printed copies---that in itself is fine. The Free |
21982 | Software Foundation @uref{http://shop.fsf.org, sells printed copies} of | |
21983 | free @uref{http://www.gnu.org/doc/doc.html, GNU manuals}, too. | |
8cda6f8f GM |
21984 | But GNU manuals are available in source code form, while these manuals |
21985 | are available only on paper. GNU manuals come with permission to copy | |
21986 | and modify; the Perl manuals do not. These restrictions are the | |
21987 | problems. | |
21988 | ||
21989 | The criterion for a free manual is pretty much the same as for free | |
21990 | software: it is a matter of giving all users certain | |
21991 | freedoms. Redistribution (including commercial redistribution) must be | |
21992 | permitted, so that the manual can accompany every copy of the program, | |
21993 | on-line or on paper. Permission for modification is crucial too. | |
21994 | ||
21995 | As a general rule, I don't believe that it is essential for people to | |
21996 | have permission to modify all sorts of articles and books. The issues | |
21997 | for writings are not necessarily the same as those for software. For | |
21998 | example, I don't think you or I are obliged to give permission to | |
21999 | modify articles like this one, which describe our actions and our | |
22000 | views. | |
22001 | ||
22002 | But there is a particular reason why the freedom to modify is crucial | |
22003 | for documentation for free software. When people exercise their right | |
22004 | to modify the software, and add or change its features, if they are | |
22005 | conscientious they will change the manual too---so they can provide | |
22006 | accurate and usable documentation with the modified program. A manual | |
22007 | which forbids programmers to be conscientious and finish the job, or | |
22008 | more precisely requires them to write a new manual from scratch if | |
22009 | they change the program, does not fill our community's needs. | |
22010 | ||
22011 | While a blanket prohibition on modification is unacceptable, some | |
22012 | kinds of limits on the method of modification pose no problem. For | |
22013 | example, requirements to preserve the original author's copyright | |
22014 | notice, the distribution terms, or the list of authors, are ok. It is | |
22015 | also no problem to require modified versions to include notice that | |
22016 | they were modified, even to have entire sections that may not be | |
22017 | deleted or changed, as long as these sections deal with nontechnical | |
22018 | topics. (Some GNU manuals have them.) | |
22019 | ||
22020 | These kinds of restrictions are not a problem because, as a practical | |
22021 | matter, they don't stop the conscientious programmer from adapting the | |
22022 | manual to fit the modified program. In other words, they don't block | |
22023 | the free software community from making full use of the manual. | |
22024 | ||
22025 | However, it must be possible to modify all the technical content of | |
22026 | the manual, and then distribute the result in all the usual media, | |
22027 | through all the usual channels; otherwise, the restrictions do block | |
22028 | the community, the manual is not free, and so we need another manual. | |
22029 | ||
22030 | Unfortunately, it is often hard to find someone to write another | |
22031 | manual when a proprietary manual exists. The obstacle is that many | |
22032 | users think that a proprietary manual is good enough---so they don't | |
22033 | see the need to write a free manual. They do not see that the free | |
22034 | operating system has a gap that needs filling. | |
22035 | ||
22036 | Why do users think that proprietary manuals are good enough? Some have | |
22037 | not considered the issue. I hope this article will do something to | |
22038 | change that. | |
22039 | ||
22040 | Other users consider proprietary manuals acceptable for the same | |
22041 | reason so many people consider proprietary software acceptable: they | |
22042 | judge in purely practical terms, not using freedom as a | |
22043 | criterion. These people are entitled to their opinions, but since | |
22044 | those opinions spring from values which do not include freedom, they | |
22045 | are no guide for those of us who do value freedom. | |
22046 | ||
22047 | Please spread the word about this issue. We continue to lose manuals | |
22048 | to proprietary publishing. If we spread the word that proprietary | |
22049 | manuals are not sufficient, perhaps the next person who wants to help | |
22050 | GNU by writing documentation will realize, before it is too late, that | |
22051 | he must above all make it free. | |
22052 | ||
22053 | We can also encourage commercial publishers to sell free, copylefted | |
22054 | manuals instead of proprietary ones. One way you can help this is to | |
22055 | check the distribution terms of a manual before you buy it, and prefer | |
22056 | copylefted manuals to non-copylefted ones. | |
22057 | ||
22058 | @sp 2 | |
22059 | @noindent | |
22060 | Note: The Free Software Foundation maintains a page on its Web site | |
22061 | that lists free books available from other publishers:@* | |
22062 | @uref{http://www.gnu.org/doc/other-free-books.html} | |
22063 | ||
d6adf7e7 | 22064 | @node GNU Free Documentation License |
8cda6f8f GM |
22065 | @appendix GNU Free Documentation License |
22066 | ||
22067 | @cindex FDL, GNU Free Documentation License | |
e41dfb1e | 22068 | @include doclicense.texi |
8cda6f8f | 22069 | |
d6adf7e7 | 22070 | @node Index |
8cda6f8f GM |
22071 | @unnumbered Index |
22072 | ||
22073 | @ignore | |
22074 | MENU ENTRY: NODE NAME. | |
22075 | @end ignore | |
22076 | ||
22077 | @printindex cp | |
22078 | ||
22079 | @iftex | |
22080 | @c Place biographical information on right-hand (verso) page | |
22081 | ||
22082 | @tex | |
a9097c6d | 22083 | \par\vfill\supereject |
8cda6f8f | 22084 | \ifodd\pageno |
8cda6f8f GM |
22085 | \global\evenheadline={\hfil} \global\evenfootline={\hfil} |
22086 | \global\oddheadline={\hfil} \global\oddfootline={\hfil} | |
a9097c6d | 22087 | %\page\hbox{}\page |
8cda6f8f | 22088 | \else |
a9097c6d | 22089 | % \par\vfill\supereject |
8cda6f8f GM |
22090 | \global\evenheadline={\hfil} \global\evenfootline={\hfil} |
22091 | \global\oddheadline={\hfil} \global\oddfootline={\hfil} | |
a9097c6d KB |
22092 | %\page\hbox{}%\page |
22093 | %\page\hbox{}%\page | |
8cda6f8f GM |
22094 | \fi |
22095 | @end tex | |
22096 | ||
a9097c6d | 22097 | @c page |
8cda6f8f GM |
22098 | @w{ } |
22099 | ||
22100 | @c ================ Biographical information ================ | |
22101 | ||
22102 | @w{ } | |
22103 | @sp 8 | |
22104 | @center About the Author | |
22105 | @sp 1 | |
22106 | @end iftex | |
22107 | ||
22108 | @ifnottex | |
d6adf7e7 | 22109 | @node About the Author |
8cda6f8f GM |
22110 | @unnumbered About the Author |
22111 | @end ifnottex | |
22112 | ||
22113 | @quotation | |
22114 | Robert J. Chassell has worked with GNU Emacs since 1985. He writes | |
22115 | and edits, teaches Emacs and Emacs Lisp, and speaks throughout the | |
22116 | world on software freedom. Chassell was a founding Director and | |
22117 | Treasurer of the Free Software Foundation, Inc. He is co-author of | |
22118 | the @cite{Texinfo} manual, and has edited more than a dozen other | |
22119 | books. He graduated from Cambridge University, in England. He has an | |
22120 | abiding interest in social and economic history and flies his own | |
22121 | airplane. | |
22122 | @end quotation | |
22123 | ||
a9097c6d KB |
22124 | @c @page |
22125 | @c @w{ } | |
22126 | @c | |
22127 | @c @c Prevent page number on blank verso, so eject it first. | |
22128 | @c @tex | |
22129 | @c \par\vfill\supereject | |
22130 | @c @end tex | |
22131 | ||
22132 | @c @iftex | |
22133 | @c @headings off | |
22134 | @c @evenheading @thispage @| @| @thistitle | |
22135 | @c @oddheading @| @| @thispage | |
22136 | @c @end iftex | |
8cda6f8f GM |
22137 | |
22138 | @bye |